ladybug.designday module

class ladybug.designday.ASHRAEClearSky(date, clearness=1, daylight_savings=False)[source]

Bases: _SkyCondition

An object representing an original ASHRAE Clear Sky.

Parameters

  • date – Ladybug Date object for the day of the year on which the design day occurs.

  • clearness – Value between 0 and 1.2 that will get multiplied by the model’s irradiance to correct for factors like elevation.

  • daylight_savings – Boolean to indicate whether daylight savings time is active. Default: False.

Properties:

  • date

  • clearness

  • daylight_savings

ToString()

Overwrite .NET ToString.

duplicate()

Get a copy of this object.

classmethod from_analysis_period(analysis_period, clearness=1, daylight_savings=False)[source]

“Initialize a ASHRAEClearSky from an analysis_period

classmethod from_dict(data)[source]

Create an ASHRAEClearSky condition from a dictionary.

Parameters

data – A python dictionary in the following format.

{
"type": "ASHRAEClearSky"
"date": [7, 21],
"clearness": 0.0  # float,
"daylight_savings": False  # bool
}
radiation_values(location, timestep=1)[source]

Get arrays of direct, diffuse, and global radiation at each timestep.

to_dict()[source]

Convert the ASHRAEClearSky to a dictionary.

SOLAR_MODELS = ('ASHRAEClearSky', 'ASHRAETau', 'ZhangHuang', 'Schedule')
beam_schedule
property clearness

Get or set the sky clearness.

property date

Get or set a Ladybug Date object for the date of the design day.

property daylight_savings

Get or set a boolean to indicate whether daylight savings time is active.

diffuse_schedule
property hourly_sky_cover

Lists of sky cover values in tenths.

class ladybug.designday.ASHRAETau(date, tau_b, tau_d, use_2017=False, daylight_savings=False)[source]

Bases: _SkyCondition

An object representing an ASHRAE Revised Clear Sky (Tau model).

Parameters

  • date – Ladybug Date object for the day of the year on which the design day occurs.

  • tau_b – Value for the beam optical depths. Typically found in .stat files.

  • tau_d – Value for the diffuse optical depth. Typically found in .stat files.

  • 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).

  • daylight_savings – Boolean to indicate whether daylight savings time is active. (Default: False).

Properties:

  • date

  • tau_b

  • tau_d

  • use_2017

  • daylight_savings

  • hourly_sky_cover

ToString()

Overwrite .NET ToString.

duplicate()

Get a copy of this object.

classmethod from_analysis_period(analysis_period, tau_b, tau_d, use_2017=False, daylight_savings=False)[source]

“Initialize a ASHRAETau sky condition from an analysis_period

classmethod from_dict(data)[source]

Create a ASHRAETau sky condition from a dictionary.

Parameters

data – A python dictionary in the following format.

{
"type": "ASHRAETau",
"date": [7, 21],
"tau_b": 0.0,  # float
"tau_d": 0.0,  # float
"use_2017": True,  # boolean for whether the 2017 model is used
"daylight_savings": False  # bool
}
radiation_values(location, timestep=1)[source]

Gat arrays of direct, diffuse, and global radiation at each timestep.

to_dict()[source]

Convert the Sky Condition to a dictionary.

SOLAR_MODELS = ('ASHRAEClearSky', 'ASHRAETau', 'ZhangHuang', 'Schedule')
beam_schedule
property date

Get or set a Ladybug Date object for the date of the design day.

property daylight_savings

Get or set a boolean to indicate whether daylight savings time is active.

diffuse_schedule
property hourly_sky_cover

Get a lists of hourly sky cover values in tenths.

property tau_b

Get or set the beam optical sky depth.

property tau_d

Get or set the diffuse optical sky depth.

property use_2017

Boolean for whether the version of the 2017 version of the ASHRAE Tau is used.

class ladybug.designday.DesignDay(name, day_type, location, dry_bulb_condition, humidity_condition, wind_condition, sky_condition)[source]

Bases: object

An object representing design day conditions.

Parameters

  • name – A text string to set the name of the design day

  • day_type – Choose from ‘SummerDesignDay’, ‘WinterDesignDay’ or other EnergyPlus days visible under the DAY_TYPES property of this object.

  • location – Location object for the design day.

  • dry_bulb_condition – Ladybug DryBulbCondition object.

  • humidity_condition – Ladybug HumidityCondition object.

  • wind_condition – Ladybug WindCondition object.

  • sky_condition – Ladybug SkyCondition object (either ASHRAEClearSky or ASHRAETau).

