ladybug.wea module

class ladybug.wea.Wea(location, direct_normal_irradiance, diffuse_horizontal_irradiance)[source]

Bases: object

A WEA object containing hourly or sub-hourly solar irradiance.

This object and its corresponding .wea file type is what the Radiance gendaymtx function uses to generate the sky.

Parameters:

  • location – Ladybug location object.

  • direct_normal_irradiance – A HourlyContinuousCollection or a HourlyDiscontinuousCollection for direct normal irradiance. The collection must be aligned with the diffuse_horizontal_irradiance.

  • diffuse_horizontal_irradiance – A HourlyContinuousCollection or a HourlyDiscontinuousCollection for diffuse horizontal irradiance, The collection must be aligned with the direct_normal_irradiance.

Properties:

  • location

  • direct_normal_irradiance

  • diffuse_horizontal_irradiance

  • direct_horizontal_irradiance

  • global_horizontal_irradiance

  • enforce_on_hour

  • datetimes

  • hoys

  • analysis_period

  • timestep

  • is_leap_year

  • is_continuous

  • is_annual

  • header

ToString()[source]

Overwrite .NET ToString.

static count_timesteps(wea_file)[source]

Count the number of timesteps represented within a Wea file.

This is useful in workflows where one needs to compute cumulative values over a Wea (eg. cumulative radiation).

Parameters:

wea_file – Full path to .wea file.

Returns:

integer for the number of timesteps in the Wea.

directional_irradiance(altitude=90, azimuth=180, ground_reflectance=0.2, isotropic=True)[source]

Get the irradiance components for a surface facing a given direction.

Note this method computes unobstructed solar flux facing a given altitude and azimuth. The default is set to return the global horizontal irradiance, assuming an altitude facing straight up (90 degrees).

Parameters:

  • altitude – A number between -90 and 90 that represents the altitude at which irradiance is being evaluated in degrees.

  • azimuth – A number between 0 and 360 that represents the azimuth at which irradiance is being evaluated in degrees.

  • ground_reflectance –

    A number between 0 and 1 that represents the reflectance of the ground. Default is set to 0.2. Some common ground reflectances are:

    • urban: 0.18

    • grass: 0.20

    • fresh grass: 0.26

    • soil: 0.17

    • sand: 0.40

    • snow: 0.65

    • fresh_snow: 0.75

    • asphalt: 0.12

    • concrete: 0.30

    • sea: 0.06

  • isotropic – A boolean value that sets whether an isotropic sky is used (as opposed to an anisotropic sky). An isotropic sky assumes an even distribution of diffuse irradiance across the sky while an anisotropic sky places more diffuse irradiance near the solar disc. (Default: True).

Returns:

A tuple of four elements

  • total_irradiance: A data collection of total solar irradiance.

  • direct_irradiance: A data collection of direct solar irradiance.

  • diffuse_irradiance: A data collection of diffuse sky solar irradiance.

  • reflected_irradiance: A data collection of ground reflected solar irradiance.

duplicate()[source]

Duplicate location.

estimate_illuminance_components(dew_point)[source]

Get estimated direct, diffuse, and global illuminance from this Wea.

Note that this method should only be used when there are no measured illuminance values that correspond to this Wea’s irradiance values. Because the illuminance components calculated here are simply estimated using a model by Perez [1], they are not as accurate as true measured values.

Note

[1] Perez R. (1990). ‘Modeling Daylight Availability and Irradiance Components from Direct and Global Irradiance’. Solar Energy. Vol. 44. No. 5, pp. 271-289. USA.

Parameters:

dew_point – A data collection of dewpoint temperature in degrees C. This data collection must align with the irradiance data on this object.

Returns:

A tuple with four elements

  • global_horiz_ill: Data collection of Global Horizontal Illuminance in lux.

  • direct_normal_ill: Data collection of Direct Normal Illuminance in lux.

  • diffuse_horizontal_ill: Data collection of Diffuse Horizontal Illuminance in lux.

  • zenith_lum: Data collection of Zenith Luminance in lux.

