Source Code Reference for the CLI.

cli

Modules:

Name	Description
cli	Photovoltaic electricity generation potential for different technologies & configurations
formatting
irradiance
manual
plot
position
power
print
rich_help_panel_names	Structural components of the command line interface
series
surface
time	Important sun and solar surface geometry parameters in calculating the amount of solar radiation that reaches a particular location on the Earth's surface
utilities
write

power

Modules:

Name	Description
average_photon_energy
broadband	CLI module to calculate the photovoltaic power output over a
broadband_multiple_surfaces	CLI module to calculate the photovoltaic power output over a
energy_	energy
introduction
spectral

irradiance

Modules:

Name	Description
extraterrestrial
ground_reflected	CLI module to calculate the reflected irradiance component over a
introduction
kato_bands
limits
reflectivity

series

Modules:

Name	Description
inspect
introduction
plot
resample
select
uniplot

time

Important sun and solar surface geometry parameters in calculating the amount of solar radiation that reaches a particular location on the Earth's surface

Functions:

Name	Description
correction
equation_of_time
fractional_year
local
offset
solar_time	Calculate the solar time.

correction

correction()

Source code in pvgis/cli/time.py

@app.command(
    "correction",
    no_args_is_help=True,
    help=f"⦩ Calculate the time correction {NOT_IMPLEMENTED_CLI}",
)
def correction():
    """ """
    pass

equation_of_time

equation_of_time()

Source code in pvgis/cli/time.py

@app.command(
    "eot",
    no_args_is_help=True,
    help=f"⦩ Calculate the equation of time {NOT_IMPLEMENTED_CLI}",
)
def equation_of_time():
    """ """
    pass

fractional_year

fractional_year()

Source code in pvgis/cli/time.py

@app.command(
    "fractional-year",
    no_args_is_help=True,
    help=f"⦩ Calculate the fractional year {NOT_IMPLEMENTED_CLI}",
)
def fractional_year():
    """ """
    pass

local

local()

Source code in pvgis/cli/time.py

@app.command(
    "local",
    no_args_is_help=True,
    help=f"⦩ Calculate the local time {NOT_IMPLEMENTED_CLI}",
)
def local():
    """ """
    pass

offset

offset()

Source code in pvgis/cli/time.py

@app.command(
    "offset",
    no_args_is_help=True,
    help=f"⦩ Calculate the time offset {NOT_IMPLEMENTED_CLI}",
)
def offset():
    """ """
    pass

solar_time

solar_time(
    longitude: Annotated[float, typer_argument_longitude],
    timestamps: Annotated[
        DatetimeIndex, typer_argument_timestamps
    ] = str(now_utc_datetimezone()),
    start_time: Annotated[
        datetime | None, typer_option_start_time
    ] = None,
    periods: Annotated[
        int | None, typer_option_periods
    ] = None,
    frequency: Annotated[
        str | None, typer_option_frequency
    ] = None,
    end_time: Annotated[
        datetime | None, typer_option_end_time
    ] = None,
    timezone: Annotated[
        str | None, typer_option_timezone
    ] = None,
    random_timestamps: Annotated[
        bool, typer_option_random_timestamps
    ] = RANDOM_TIMESTAMPS_FLAG_DEFAULT,
    solar_time_model: Annotated[
        List[SolarTimeModel], typer_option_solar_time_model
    ] = [milne],
    angle_output_units: Annotated[
        str, typer_option_angle_output_units
    ] = ANGLE_OUTPUT_UNITS_DEFAULT,
    rounding_places: Annotated[
        int, typer_option_rounding_places
    ] = ROUNDING_PLACES_DEFAULT,
    csv: Annotated[
        Path, typer_option_csv
    ] = CSV_PATH_DEFAULT,
    dtype: Annotated[
        str, typer_option_dtype
    ] = DATA_TYPE_DEFAULT,
    array_backend: Annotated[
        str, typer_option_array_backend
    ] = ARRAY_BACKEND_DEFAULT,
    verbose: Annotated[
        int, typer_option_verbose
    ] = VERBOSE_LEVEL_DEFAULT,
    log: Annotated[
        int, typer_option_log
    ] = LOG_LEVEL_DEFAULT,
    fingerprint: Annotated[
        bool, typer_option_fingerprint
    ] = FINGERPRINT_FLAG_DEFAULT,
    index: Annotated[
        bool, typer_option_index
    ] = INDEX_IN_TABLE_OUTPUT_FLAG_DEFAULT,
    quiet: Annotated[
        bool, typer_option_quiet
    ] = QUIET_FLAG_DEFAULT,
)

Calculate the solar time.

1. Map the day of the year onto the circumference of a circle, essentially converting the day of the year into radians.

2. Approximate empirically the equation of time, which accounts for the elliptical shape of Earth's orbit and the tilt of its axis.

3. Calculate the solar time by adding the current hour of the year, the time offset from the equation of time, and the hour offset (likely a longitude-based correction).

Source code in pvgis/cli/time.py