Properties:

  • name

  • day_type

  • location

  • dry_bulb_condition

  • humidity_condition

  • wind_condition

  • sky_condition

  • analysis_period

  • hourly_datetimes

  • hourly_dry_bulb

  • hourly_dew_point

  • hourly_relative_humidity

  • hourly_barometric_pressure

  • hourly_wind_speed

  • hourly_wind_direction

  • hourly_solar_radiation

  • hourly_sky_cover

  • hourly_horizontal_infrared

ToString()[source]

Overwrite .NET ToString.

duplicate()[source]

Get a copy of this object.

classmethod from_ashrae_dict_cooling(ashrae_dict, location, use_010=False, pressure=None, tau=None)[source]

Create a heating design day object from a ASHRAE HOF dictionary.

Parameters

  • ashrae_dict – A dictionary with 32 keys that match those in the COOLING_KEYS property of this object. Each key should correspond to a value.

  • location – Location object for the design day

  • use_010 – Boolean to denote what type of design day to create (wether it is a 1.0% or a 0.4% design day). Default is False for a 0.4% annual cooling design day

  • pressure – Atmospheric pressure in Pa that should be used in the creation of the humidity condition. Default is 101325 Pa for pressure at sea level.

  • tau – Optional tuple containing two values, which will set the sky condition to be a revised ASHRAE clear sky (Tau model). The first item of the tuple should be the tau beam value and the second is for the tau diffuse value. Default is None, which will default to the original ASHRAE Clear Sky.

classmethod from_ashrae_dict_heating(ashrae_dict, location, use_990=False, pressure=None)[source]

Create a heating design day object from a ASHRAE HOF dictionary.

Parameters

  • ashrae_dict – A dictionary with 15 keys that match those in the HEATING_KEYS property of this object. Each key should correspond to a value.

  • location – Location object for the design day

  • use_990 – Boolean to denote what type of design day to create (wether it is a 99.0% or a 99.6% design day). Default is False for a 99.6% annual heating design day

  • pressure – Atmospheric pressure in Pa that should be used in the creation of the humidity condition. Default is 101325 Pa for pressure at sea level.

classmethod from_design_day_properties(name, day_type, location, date, dry_bulb_max, dry_bulb_range, humidity_type, humidity_value, pressure, wind_speed, wind_dir, sky_model, sky_properties)[source]

Create a design day object from various key properties.

Parameters

  • name – A text string to set the name of the design day

  • day_type – Choose from ‘SummerDesignDay’, ‘WinterDesignDay’ or other EnergyPlus days

  • location – Location for the design day

  • date – Ladybug Date object for the design day.

  • dry_bulb_max – Maximum dry bulb temperature over the design day (in C).

  • dry_bulb_range – Dry bulb range over the design day (in C).

  • humidity_type – Type of humidity to use. Choose from Wetbulb, Dewpoint, HumidityRatio, Enthalpy

  • humidity_value – The value of the condition above.

  • pressure – Barometric pressure in Pa.

  • wind_speed – Wind speed over the design day in m/s.

  • wind_dir – Wind direction over the design day in degrees.

  • sky_model – Type of solar model to use. Choose from ASHRAEClearSky, ASHRAETau.

  • sky_properties – A list of properties describing the sky above. For ASHRAEClearSky this is a single value for clearness For ASHRAETau, this is the tau_beam and tau_diffuse

classmethod from_dict(data)[source]

Create a Design Day from a dictionary.

Parameters

data – A python dictionary in the following format

{
"type": "DesignDay",
"name": "",  # string
"day_type": "",  # string
"location": {},  # optional ladybug Location dictionary
"dry_bulb_condition": {},  # ladybug DryBulbCondition dictionary
"humidity_condition": {},  # ladybug HumidityCondition dictionary
"wind_condition": {},  # ladybug WindCondition dictionary
"sky_condition": {}  # ladybug ASHRAEClearSky or ASHRAETau dictionary
}
classmethod from_idf(idf_string, location)[source]

Initialize from an EnergyPlus IDF string of a SizingPeriod:DesignDay.

Parameters

  • idf_string – A full IDF string representing a SizingPeriod:DesignDay.

  • location – A Ladybug Location object, used to interpret the sky condition over the course of the design day.

to_dict(include_location=True)[source]

Convert the Design Day to a dictionary.

Parameters

include_location – If True, the location dictionary will be included in the returned dictionary. This ensures that the sky condition contained in any re-serialized design day can produce accurate radiation values. However, this location is not necessary when exporting design days for energy simulation since the EPW simulated with the model already contains location information. Default: True.

to_idf()[source]

Get this object as an EnergyPlus IDF SizingPeriod:DesignDay string.