filter_by_analysis_period(analysis_period)[source]

Create a new filtered Wea from this Wea based on an analysis period.

Parameters:

period (analysis) – A Ladybug analysis period.

Returns:

A new Wea filtered by the analysis period.

filter_by_hoys(hoys)[source]

Create a new filtered Wea from this Wea using a list of hours of the year.

Parameters:

hoys – A List of hours of the year 0..8759.

Returns:

A new Wea with filtered data.

filter_by_moys(moys)[source]

Create a new filtered Wea from this Wea based on a list of minutes of the year.

Parameters:

moys – A List of minutes of the year [0..8759 * 60].

Returns:

A new Wea with filtered data.

filter_by_pattern(pattern)[source]

Create a new filtered Wea from this Wea using a list of booleans.

Parameters:

pattern – An array of True/False values. This array should usually have a length matching the number of irradiance values in the Wea but it can also be a pattern to be repeated over the data.

Returns:

A new Wea filtered by the analysis period.

filter_by_sun_up(min_altitude=0)[source]

Create a new filtered Wea from this Wea based on whether the sun is up

Parameters:

min_altitude – A number for the minimum altitude above the horizon at which the sun is considered up in degrees. Setting this to 0 will filter values for all hours where the sun is physically above the horizon. By setting this to a negative number (eg. -6), various levels of twilight can be used to filter the data (eg. civil twilight). Positive numbers can be used to discount low sun angles (Default: 0).

Returns:

A new Wea with filtered data.

classmethod from_annual_values(location, direct_normal_irradiance, diffuse_horizontal_irradiance, timestep=1, is_leap_year=False)[source]

Create an annual Wea from an array of irradiance values.

Parameters:

  • location – Ladybug location object.

  • direct_normal_irradiance – An array of values for direct normal irradiance. The length of this list should be same as diffuse_horizontal_irradiance and should represent an entire year of values at the input timestep.

  • diffuse_horizontal_irradiance – A HourlyContinuousCollection or a HourlyDiscontinuousCollection for diffuse horizontal irradiance, The collection must be aligned with the direct_normal_irradiance.

  • timestep – An integer to set the number of time steps per hour. Default is 1 for one value per hour.

  • is_leap_year – A boolean to indicate if values are for a leap year. (Default: False).

classmethod from_ashrae_clear_sky(location, sky_clearness=1, timestep=1, is_leap_year=False)[source]

Create a wea object representing an original ASHRAE Clear Sky.

The original ASHRAE Clear Sky is intended to determine peak solar load and sizing parameters for HVAC systems. It is not the sky model currently recommended by ASHRAE since it usually overestimates the amount of solar irradiance in comparison to the newer ASHRAE Revised Clear Sky (“Tau Model”). However, the original model here is still useful for cases where monthly optical depth values are not known. For more information on the ASHRAE Clear Sky model, see the EnergyPlus Engineering Reference: https://bigladdersoftware.com/epx/docs/8-9/engineering-reference/climate-calculations.html

Parameters:

  • location – Ladybug location object.

  • sky_clearness – A factor that will be multiplied by the output of the model. This is to help account for locations where clear, dry skies predominate (e.g., at high elevations) or, conversely, where hazy and humid conditions are frequent. See Threlkeld and Jordan (1958) for recommended values. Typical values range from 0.95 to 1.05 and are usually never more than 1.2. Default is set to 1.0.

  • timestep – An optional integer to set the number of time steps per hour. Default is 1 for one value per hour.

  • is_leap_year – A boolean to indicate if values are for a leap year. (Default: False).

classmethod from_ashrae_revised_clear_sky(location, monthly_tau_beam, monthly_tau_diffuse, timestep=1, is_leap_year=False, use_2017=False)[source]

Create a wea object representing an ASHRAE Revised Clear Sky (“Tau Model”)

