Skip to content

Solar Radiation#

smart_control.simulator.solar_radiation #

Solar Radiation Calculations for Building Simulation.

For computing irradiance components, solar position, and sky temperature.

BuildingInfo dataclass #

BuildingInfo(
    floor_plan_filepath: str = "",
    floor_plan_orientation: float = 0.0,
    lat: float = 37.4263,
    lon: float = -122.0349,
    time_zone: str = "US/Pacific",
    altitude: float | None = None,
)

Information about the building under control.

On construction, floor_plan_orientation is validated to be within [0, 360] degrees; a ValueError is raised otherwise.

Attributes:

Name Type Description
floor_plan_filepath str

Path to the building's floor-plan .npy file.
floor_plan_orientation float

Compass angle (degrees) of the floor-plan's "up" direction. 0 / 360 = North, 90 = East, 180 = South, 270 = West. Must be between 0 and 360 inclusive.
lat float

Latitude of the building in decimal degrees.
lon float

Longitude of the building in decimal degrees.
time_zone str

IANA time-zone string (e.g. "US/Pacific").
altitude float | None

Altitude above sea level in metres. When None pvlib will attempt to look it up automatically.

ExteriorRadiationData dataclass #

ExteriorRadiationData(
    timestamp: Timestamp,
    ambient_temp_k: float,
    sky_temp_k: float,
    irradiance: IrradianceComponents,
)

Full exterior radiation state for a single timestep.

Bundles the ambient dry-bulb temperature, sky temperature (for longwave radiation), and irradiance components (for shortwave radiation) so that the simulator can request all exterior radiation quantities in a single call to :meth:SolarRadiation.get_exterior_radiation.

Attributes:

Name Type Description
timestamp Timestamp

Pandas timestamp for the observation.
ambient_temp_k float

Outdoor dry-bulb temperature in Kelvin.
sky_temp_k float

Sky temperature in Kelvin (Clark & Allen formula). Used for exterior longwave radiative heat transfer (LWR).
irradiance IrradianceComponents

Shortwave irradiance components (GHI, DNI, DHI) and solar position. Used for solar gain through fenestrations.

IrradianceComponents dataclass #

IrradianceComponents(
    ghi: float,
    dni: float,
    dhi: float,
    solar_zenith: float,
    solar_azimuth: float,
    timestamp: Timestamp | None = None,
)

Irradiance components and solar position at a given timestamp.

Attributes:

Name Type Description
timestamp Timestamp | None

Pandas timestamp for the measurement. May be None when the timestamp is not available (e.g. when constructed from a weather controller that does not track it).
ghi float

Global Horizontal Irradiance in W/m². Total solar radiation received on a horizontal surface.
dni float

Direct Normal Irradiance in W/m². Solar radiation received perpendicular to the sun's rays.
dhi float

Diffuse Horizontal Irradiance in W/m². Solar radiation received on a horizontal surface from the sky (excluding direct beam).
solar_zenith float

Solar zenith angle in degrees (angle from vertical). 0 = sun directly overhead, 90 = sun at horizon.
solar_azimuth float

Solar azimuth angle in degrees (compass direction of the sun). 0 / 360 = North, 90 = East, 180 = South, 270 = West.

SolarRadiation #

SolarRadiation(
    building_info: BuildingInfo | None = None,
    weather_controller: BaseWeatherController | None = None,
    dewpoint_depression: float = 5.0,
    cloud_cover: float | None = None,
    cloud_cover_low: float | None = None,
    cloud_cover_high: float | None = None,
    irradiance_method: str = "clearsky",
)

Calculates solar radiation for a building location.

Combines a :class:simulator.weather_controller.BaseWeatherController with cloud-cover and irradiance-method settings to produce :class:IrradianceComponents and sky-temperature values.

Parameters:

Name Type Description Default
building_info BuildingInfo | None

Location metadata. Uses defaults (Mountain View, CA) if not provided.

 None
weather_controller BaseWeatherController | None

A weather controller instance used to obtain temperature (for sky-temperature calculations).

 None
dewpoint_depression float

Difference between dry-bulb and dew-point temperatures in K. Used when no dew-point sensor is available.

 5.0
cloud_cover float | None

Static cloud cover in percent (0–100). If None and no dynamic cloud cover is configured, the clearsky model is used.

 None
cloud_cover_low float | None

Low cloud cover in percent at midnight (dynamic mode).

 None
cloud_cover_high float | None

High cloud cover in percent at noon (dynamic mode).

 None
irradiance_method str

One of 'clearsky', 'linear', or 'campbell_norman'.

 'clearsky'

get_current_cloud_cover #

get_current_cloud_cover(timestamp: Timestamp) -> float

Return current cloud cover in percent (0–100).

Supports static, dynamic (sinusoidal), and clearsky (returns 0.0) modes.

Parameters:

Name Type Description Default
timestamp Timestamp

Pandas timestamp. If naive, will be localised to the building's timezone.

 required

Returns:

Type Description
float

Cloud cover in percent.

get_current_irradiance #

get_current_irradiance(timestamp: Timestamp) -> IrradianceComponents

Return current irradiance (GHI, DNI, DHI) in W/m².

Uses the clearsky model by default, or adjusts for cloud cover when configured.

Parameters:

Name Type Description Default
timestamp Timestamp