@app.command("solar", no_args_is_help=True, help="⦩ Calculate the apparent solar time")
def solar_time(
    longitude: Annotated[float, typer_argument_longitude],
    timestamps: Annotated[DatetimeIndex, typer_argument_timestamps] = str(
        now_utc_datetimezone()
    ),
    start_time: Annotated[
        datetime | None, typer_option_start_time
    ] = None,  # Used by a callback function
    periods: Annotated[
        int | None, typer_option_periods
    ] = None,  # Used by a callback function
    frequency: Annotated[
        str | None, typer_option_frequency
    ] = None,  # Used by a callback function
    end_time: Annotated[
        datetime | None, typer_option_end_time
    ] = None,  # Used by a callback function
    timezone: Annotated[str | None, typer_option_timezone] = None,
    random_timestamps: Annotated[
        bool, typer_option_random_timestamps
    ] = RANDOM_TIMESTAMPS_FLAG_DEFAULT,  # Used by a callback function
    solar_time_model: Annotated[List[SolarTimeModel], typer_option_solar_time_model] = [
        SolarTimeModel.milne
    ],
    angle_output_units: Annotated[
        str, typer_option_angle_output_units
    ] = ANGLE_OUTPUT_UNITS_DEFAULT,
    rounding_places: Annotated[
        int, typer_option_rounding_places
    ] = ROUNDING_PLACES_DEFAULT,
    csv: Annotated[Path, typer_option_csv] = CSV_PATH_DEFAULT,
    dtype: Annotated[str, typer_option_dtype] = DATA_TYPE_DEFAULT,
    array_backend: Annotated[str, typer_option_array_backend] = ARRAY_BACKEND_DEFAULT,
    verbose: Annotated[int, typer_option_verbose] = VERBOSE_LEVEL_DEFAULT,
    log: Annotated[int, typer_option_log] = LOG_LEVEL_DEFAULT,
    fingerprint: Annotated[bool, typer_option_fingerprint] = FINGERPRINT_FLAG_DEFAULT,
    index: Annotated[bool, typer_option_index] = INDEX_IN_TABLE_OUTPUT_FLAG_DEFAULT,
    quiet: Annotated[bool, typer_option_quiet] = QUIET_FLAG_DEFAULT,
):
    """Calculate the solar time.

    1. Map the day of the year onto the circumference of a circle, essentially
    converting the day of the year into radians.

    2. Approximate empirically the equation of time, which accounts for the
    elliptical shape of Earth's orbit and the tilt of its axis.

    3. Calculate the solar time by adding the current hour of the year, the
    time offset from the equation of time, and the hour offset (likely a
    longitude-based correction).
    """
    # Note the input timestamp and timezone
    user_requested_timestamps = timestamps
    user_requested_timezone = timezone  # Set to UTC by the callback functon !
    timezone = utc_zoneinfo = ZoneInfo("UTC")
    logger.debug(
        f"Input time zone : {timezone}",
        alt=f"Input time zone : [code]{timezone}[/code]",
    )

    if timestamps.tz is None:
        timestamps = timestamps.tz_localize(utc_zoneinfo)
        logger.debug(
            f"Naive input timestamps\n({user_requested_timestamps})\nlocalized to UTC aware for all internal calculations :\n{timestamps}"
        )

    elif timestamps.tz != utc_zoneinfo:
        timestamps = timestamps.tz_convert(utc_zoneinfo)
        logger.debug(
            f"Input zone\n{user_requested_timezone}\n& timestamps :\n{user_requested_timestamps}\n\nconverted for all internal calculations to :\n{timestamps}",
            alt=f"Input zone : [code]{user_requested_timezone}[/code]\n& timestamps :\n{user_requested_timestamps}\n\nconverted for all internal calculations to :\n{timestamps}",
        )

    solar_time_models = select_models(
        SolarTimeModel, solar_time_model
    )  # Using a callback fails!

    solar_time_series = calculate_solar_time_series(
        longitude=longitude,
        timestamps=timestamps,
        timezone=timezone,
        solar_time_models=solar_time_models,
        dtype=dtype,
        array_backend=array_backend,
        verbose=verbose,
        log=log,
    )
    longitude = convert_float_to_degrees_if_requested(longitude, angle_output_units)

    if not quiet:
        from pvgis.cli.print.solar_time import print_solar_time_series_table

        print_solar_time_series_table(
            longitude=longitude,
            timestamps=timestamps,
            timezone=timezone,
            solar_time_series=solar_time_series,
            title="Solar Time Overview",
            rounding_places=rounding_places,
            index=index,
        )
    if csv:
        pass

position

Modules:

Name	Description
altitude	CLI module to calculate the solar altitude angle parameters over a
azimuth
declination	CLI module to calculate the solar declination angle for a location and moment in time.
event_time
hour_angle
incidence	CLI module to calculate the solar incidence angle for a solar surface at a
introduction
overview	CLI module to calculate and overview the solar position parameters over a
position	Important sun and solar surface position parameters in calculating the amount of solar radiation that reaches a particular location on the Earth's surface
shading	CLI module to calculate and overview the solar position parameters over a
zenith	CLI module to calculate the solar zenith angle for a location and a single moment in time.

surface

Functions:

Name	Description
introduction	A short primer on solar surface

introduction

introduction()

A short primer on solar surface

Source code in pvgis/cli/surface.py

@app.command(
    name="introduction",
    help="A short primer on solar surface",
    no_args_is_help=False,
)
def introduction():
    """A short primer on solar surface"""
    introduction = """
    The [code]surface[/code] command can help you calculate the optimal position of a solar surface.
    """
    console.print(introduction)