ASHRAE Revised Clear Skies are intended to determine peak solar load and sizing parameters for HVAC systems. The revised clear sky is currently the default recommended sky model used to autosize HVAC systems in EnergyPlus. For more information on the ASHRAE Revised Clear Sky model, see the EnergyPlus Engineering Reference: https://bigladdersoftware.com/epx/docs/23-2/engineering-reference/climate-calculations.html

Parameters:

  • location – Ladybug location object.

  • monthly_tau_beam – A list of 12 float values indicating the beam optical depth of the sky at each month of the year.

  • monthly_tau_diffuse – A list of 12 float values indicating the diffuse optical depth of the sky at each month of the year.

  • timestep – An optional integer to set the number of time steps per hour. Default is 1 for one value per hour.

  • is_leap_year – A boolean to indicate if values are for a leap year. (Default: False).

  • use_2017 – A boolean to indicate whether the version of the ASHRAE Tau model that should be the revised version published in 2017 (True) or the original one published in 2009 (False). (Default: False).

classmethod from_daysim_file(wea_file, timestep=1, is_leap_year=False)[source]

Create Wea object from a .wea file produced by DAYSIM.

Note that this method is only required when the .wea file generated from DAYSIM has a timestep greater than 1, which results in the file using times of day greater than 23:59. DAYSIM weas with a timestep of 1 can use the from_file method without issues.

Parameters:

  • wea_file – Full path to .wea file.

  • timestep – An optional integer to set the number of time steps per hour. Default is 1 for one value per hour.

  • is_leap_year – A boolean to indicate if values are for a leap year. (Default: False).

classmethod from_dict(data)[source]

Create Wea from a dictionary

Parameters:

data – A python dictionary in the following format

{
"type": "Wea",
"location": {},  # ladybug location dictionary
"direct_normal_irradiance": [],  # direct normal irradiance values
"diffuse_horizontal_irradiance": [],  # diffuse horizontal irradiance values
"timestep": 1,  # optional timestep between measurements
"is_leap_year": False,  # optional boolean for leap year
"datetimes": []  # array of datetime arrays; only required when not annual
}
classmethod from_epw_file(epw_file, timestep=1)[source]

Create a wea object using the solar irradiance values in an epw file.

Parameters:

  • epw_file – Full path to epw weather file.

  • timestep – An optional integer to set the number of time steps per hour. Default is 1 for one value per hour. Note that this input will only do a linear interpolation over the data in the EPW file. While such linear interpolations are suitable for most thermal simulations, where thermal lag “smooths over” the effect of momentary increases in solar energy, it is not recommended for daylight simulations, where momentary increases in solar energy can mean the difference between glare and visual comfort.

classmethod from_file(wea_file, timestep=1, is_leap_year=False)[source]

Create Wea object from a .wea file.

Parameters:

  • wea_file – Full path to .wea file.

  • timestep – An optional integer to set the number of time steps per hour. Default is 1 for one value per hour. If the wea file has a time step smaller than an hour, adjust this input accordingly.

  • is_leap_year – A boolean to indicate if values are for a leap year. (Default: False).

classmethod from_stat_file(statfile, timestep=1, is_leap_year=False, use_2017=False)[source]

Create an ASHRAE Revised Clear Sky Wea object from data in .stat file.

The .stat file must have monthly sky optical depths within it in order to create a Wea this way.

Parameters:

  • statfile – Full path to the .stat file.

  • timestep – An optional integer to set the number of time steps per hour. Default is 1 for one value per hour.

  • is_leap_year – A boolean to indicate if values are for a leap year. (Default: False).

  • use_2017 – A boolean to indicate whether the version of the ASHRAE Tau model that should be the revised version published in 2017 (True) or the original one published in 2009 (False). (Default: False).

classmethod from_zhang_huang_solar(location, cloud_cover, relative_humidity, dry_bulb_temperature, wind_speed, atmospheric_pressure=None, use_disc=False)[source]

Create a Wea object from climate data using the Zhang-Huang model.