COOLING_KEYS = ('Month', 'DBR', 'DB004', 'WB_DB004', 'DB010', 'WB_DB010', 'DB020', 'WB_DB020', 'WB004', 'DB_WB004', 'WB010', 'DB_WB010', 'WB020', 'DB_WB020', 'WS_DB004', 'WD_DB004', 'DP004', 'HR_DP004', 'DB_DP004', 'DP010', 'HR_DP010', 'DB_DP010', 'DP020', 'HR_DP020', 'DB_DP020', 'EN004', 'DB_EN004', 'EN010', 'DB_EN010', 'EN020', 'DB_EN020', 'Hrs_8-4_&_DB')
DAY_TYPES = ('SummerDesignDay', 'WinterDesignDay', 'Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Holiday', 'CustomDay1', 'CustomDay2')
EXTREME_KEYS = ('WS010', 'WS025', 'WS050', 'WBmax', 'DBmin_mean', 'DBmax_mean', 'DBmin_stddev', 'DBmax_stddev', 'DBmin05years', 'DBmax05years', 'DBmin10years', 'DBmax10years', 'DBmin20years', 'DBmax20years', 'DBmin50years', 'DBmax50years')
HEATING_KEYS = ('Month', 'DB996', 'DB990', 'DP996', 'HR_DP996', 'DB_DP996', 'DP990', 'HR_DP990', 'DB_DP990', 'WS004c', 'DB_WS004c', 'WS010c', 'DB_WS010c', 'WS_DB996', 'WD_DB996')
IDF_COMMENTS = ('!- Name', '!- Month', '!- Day of Month', '!- Day Type', '!- Max Dry-Bulb Temp {C}', '!- Daily Dry-Bulb Temp Range {C}', '!- Dry-Bulb Temp Range Modifier Type', '!- Dry-Bulb Temp Range Modifier Schedule Name', '!- Humidity Condition Type', '!- Wetbulb/Dewpoint at Max Dry-Bulb {C}', '!- Humidity Indicating Day Schedule Name', '!- Humidity Ratio at Maximum Dry-Bulb {kgWater/kgDryAir}', '!- Enthalpy at Maximum Dry-Bulb {J/kg}', '!- Daily Wet-Bulb Temperature Range {deltaC}', '!- Barometric Pressure {Pa}', '!- Wind Speed {m/s}', '!- Wind Direction {Degrees; N=0, S=180}', '!- Rain {Yes/No}', '!- Snow on ground {Yes/No}', '!- Daylight Savings Time Indicator {Yes/No}', '!- Solar Model Indicator', '!- Beam Solar Day Schedule Name', '!- Diffuse Solar Day Schedule Name', '!- ASHRAE Clear Sky Beam Optical Depth (taub)', '!- ASHRAE Clear Sky Diffuse Optical Depth (taud)', '!- Clearness (0.0 to 1.2)')
property analysis_period

Get the analysisperiod of the design day.

property day_type

Get or set the type of design day.

property dry_bulb_condition

Get or set the dry bulb conditions.

property hourly_barometric_pressure

A data collection containing hourly barometric pressures over they day.

property hourly_datetimes

Get a list of hourly DateTime objects for the DesignDay.

property hourly_dew_point

A data collection containing hourly dew points over they day.

property hourly_dry_bulb

A data collection containing hourly dry bulb temperature over they day.

property hourly_horizontal_infrared

A data collection containing hourly horizontal infrared intensity in W/m2.

property hourly_relative_humidity

A data collection containing hourly relative humidity over they day.

property hourly_sky_cover

A data collection containing hourly sky cover values in tenths.

property hourly_solar_radiation

Three data collections containing hourly direct normal, diffuse horizontal, and global horizontal radiation.

property hourly_wind_direction

A data collection containing hourly wind directions over they day.

property hourly_wind_speed

A data collection containing hourly wind speeds over they day.

property humidity_condition

Get or set the humidity conditions.

property location

Get or set the location.

property name

Get or set the name.

property sky_condition

Get or set the sky conditions.

property wind_condition

Get or set the wind conditions.

class ladybug.designday.DryBulbCondition(dry_bulb_max, dry_bulb_range, modifier_type='DefaultMultipliers', modifier_schedule='')[source]

Bases: object

Represents dry bulb conditions on a design day.

Parameters

  • dry_bulb_max – The maximum dry bulb temperature on the design day [C].

  • dry_bulb_range – The difference between min and max temperatures on the design day [C].

  • modifier_type – Optional string for the type of modifier used to estimate temperature at a given timestep. Choose from the following: ‘DefaultMultipliers’, ‘MultiplierSchedule’, ‘DifferenceSchedule’, ‘TemperatureProfileSchedule’. Default: ‘DefaultMultipliers’

  • modifier_schedule – Optional text string for the name of the modifier schedule. Should be an empty string unless ‘MultiplierSchedule’ is selected as the modifier_type.