Pandas timestamp. If naive, will be localised to the building's timezone.

 required

Returns:

Type Description
IrradianceComponents

class:IrradianceComponents with GHI, DNI, DHI and solar position.

get_current_sky_temperature #

get_current_sky_temperature(timestamp: Timestamp) -> float

Return sky temperature in K using the Clark & Allen formula.

Requires weather_controller to have been set during construction so that the dry-bulb temperature can be obtained.

Parameters:

Name Type Description Default
timestamp Timestamp

Pandas timestamp. Passed as-is to the weather controller's get_current_temp method.

 required

Returns:

Type Description
float

Sky temperature in K.

Raises:

Type Description
ValueError

If no weather controller was provided.

get_exterior_radiation #

get_exterior_radiation(timestamp: Timestamp) -> ExteriorRadiationData

Return ambient temperature, sky temperature, and irradiance at once.

Convenience method for the simulator that needs all exterior radiation quantities (convection temperature, longwave sky temperature, and shortwave irradiance) in a single call per timestep.

Parameters:

Name Type Description Default
timestamp Timestamp

Pandas timestamp. If naive, will be localised to the building's timezone for irradiance and sky-temperature calculations. Passed as-is to weather_controller.get_current_temp().

 required

Returns:

Type Description
ExteriorRadiationData

class:ExteriorRadiationData with ambient_temp_k,
ExteriorRadiationData

sky_temp_k, and irradiance.

Raises:

Type Description
ValueError

If no weather controller was provided.

calculate_poa_irradiance #

calculate_poa_irradiance(
    irradiance_components: IrradianceComponents,
    surface_tilt: float,
    surface_azimuth: float,
    solar_zenith: float,
    solar_azimuth: float,
) -> float

Calculate plane-of-array (POA) global irradiance.

Converts horizontal irradiance components (GHI, DNI, DHI) to the irradiance incident on a tilted surface using pvlib's get_total_irradiance.

Parameters:

Name Type Description Default
irradiance_components IrradianceComponents

:class:IrradianceComponents with ghi, dni, and dhi fields (W/m²).

 required
surface_tilt float

Surface tilt angle from horizontal in degrees (0 = horizontal, 90 = vertical).

 required
surface_azimuth float

Surface azimuth angle in degrees (180 = south-facing in the Northern Hemisphere).

 required
solar_zenith float

Solar zenith angle in degrees.

 required
solar_azimuth float

Solar azimuth angle in degrees.

 required

Returns:

Type Description
float

POA global irradiance in W/m².

Examples:

irrad = IrradianceComponents(
    ghi=800.0, dni=700.0, dhi=100.0,
    solar_zenith=30.0, solar_azimuth=180.0,
)
poa = calculate_poa_irradiance(
    irrad,
    surface_tilt=30.0,
    surface_azimuth=180.0,
    solar_zenith=30.0,
    solar_azimuth=180.0,
)

get_replay_cloud_cover #

get_replay_cloud_cover(
    observation_responses: Sequence[object],
) -> Mapping[str, float]

Return cloud cover replays from past observations.

Parameters:

Name Type Description Default
observation_responses Sequence[object]

Sequence of ObservationResponse protos.

 required

Returns:

Type Description
Mapping[str, float]

Mapping from timestamp string to cloud cover in percent (0–100).
Mapping[str, float]

Entries missing the cloud_cover_sensor measurement default to 0.0
Mapping[str, float]

(clear sky).

get_replay_irradiance #

get_replay_irradiance(
    observation_responses: Sequence[object],
) -> Sequence[IrradianceComponents]

Extract irradiance data from past observation protos.

Iterates over observation_responses and reads the ghi_sensor, dni_sensor, and dhi_sensor measurements. Solar zenith and azimuth are set to 0.0 because they are not typically recorded in observation protos.

Parameters:

Name Type Description Default
observation_responses Sequence[object]

Sequence of ObservationResponse protos.

 required

Returns:

Type Description
Sequence[IrradianceComponents]

A list of :class:IrradianceComponents, one per observation.

get_replay_sky_temperature #

get_replay_sky_temperature(
    observation_responses: Sequence[object], dewpoint_depression: float = 5.0
) -> Mapping[str, float]

Return sky temperature replays from past observations.

Calculates sky temperature using Clark & Allen formula from dry-bulb temperature and dew point. If a dew-point sensor is not present in the observation, the dew point is estimated as dry_bulb - dewpoint_depression. Observations that lack a dry-bulb temperature are silently skipped.

Parameters:

Name Type Description Default
observation_responses Sequence[object]

Sequence of ObservationResponse protos.

 required
dewpoint_depression float

Difference between dry-bulb and dew-point temperatures in K. Used when no dew-point sensor is available.

 5.0

Returns:

Type Description
Mapping[str, float]

Mapping from timestamp string to sky temperature in Kelvin.

get_replay_temperatures #

get_replay_temperatures(
    observation_responses: Sequence[object],
) -> Mapping[str, float]

Return temperature replays from past observations.

Parameters:

Name Type Description Default
observation_responses Sequence[object]

Sequence of ObservationResponse protos.

 required

Returns:

Type Description
Mapping[str, float]

Mapping from timestamp string to temperature in Kelvin. Entries missing
Mapping[str, float]

the outside_air_temperature_sensor measurement are mapped to -1.0.