The Zhang-Huang solar model was developed to estimate solar irradiance for weather stations that lack such values, which are typically colleted with a pyranometer. Using total cloud cover, dry-bulb temperature, relative humidity, and wind speed as inputs the Zhang-Huang estimates global horizontal irradiance by means of a regression model across these variables. For more information on the Zhang-Huang model, see the EnergyPlus Engineering Reference: https://bigladdersoftware.com/epx/docs/8-7/engineering-reference/climate-calculations.html#zhang-huang-solar-model

Parameters:

  • location – Ladybug location object.

  • cloud_cover – A hourly continuous data collection with values for the fraction of the sky dome covered in clouds (0 = clear; 1 = completely overcast).

  • relative_humidity – A hourly continuous data collection with values for the relative humidity in percent.

  • dry_bulb_temperature – A hourly continuous data collection with values for the dry bulb temperature in degrees Celsius.

  • wind_speed – A hourly continuous data collection with values for the wind speed in meters per second.

  • atmospheric_pressure – An optional hourly continuous data collection with values for the atmospheric pressure in Pa. If None, pressure at sea level will be used (101325 Pa). (Default: None)

  • use_disc – Boolean to note whether the original DISC model as opposed to the newer and more accurate DIRINT model. (Default: False).

get_irradiance_value(month, day, hour)[source]

Get direct and diffuse irradiance values for a point in time.

Parameters:

  • month – Integer for month of the year [1 - 12].

  • day – Integer for the day of the month [1 - 31].

  • hour – Float for hour of the day [0 - 23].

get_irradiance_value_for_hoy(hoy)[source]

Get direct and diffuse irradiance values for a hoy.

Parameters:

hoy – Float for hour of the year [0 - 8759].

static to_constant_value(wea_file, value=1000)[source]

Convert a Wea file to have a constant value for each datetime.

This is useful in workflows where hourly irradiance values are inconsequential to the analysis and one is only using the Wea as a format to pass location and datetime information (eg. for direct sun hours).

Parameters:

  • wea_file – Full path to .wea file.

  • value – The direct and diffuse irradiance value that will be written in for all datetimes of the Wea.

Returns:

Text string of Wea file contents with all irradiance values replaces with the input value.

to_dict()[source]

Get the Wea as a dictionary.

to_file_string()[source]

Get a text string for the entirety of the Wea file contents.

write(file_path, write_hours=False)[source]

Write the Wea object to a .wea file and return the file path.

Parameters:

  • file_path – Text string for the path to where the .wea file should be written.

  • write_hours – Boolean to note whether a .hrs file should be written next to the .wea file, which lists the hours of the year (hoys) contained within the .wea file.

property analysis_period

Get an AnalysisPeriod for the Wea data.

property datetimes

Get the datetimes in the Wea as a tuple of datetimes.

property diffuse_horizontal_irradiance

Get or set a hourly data collection for the diffuse horizontal irradiance.

property direct_horizontal_irradiance

Get a data collection for the direct irradiance on a horizontal surface.

Note that this is different from the direct_normal_irradiance needed to construct a Wea, which is NORMAL and not HORIZONTAL.

property direct_normal_irradiance

Get or set a hourly data collection for the direct normal irradiance.

property enforce_on_hour

Get or set a boolean for whether datetimes occur on the hour.

By default, datetimes will be on the half-hour whenever the Wea has a timestep of 1, which aligns best with epw data. Setting this property to True will force the datetimes to be on the hour. Note that this property has no effect when the Wea timestep is not 1.

property global_horizontal_irradiance

Get a data collection for the global horizontal irradiance.

property header

Get the Wea header as a string.

property hoys

Get the hours of the year in Wea as a tuple of floats.

property is_annual

Get a boolean for whether the irradiance data is for an entire year.

property is_continuous

Get a boolean for whether the irradiance data is continuous.

property is_leap_year

Get a boolean for whether the irradiance data is for a leap year.

property location

Get or set a Ladybug Location object for the Wea.

metadata
property timestep

Get the timesteps per hour of the Wea as an integer.