Properties:

  • dry_bulb_max

  • dry_bulb_range

  • modifier_type

  • modifier_schedule

  • hourly_values

ToString()[source]

Overwrite .NET ToString.

duplicate()[source]

Get a copy of this object.

classmethod from_dict(data)[source]

Create a Dry Bulb Condition from a dictionary.

Parameters

data – A python dictionary in the following format

{
"type": "DryBulbCondition",
"dry_bulb_max": 0.0,  # float
"dry_bulb_range": 0.0  # float
}
to_dict()[source]

Convert the Dry Bulb Condition to a dictionary.

HOURLY_MULTIPLIERS = (0.82, 0.88, 0.92, 0.95, 0.98, 1, 0.98, 0.91, 0.74, 0.55, 0.38, 0.23, 0.13, 0.05, 0, 0, 0.06, 0.14, 0.24, 0.39, 0.5, 0.59, 0.68, 0.75)
property dry_bulb_max

Get or set the max dry bulb temperature.

property dry_bulb_range

Get or set the dry bulb range over the day.

property hourly_values

Get a list of temperature values for each hour over the design day.

modifier_schedule
modifier_type
class ladybug.designday.HumidityCondition(humidity_type, humidity_value, barometric_pressure=101325, rain=False, snow_on_ground=False, schedule='', wet_bulb_range='')[source]

Bases: object

Represents humidity and precipitation conditions on the design day.

Parameters

  • humidity_type – Choose from: Wetbulb, Dewpoint, HumidityRatio, Enthalpy

  • humidity_value – The value correcponding to the humidity_type

  • barometric_pressure – Default is to use pressure at sea level

  • rain – Boolean to indicate rain on the design day. Default: False.

  • snow_on_ground – Boolean to indicate snow on the design day. Default: False.

  • schedule – Optional humidity schedule

  • wet_bulb_range – Optional wet bulb temperature range

Properties:

  • humidity_type

  • humidity_value

  • barometric_pressure

  • rain

  • snow_on_ground

  • schedule

  • wet_bulb_range

  • hourly_pressure

ToString()[source]

Overwrite .NET ToString.

dew_point(db)[source]

Get the dew point (C), which is constant throughout the day (except at saturation).

Parameters

db – The maximum dry bulb temperature over the day.

duplicate()[source]

Get a copy of this object.

classmethod from_dict(data)[source]

Create a Humidity Condition from a dictionary.

Parameters

data – A python dictionary in the following format

{
"type": "HumidityCondition",
"humidity_type": "",  # string
"humidity_value": 0.0,  # float
"barometric_pressure": 0.0,  # float
"rain": False,  # bool
"snow_on_ground": False  # bool
}
hourly_dew_point_values(dry_bulb_condition)[source]

Get a list of dew points (C) at each hour over the design day.

Parameters

dry_bulb_condition – The dry bulb condition for the day.

to_dict()[source]

Convert the Humidity Condition to a dictionary.

HUMIDITY_TYPES = ('Wetbulb', 'Dewpoint', 'HumidityRatio', 'Enthalpy')
property barometric_pressure

Get or set the value of the barometric pressure.

property hourly_pressure

Get a list of barometric pressures for each hour over the design day.

property humidity_type

Get or set the humidity condition type.

property humidity_value

Get or set the value of the humidity.

property rain

Get or set a boolean for the presence of rain.

schedule
property snow_on_ground

Get or set a boolean for the presence of snow on the ground.

wet_bulb_range
class ladybug.designday.WindCondition(wind_speed, wind_direction=0)[source]

Bases: object

Represents wind conditions on the design day.

Parameters

  • wind_speed – Wind speed on the design day [m/s].

  • wind_direction – Wind direction on the design day [degrees]. Default: 0

Properties:

  • wind_speed

  • wind_direction

  • hourly_values

  • hourly_wind_dirs

ToString()[source]

Overwrite .NET ToString.

duplicate()[source]

Get a copy of this object.

classmethod from_dict(data)[source]

Create a Wind Condition from a dictionary.

Parameters

data – A python dictionary in the following format

{
"type": "WindCondition",
"wind_speed": 3.0,  # float
"wind_direction": 0.0  # float
}
to_dict()[source]

Convert the Wind Condition to a dictionary.

property hourly_values

A list of wind speed values for each hour over the design day.

property hourly_wind_dirs

A list of wind directions for each hour over the design day.

property wind_direction

Get or set the wind direction.

property wind_speed

Get or set the wind speed.