Skip to content
Login Register
Simulations Integrators AI Assistant AI Reports Pricing
Case Studies Podcast Docs
Login Register
View as Markdown llms.txt

Models

Latitude module-attribute 

Latitude = Annotated[float, Field(ge=-90, le=90)]

Latitude in degrees, from -90 to 90.

Longitude module-attribute 

Longitude = Annotated[float, Field(ge=-180, le=180)]

Longitude in degrees, from -180 to 180.

DataList module-attribute 

DataList = Annotated[list[float], Field(min_length=1)]

A non-empty list of floats.

Hour module-attribute 

Hour = Annotated[int, Field(ge=0, le=23)]

Hour of the day, 0 to 23.

Month module-attribute 

Month = Annotated[int, Field(ge=1, le=12)]

Month of the year, 1 to 12.

Day module-attribute 

Day = Annotated[int, Field(ge=1, le=31)]

Day of the month, 1 to 31.

Payload

Bases: BaseModel

Base class of the SDK's request payloads.

A payload is immutable and validated on creation. Unknown fields are rejected, and surrounding whitespace in strings is stripped. Fields are serialized under their kebab-case aliases by default; the alias and the Python field name are both accepted on input.

to_dict 

to_dict(*, by_alias: bool = True, exclude_none: bool = True) -> dict

Return the payload as a plain dict.

Parameters:

Name Type Description Default
by_alias bool

Use the wire (kebab-case) field names instead of the Python names.

 True
exclude_none bool

Leave out fields whose value is None.

 True

Returns:

Type Description
dict

The payload as built-in types.

to_json 

to_json(*, by_alias: bool = True, exclude_none: bool = True) -> str

Return the payload as a JSON string.

Parameters:

Name Type Description Default
by_alias bool

Use the wire (kebab-case) field names instead of the Python names.

 True
exclude_none bool

Leave out fields whose value is None.

 True

Returns:

Type Description
str

The payload as JSON.

to_gzip 

to_gzip()

Return the payload's JSON, UTF-8 encoded and gzip-compressed.

Returns:

Type Description
bytes

The compressed JSON of to_json().

TimePeriod

Bases: Payload

One analysis window, as the six integers the filter takes.

Warnings

A window is a date span with a daily hour range, not one continuous stretch of time: the hours the model counts. "1 March 08:00 to 30 September 18:00" selects hours 08 to 18 of every day from 1 March to 30 September. The hours are EPW local standard time: no daylight-saving hour is added or removed.

A window may cross the year end (for example 1 December to 28 February); it selects December, January and February of the typical year, in calendar order of the year.

Malformed values are refused: a month outside 1-12, an hour outside 0-23, a day outside its own month's length. The check happens before the tiles are built and acquired, and therefore before anything is billed.

A single-hour window (start == end) is valid: it selects one hour of each day in the date span.

Attributes:

Name Type Description
start_month int

First month of the window, 1 to 12.
start_day int

First day of the window, 1 to 31 and within the month's length. 29 February is accepted because the window carries no year.
start_hour int

First hour of the daily range, 0 to 23.
end_month int

Last month of the window, 1 to 12. A month before start_month crosses the year end.
end_day int

Last day of the window, 1 to 31 and within the month's length.
end_hour int

Last hour of the daily range, 0 to 23, inclusive.

Location

Bases: Payload

A point on Earth.

Attributes:

Name Type Description
latitude float

Latitude in degrees, from -90 to 90.
longitude float

Longitude in degrees, from -180 to 180.

WeatherDataPoint

Bases: Payload

One hourly weather record.

Each field is the EPW column of the same name, with the EPW column's units. Every field is optional and None means no reading. Numeric strings are converted to floats, and empty strings and the tokens null, none, na, n/a and nan become None. Unknown keys are ignored.

Warnings

The pre-0.10 key znithLuminance is still accepted for zenithLuminance with a DeprecationWarning.

Attributes:

Name Type Description
dryBulbTemperature (float, optional)

Dry-bulb air temperature.
dewPointTemperature (float, optional)

Dew-point temperature.
relativeHumidity (float, optional)

Relative humidity.
atmosphericStationPressure (float, optional)

Atmospheric pressure at the station.
extraterrestrialHorizontalRadiation (float, optional)

Extraterrestrial radiation on a horizontal surface.
extraterrestrialDirectNormalRadiation (float, optional)

Extraterrestrial direct normal radiation.
horizontalInfraredRadiationIntensity (float, optional)

Horizontal infrared radiation intensity from the sky.
globalHorizontalRadiation (float, optional)

Global horizontal radiation.
directNormalRadiation (float, optional)

Direct normal radiation.
diffuseHorizontalRadiation (float, optional)

Diffuse horizontal radiation.
globalHorizontalIlluminance (float, optional)

Global horizontal illuminance.
directNormalIlluminance (float, optional)

Direct normal illuminance.
diffuseHorizontalIlluminance (float, optional)

Diffuse horizontal illuminance.
zenithLuminance (float, optional)

Luminance at the zenith.
windDirection (float, optional)

Wind direction.
windSpeed (float, optional)

Wind speed.
totalSkyCover (float, optional)

Total sky cover.
opaqueSkyCover (float, optional)

Opaque sky cover.
visibility (float, optional)

Horizontal visibility.
ceilingHeight (float, optional)

Cloud ceiling height.
presentWeatherObservation (float, optional)

Present weather observation indicator.
presentWeatherCodes (float, optional)

Present weather codes.
precipitableWater (float, optional)

Precipitable water.
aerosolOpticalDepth (float, optional)

Aerosol optical depth.
snowDepth (float, optional)

Snow depth.
daysSinceLastSnowfall (float, optional)

Days since the last snowfall.
albedo (float, optional)

Ground albedo.
liquidPrecipitationDepth (float, optional)

Depth of liquid precipitation.
liquidPrecipitationQuantity (float, optional)

Quantity of liquid precipitation.

coerce_numeric_strings classmethod 

coerce_numeric_strings(v)
  • None stays None
  • numbers stay numbers
  • numeric strings -> float
  • empty strings -> None
  • 'null', 'na', 'nan' -> None
  • non-numeric strings -> ValueError

require_env 

require_env(name: str, defaultValue: Optional[str] = None) -> str

Read a required environment variable.

Parameters:

Name Type Description Default
name str

Name of the environment variable.

 required
defaultValue str

Value to use when the variable is unset. If omitted, an unset or empty variable is an error.

 None

Returns:

Type Description
str

The value of the variable.

Raises:

Type Description
RuntimeError

If the value is missing or empty.

to_camel_case 

to_camel_case(s: str) -> str

Convert a snake_case string to camelCase.

to_kebab_case 

to_kebab_case(s: str) -> str

Convert a snake_case string to kebab-case.

extract_weather_fields 

extract_weather_fields(
    weather_data: list[WeatherDataPoint], fields: list[str]
) -> dict[str, Any]

Extract the given fields from weather data points into flat lists.

A gap (None) in a requested field raises instead of being skipped, because skipping it would shorten that column and misalign it against every other array. For a complete weather window the output is the same as in 0.5.3.

Parameters:

Name Type Description Default
weather_data list of WeatherDataPoint

WeatherDataPoint instances, plain mapping rows (for example a dict from json.load of a weather file), or a mix of both. A mapping row is read through WeatherDataPoint itself, so it accepts the same column spellings, including the legacy znithLuminance alias.

 required
fields list of str

camelCase attribute names of WeatherDataPoint, for example ["diffuseHorizontalRadiation", "directNormalRadiation"].

 required

Returns:

Type Description
dict

Maps each requested field, converted to snake_case, to its list of float values.

Raises:

Type Description
ValueError

If a requested field has no reading in one of the points, or a mapping row is not a valid weather record.