- [source code]

Open EPWmap in a web browser.

Inputs

• epw_map [Required]

Set to "True" to open EPWmap in a supported browser.

Outputs

• report

...

- [source code]

Import location from an epw file.

Inputs

• epw_file [Required]

An epw file path on your system as a string.

Outputs

• location

Location data (use this output to construct the sun path).

• Download Weather

• EPWmap

• Import EPW

• Import Location

• Construct Location

• Deconstruct Location

• Import DDY

• Import STAT

• Deconstruct Design Day

• Import Design Day

• EPW to DDY

- [source code]

Import climate data from a standard .epw file.

Inputs

• epw_file [Required]

An .epw file path on your system as a string.

Outputs

• location

A Ladybug Location object describing the location data in the weather file.

• dry_bulb_temperature

The houlry dry bulb temperature, in C. Note that this is a full numeric field (i.e. 23.6) and not an integer representation with tenths. Valid values range from 70 C to 70 C. Missing value for this field is 99.9.

• dew_point_temperature

The hourly dew point temperature, in C. Note that this is a full numeric field (i.e. 23.6) and not an integer representation with tenths. Valid values range from 70 C to 70 C. Missing value for this field is 99.9.

• relative_humidity

The hourly Relative Humidity in percent. Valid values range from 0% to 110%. Missing value for this field is 999.

• wind_speed

The hourly wind speed in m/sec. Values can range from 0 to 40. Missing value is 999.

• wind_direction

The hourly wind direction in degrees. The convention is North=0.0, East=90.0, South=180.0, West=270.0. If wind is calm for the given hour, the direction equals zero. Values can range from 0 to 360. Missing value is 999.

• direct_normal_rad

The hourly Direct Normal Radiation in Wh/m2. Direc Normal Radiation is the amount of solar radiation in Wh/m2 received directly from the solar disk on a surface perpendicular to the sun's rays. Missing values are (9999).

• diffuse_horizontal_rad

The hourly Diffuse Horizontal Radiation in Wh/m2. Diffuse Horizontal Radiation is the amount of solar radiation in Wh/m2 received from the sky (excluding the solar disk) on a horizontal surface. Missing values are (9999).

• global_horizontal_rad

The hourly Global Horizontal Radiation in Wh/m2. Global Horizontal Radiation is the total amount of direct and diffuse solar radiation in Wh/m2 received on a horizontal surface. It is not currently used inbEnergyPlus calculations. It should have a minimum value of 0; missing value for this field is 9999.

• horizontal_infrared_rad

The Horizontal Infrared Radiation Intensity in Wh/m2. If it is missing, EnergyPlus calculates it from the Opaque Sky Cover field. It should have a minimum value of 0; missing value is 9999.

• direct_normal_ill

The hourly Direct Normal Illuminance in lux. Direct Normal Illuminance is the average amount of illuminance in lux received directly from the solar disk on a surface perpendicular to the sun's rays. It is not currently used in EnergyPlus calculations. It should have a minimum value of 0; missing value is 999999.

• diffuse_horizontal_ill

The hourly Diffuse Horizontal Illuminance in lux. Diffuse Horizontal Illuminance is the average amount of illuminance in lux received from the sky (excluding the solar disk) on a horizontal surface. It is not currently used in EnergyPlus calculations. It should have a minimum value of 0; missing value is 999999.

• global_horizontal_ill

The hourly Global Horizontal Illuminance in lux. Global Horizontal Illuminance is the average total amount of direct and diffuse illuminance in lux received on a horizontal surface. It is not currently used in EnergyPlus calculations. It should have a minimum value of 0; missing value is 999999.

• total_sky_cover

The fraction for Total Sky Cover in tenths of coverage. (eg. 1 is 1/10 covered. 10 is total coverage). Total Sky Cover is the amount of the sky dome covered by clouds or obscuring phenomena. Minium value is 0; maximum value is 10; missing value is 99.

• barometric_pressure

The hourly weather station pressure in Pa. Valid values range from 31,000 to 120,000. Missing value is 999999.

• model_year

The year from which the hourly data has been extracted. EPW files are synthesized from real recorded data from different years in a given climate. This is done to ensure that, for each month, the selected data is statistically representative of the average monthly conditions over the 18+ years of recording the data. Different EPW files will be synthesized from different years depeding on whether they are TMY (Typical Meteorological Year), TMY2, TMY3, AMY (Actual Meteorological Year) or other.

• ground_temperature

Monthly ground temperature data if it exists within the EPW file. Typically, each data collection in this list represents monthly temperatures at three different depths.

- 0.5 meters

- 2.0 meters

- 4.0 meters

- [source code]

Construct location from latitude, lognitude, and time zone data.

Inputs

• name

A name for the location you are constructing. For example, "Steventon Island, Antarctica". (Default: "-")

• latitude

Location latitude between -90 and 90 (Default: 0).

• longitude

Location longitude between -180 (west) and 180 (east) (Default: 0).

• time_zone

Time zone between -12 hours (west) and 12 hours (east). If None, the time zone will be an estimated integer value derived from the longitude in accordance with solar time (Default: None).

• elevation

A number for elevation of the location in meters. (Default: 0).

Outputs

• location

Location data (use this output to construct the sun path).

- [source code]

Deconstruct location into its component properties.

Inputs

• location [Required]

The output from the importEPW or constructLocation component.

Outputs

• name

Name of the location.

• latitude

Latitude of the location.

• longitude

Longitude of the location.

• time_zone

Time zone of the location.

• elevation

Elevation of the location.

-

Import data from a standard .stat file.

Inputs

• stat_file [Required]

A .stat file path on your system as a string.

Outputs

• location

A Ladybug Location object describing the location data in the STAT file.

• ashrae_zone

The ASHRAE climate zone of the STAT file. Numbers in the zone denote average temperature (0 = Hottest; 8 = Coldest). Letters in the zone denote wetness (A = Humid; B = Dry; C = Marine)

• koppen_zone

The Koppen climate zone of the STAT file. The Koppen climate system uses vegetation as in indicator fo climate and combines average monthly temperatures, precipitation, and the seasonality of precipitation.

• clear_dir_norm_rad

The hourly "Clear Sky" Direct Normal Radiation in Wh/m2. Such clear sky radiation is typically used for sizing cooling systems. If monthly optical depths are found within the STAT file, these values will come from the Revised ASHARAE Clear Sky (Tau model). If no optical depths are found, they will come from the original ASHARE lear sky model.

• clear_diff_horiz_rad

The hourly "Clear Sky" Diffuse Horizontal Radiation in Wh/m2. Such clear sky radiation is typically used for sizing cooling systems. If monthly optical depths are found within the STAT file, these values will come from the Revised ASHARAE Clear Sky (Tau model). If no optical depths are found, they will come from the original ASHARE lear sky model.

• ann_heat_dday_996

A DesignDay object representing the annual 99.6% heating design day.

• ann_heat_dday_990

A DesignDay object representing the annual 99.0% heating design day.

• ann_cool_dday_004

A DesignDay object representing the annual 0.4% cooling design day.

• ann_cool_dday_010

A DesignDay object representing the annual 1.0% cooling design day.

• monthly_ddays_050

A list of 12 DesignDay objects representing monthly 5.0% cooling design days.

• monthly_ddays_100

A list of 12 DesignDay objects representing monthly 10.0% cooling design days.

• extreme_cold_week

A Ladybug AnalysisPeriod object representing the coldest week within the corresponding EPW.

• extreme_hot_week

A Ladybug AnalysisPeriod object representing the hottest week within the corresponding EPW.

• typical_weeks

A list of Ladybug AnalysisPeriod objects representing typical weeks within the corresponding EPW. The type of week can vary depending on the climate. For mid and high lattitude climates with 4 seasons (eg. New York), these weeks are for each of the 4 seasons ordered as follows: Winter, Spring, Summer, Autumn For low lattitude climates with wet/dry seasons (eg. Mumbai), these weeks might also include: Wet Season, Dry Season For equitorial climates with no seasons (eg. Singapore), This output is usually a single week representing typical conditions of the entire year.

-

Import hourly climate data from a Ladybug DesignDay object.

Inputs

• design_day [Required]

A DesignDay object to import.

Outputs

• location

A Ladybug Location object describing the location of the design day.

• dry_bulb_temperature

The houlry dry bulb temperature over the design day, in C.

• dew_point_temperature

The hourly dew point temperature over the design day, in C.

• relative_humidity

The hourly Relative Humidity over the design day in percent.

• wind_speed

The hourly wind speed over the design day in m/sec.

• wind_direction

The hourly wind direction over the design day in degrees. The convention is that North=0.0, East=90.0, South=180.0, West=270.0.

• direct_normal_rad

The hourly Direct Normal Radiation over the design day in Wh/m2.

• diffuse_horizontal_rad

The hourly Diffuse Horizontal Radiation over the design day in Wh/m2.

• global_horizontal_rad

The hourly Global Horizontal Radiation over the design day in Wh/m2.

• horizontal_infrared_rad

The Horizontal Infrared Radiation Intensity over the design day in Wh/m2.

• total_sky_cover

The fraction for total sky cover over the design day in tenths of coverage.

• barometric_pressure

The hourly weather station pressure over the design day in Pa.

• Construct Data

• Construct Data Type

• Construct Header

• Deconstruct Data

• Analysis Period

• Calculate HOY

• Apply Analysis Period

• Apply Conditional Statement

• Arithmetic Operation

• Time Interval Operation

• Degree Days

• Wind Speed

• Adaptive Comfort

• PET Comfort

• PMV Comfort

• UTCI Comfort

• Indoor Solar MRT

• Outdoor Solar MRT

• Ankle Draft

• Clothing by Temperature

• Comfort Statistics

• Convert to Timestep

• Data DateTimes

• Day Solar Information

• Deconstruct Header

• Directional Solar Irradiance

• HOY to DateTime

• Humidity Metrics

• Mass Arithmetic Operation

• Radiant Asymmetry

• Relative Humidity from Dew Point

• Solar MRT from Solar Components

• Thermal Indices

This primer provides an overview of the Ladybug components for Grasshopper.

Ladybug imports standard EnergyPlus Weather (.EPW) files into Grasshopper and provides a variety of 2D and 3D graphics to support the decision-making process during the early stages of design. The tool also provides several simple geometry analyses, including incident radiation and direct sun hours.

Installation

See the Wiki of the lbt-grasshopper repository for the installation instructions for the entire Ladybug Tools Grasshopper plugin (including ladybug-grasshopper).

Resources

Post your questions to Ladybug Tools forum and see the ladybug-grasshopper repository for source code.

Please let us know if you find any mistakes in grammar or spelling in this primer and we will gladly fix them.

- [source code]

Deconstruct design day into parameters.

Inputs

• design_day [Required]

A DesignDay object to deconstruct.

Outputs

• name

The name of the DesignDay object.

• day_type

Text indicating the type of design day (ie. 'SummerDesignDay', 'WinterDesignDay' or other EnergyPlus days).

• location

A Ladybug Location object describing the location of the design day.

• date

Date for the day of the year 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. Will be one of the following:

* Wetbulb

* Dewpoint

* HumidityRatio

* Enthalpy

• humidity_value

The value of the humidity condition above.

• barometric_p

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_type

Script output sky_type.

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

- [source code]

Import data from a standard .ddy file.

Inputs

• ddy_file [Required]

A .ddy file path on your system as a string.

Outputs

• location

A Ladybug Location object describing the location data in the DDY file.

• design_days

A list of DesignDay objects representing the design days contained within the ddy file.

- [source code]

Produce a DDY file from the data contained within an EPW or STAT file.

For EPW files, this method will first check if there is any heating or cooling design day information contained within the EPW itself. If None is found, the heating and cooling design days will be derived from analysis of the annual data within the EPW. This process of analyzing the annual TMY data is less representative of the climate since only one year of data is used to derive the DDY (instead of the usual multi-year analysis). However, if the EPW is the best available representation of the climate for a given site, it can often be preferable to using a DDY constructed with more years of data but from further away. Information on the uncertainty introduced by using only one year of data to create design days can be found in AHSRAE HOF 2013, Chapter 14.14.

For STAT files, the DDY file will only be produced if the design day information is found within the file. If no information on the relevant design days are found, and error will be raised and the component will fail to run.

Inputs

• weather_file [Required]

The path to an .epw file or .stat file on your system, from which a .ddy will be generated.

• percentile

A number between 0 and 50 for the percentile difference from the most extreme conditions within the EPW or STAT to be used for the design day. Typical values are 0.4 and 1.0. (Default: 0.4).

• monthly_cool

A boolean to note whether the resulting .ddy file should contain twelve cooling design days for each of the months of the year. This type of DDY file is useful when the peak cooling might not be driven by warm outdoor temperatures but instead by the highest-intensity solar condition, which may not conincide with the highest temperature. Monthly conditions will be for the 2.0% hottest conditions in each month, which generally aligns with the annual 0.4% cooling design conditions.

• folder

An optional file path to a directory into which the DDY file will be written. If None, the DDY file will be written to the ladybug default weather data folder and placed in a sub-folder called "ddy".

• write [Required]

Set to "True" to write the .ddy file.

Outputs

• ddy_file

A .ddy file path that has been written to your system.

- [source code]

Construct a Ladybug Header to be used to create a ladybug DataCollection.

Inputs

• data_type [Required]

Text representing the type of data (e.g. Temperature). A full list of acceptable inputs can be seen by checking the all_u output of the "LB Unit Converter" component. This input can also be a custom DataType object that has been created with the "LB Construct Data Type" component.

• unit

Units of the data_type (e.g. C). Default is to use the base unit of the connected_data_type.

• a_period

Script variable constrData

• metadata

Optional metadata to be associated with the Header. The input should be a list of text strings with a property name and value for the property separated by a colon. For example: . source: TMY . city: New York . country: USA

Outputs

• header

A Ladybug Header object.

- [source code]

Deconstruct a Ladybug DataCollection into a header and values.

Inputs

• data [Required]

A Ladybug DataCollection object.

Outputs

• header

The header of the DataCollection (containing metadata).

• values

The numerical values of the DataCollection.

-

Create an Analysis Period to describe a slice of time during the year.

Inputs

• start_month

Start month (1-12).

• start_day

Start day (1-31).

• start_hour

Start hour (0-23).

• end_month

End month (1-12).

• end_day

End day (1-31).

• end_hour

End hour (0-23).

• timestep

An integer number for the number of time steps per hours. Acceptable inputs include: 1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30, 60

Outputs

• period

Analysis period.

• hoys

List of dates in this analysis period.

• dates

List of hours of the year in this analysis period.

-

Convert a hourly Ladybug data collection to a continuous collection at a specific timestep.

This will be done either through linear interpolation or by culling out values that do not fit the timestep. It can also be used to convert a discontinous data collection to a continuous one by linearly interpolating over holes in the data set.

Inputs

• data [Required]

A list of aligned Data Collections to be evaluated against the _statement.

• statement [Required]

A conditional statement as a string (e.g. a > 25). The variable of the first data collection should always be named 'a' (without quotations), the variable of the second list should be named 'b', and so on. For example, if three data collections are connected to _data and the following statement is applied: '18 < a < 26 and b < 80 and c > 2' The resulting collections will only include values where the first data collection is between 18 and 26, the second collection is less than 80 and the third collection is greater than 2.

Outputs

• data

A list of Data Collections that have been filtered by the statement_.

-

Construct a Ladybug data collection from header and values.

Inputs

• header [Required]

A Ladybug header object describing the metadata of the data collection.

• values [Required]

A list of numerical values for the data collection.

• interval

Text to indicate the time interval of the data collection, which determines the type of collection that is output. (Default: hourly). Choose from the following:

Note that the "hourly" input is also used to represent sub-hourly intervals (in this case, the timestep of the analysis period must not be 1).

Outputs

• data

A Ladybug data collection object.

-

Calculate hour of the year from month, day, hour, minute.

Inputs

• month

Integer for month (1-12).

• day

Integer for day (1-31).

• hour

Integer for hour (0-23).

• minute

Integer for minute (0-59).

Outputs

• hoy

Hour of the year.

• doy

Day of the year.

• date

Human readable date time.

-

Calculate heating and cooling degree-days from outdoor dry bulb temperature.

Inputs

• dry_bulb [Required]

A data collection representing outdoor dry bulb temperature [C]

• heat_base

A number for the base temperature below which a given hour is considered to be in heating mode. Default is 18 Celcius, which is a common balance point for buildings.

• cool_base

A number for the base temperature above which a given hour is considered to be in cooling mode. Default is 23 Celcius, which is a common balance point for buildings.

Outputs

• hourly_heat

A data collection of heating degree-days. Plug this into the 'Time Interval Operation' component to get the number of degree-days at different time intervals.

• hourly_cool

A data collection of cooling degree-days. Plug this into the 'Time Interval Operation' component to get the number of degree-days at different time intervals.

• heat_deg_days

A value indicating the total number of heating degree-days over the entire input _dry_bulb collection.

• cool_deg_days

A value indicating the total number of cooling degree-days over the entire input _dry_bulb collection.

- [source code]

Calculate wind speed at a specific height above the ground for a given terrain type.

By default, the component will calculate wind speed at a height of 1 meter, which is suitable for most thermal comfort models like PET and SET. Alternatively, by hooking up the output wind data to the "LB Wind rose" component, a wind rose for any terrain or at height above the ground can be produced.

This component uses the same wind profile function as used by the "LB Wind Profile" component.

Inputs

• met_wind_vel [Required]

A data collection of meteorological wind speed measured at the met_height with the _met_terrian [m/s]. Typically, this comes from the "LB Import EPW" component. This can also be a number for the meteorological wind speed in m/s.

• height

The height above the ground to be evaluated in meters. (Default: 1 meter, which is suitable for most thermal comfort models like PET and SET.).

• terrain

Text string that sets the terrain class associated with the output air_speed. This can also be an integer that codes for the terrain. (Default: city). Must be one the following. 0 = city - 50% of buildings above 21m over a distance of at least 2000m upwind. 1 = suburban - suburbs, wooded areas. 2 = country - open, with scattered objects generally less than 10m high. 3 = water - flat areas downwind of a large water body (max 500m inland).

• met_height

A number for the height above the ground at which the meteorological wind speed is measured in meters. (Default: 10 meters, which is the standard used by most airports and EPW files).

• met_terrain

Text string that sets the terrain class associated with the meteorological wind speed. This can also be an integer that codes for the terrain. (Default: country, which is typical of most airports where wind measurements are taken). Must be one the following. 0 = city - 50% of buildings above 21m over a distance of at least 2000m upwind. 1 = suburban - suburbs, wooded areas. 2 = country - open, with scattered objects generally less than 10m high. 3 = water - flat areas downwind of a large water body (max 500m inland).

• log_law

A boolean to note whether the wind profile should use a logarithmic law to determine wind speeds instead of the default power law, which is used by EnergyPlus. (Default: False).

Outputs

• report

Reports, errors, warnings, etc.

• air_speed

A data collection or single value for the air speed at the input height above the ground for the input terrain. This can be plugged into thermal comfort models like PET or SET/PMV. Alternatively, by connecting the wind data to the "LB Wind rose" component, a wind rose for the input terrain and height above the ground can be produced.

- [source code]

Apply an analysis period to a data collection.

Inputs

• data [Required]

A Ladybug data collection object.

• period [Required]

A Ladybug analysis period from the "LB AnalysisPeriod" component.

Outputs

• data

The data collection with the analysis period applied to it.

- [source code]

Perform simple arithmetic operations between Data Collections. For example, adding two Data Collections together, subtracting one collection from another, or multiplying/dividing a data in a collection by a factor.

Note that Data Collections must be aligned in order for this component to run successfully.

Using this component will often be much faster and more elegant compared to deconstructing the data collection, performing the operation with native Grasshopper components, and rebuilding the collection.

Inputs

• data_1 [Required]

The first Data Collection in the operation. If the operator is not commutative, this collection comes before the operator. For example, in subtraction, this is the collection being subtracted from. This can also be a list of Data Collections that align with _data_2. It cal also be a single number that will be added, multiplied, etc. to all of _data_2.

• data_2 [Required]

The second Data Collection in the operation. If the operator is not commutative, this collection comes after the operator. For example, in subtraction, this is the collection being subtracted with. This can also be a list of Data Collections that align with _data_1. It cal also be a single number that will be added, multiplied, etc. to all of _data_1.

• operator

Text for the operator to use between the two Data Collections. Valid examples include (+, -, *, /). By default this is + for addition.

• type

Optional text for a new "type" key in the Data Collection's metadata. This will usually show up in most Ladybug visualiztions and it should usually change for most types of operations.

Outputs

• data

A Ladybug data collection object derived from the operation between the two data inputs.

- [source code]

Calculate Predicted Mean Vote (PMV).

PMV is a thermal comfort model for use on the interior of buildings where a heating or cooling system is operational. For naturally ventilated buildings, the Adaptive thermal comfort model is recommended and, for outdoor conditions, models such as Universal Thermal Climate Index (UTCI) or Physiological Equivalent Temperature (PET) are recommended.

Inputs

• air_temp [Required]

Data Collection or individual value for air temperature in C.

• mrt

Data Collection or individual value of mean radiant temperature (MRT) in C. Default is the same as the air_temp.

• rel_humid [Required]

Data Collection or individual value for relative humidity in %. Note that percent values are between 0 and 100.

• air_speed

Data Collection or individual value for air speed in m/s. Default is a very low speed of 0.1 m/s, which is typical of the room air speeds induced by HVAC systems.

• met_rate

Data Collection or individual value of metabolic rate in met. Default is set to 1.1 met for seated, typing. Typical values include the following.

* 1 met = Metabolic rate of a resting seated person

* 1.2 met = Metabolic rate of a standing person

* 2.4 met = Metabolic rate of a person walking at ~1 m/s (2 mph)

• clothing

Data Collection or individual value of clothing insulation in clo. Default is set to 0.7 clo for long sleeve shirt and pants. Typical values include the following.

* 1 clo = Three-piece suit

* 0.5 clo = Shorts + T-shirt

* 0 clo = No clothing

• pmv_par

Optional comfort parameters from the "LB PMV Comfort Parameters" component to specify the criteria under which conditions are considered acceptable/comfortable. The default will assume a PPD threshold of 10% and no absolute humidity constraints.

• run [Required]

Set to True to run the component.

Outputs

• report

Reports, errors, warnings, etc.

• pmv

Predicted Mean Vote (PMV). PMV is a seven-point scale from cold (-3) to hot (+3) that was used in comfort surveys of P.O. Fanger. Each interger value of the scale indicates the following:

* -3 = Cold

* -2 = Cool

* -1 = Slightly Cool

*  0 = Neutral

* +1 = Slightly Warm

* +2 = Warm

* +3 = Hot

• ppd

Percentage of People Dissatisfied (PPD). Specifically, this is defined by the percent of people who would have a PMV beyond acceptable thresholds (typically <-0.5 and >+0.5). Note that, with the PMV model, the best possible PPD achievable is 5% and most standards aim to have a PPD below 10%.

• set

Standard Effective Temperature (SET) in Celcius. These temperatures describe what the given input conditions "feel like" in relation to a standard environment of 50% relative humidity, <0.1 m/s average air speed, and mean radiant temperature equal to average air temperature, in which the total heat loss from the skin of an imaginary occupant with an activity level of 1.0 met and a clothing level of 0.6 clo is the same as that from a person in the actual environment.

• comfort

Integers noting whether the input conditions are acceptable according to the assigned comfort_parameter. Values are one of the following:

* 0 = uncomfortable

* 1 = comfortable

• condition

Integers noting the thermal status of a subject according to the assigned comfort_parameter. Values are one of the following:

* -2 = too dry (but thermally neutral)

* -1 = cold

*  0 = netural

* +1 = hot

* +2 = too humid (but thermally neutral)

• heat_loss

A list of 6 terms for heat loss from the human energy balance calculation that underlies PMV. Valeus are in W. The terms are ordered as follows:

- Conduction

- Sweating

- Latent Respiration

- Dry Respiration

- Radiation

- Convection

• comf_obj

A Python object containing all inputs and results of the analysis. This can be plugged into components like the "Comfort Statistics" component to get further information.

-

Construct a Ladybug DataType to be used in the header of a ladybug DataCollection.

Inputs

• name [Required]

A name for the data type as a string.

• unit [Required]

A unit for the data type as a string.

• cumulative

Boolean to tell whether the data type can be cumulative when it is represented over time (True) or it can only be averaged over time to be meaningful (False).

• categories

An optional list of text for categories to be associated with the data type. These categories will show up in the legend whenever data with this data type is visualized. The input should be text strings with a category number (integer) and name separated by a colon. For example: . -1: Cold . 0: Neutral . 1: Hot

Outputs

• type

A Ladybug DataType object that can be assigned to the header of a Ladybug DataCollection.

-

Calculate Universal Thermal Climate Index (UTCI).

UTCI is a thermal comfort model strictly for the outdoors. It is an international standard for outdoor temperature sensation (aka. "feels-like" temperature) and is one of the most common of such "feels-like" temperatures used by meteorologists. UTCI that attempts to satisfy the following requirements:

1. Thermo-physiological significance in the whole range of heat exchange conditions. 2) Valid in all climates, seasons, and scales. 3) Useful for key applications in human biometeorology.

While UTCI is designed to be valid in all climates and seasons, it assumes that human subjects are walking (with a metabolic rate around 2.4 met) and that they naturally adapt their clothing with the outdoor temperature. For outdoor situations that do not fit these criteria, the Physiological Equivalent Temperature (PET) model is recommended.

Inputs

• air_temp [Required]

Data Collection or individual value for air temperature in C.

• mrt

Data Collection or individual value for mean radiant temperature (MRT) in C. Default is the same as the air_temp.

• rel_humid [Required]

Data Collection or individual value for relative humidity in %. Note that percent values are between 0 and 100.

• wind_vel

Data Collection or individual value for meteoroligical wind velocity at 10 m above ground level in m/s. Note that this meteorological velocity at 10 m is simply 1.5 times the speed felt at ground level in the original Fiala model used to create the UTCI model. Therefore, multiplying air speed values at the height of the human subject by 1.5 will make them a suitable input for this component. Default is a low speed of 0.5 m/s, which is the lowest input speed that is recommended for the UTCI model.

• utci_par

Optional comfort parameters from the "LB UTCI Comfort Parameters" component to specify the temperatures (in Celcius) that are considered acceptable/comfortable. The default will assume a that the comfort range is between 9C and 26C.

• run [Required]

Set to True to run the component.

Outputs

• report

Reports, errors, warnings, etc.

• utci

Universal Thermal Climate Index (UTCI) in Celcius.

• comfort

Integers noting whether the input conditions result in no thermal stress. Values are one of the following:

• condition

Integers noting the thermal status of a subject. Values are one of the following:

• category

Integers noting the category that the UTCI conditions fall under on an 11-point scale. Values are one of the following:

• comf_obj

A Python object containing all inputs and results of the analysis. This can be plugged into components like the "Comfort Statistics" component to get further information.

-

Estimate levels of clothing using a temperature value or data collection of temperatures to which a human subject is adapting (typically the outdoor air temperature).

This resulting clothing values can be plugged into the clothing input of the "LB PMV Comfort" component or the "LB PET Comfort" component. They can also be used in thermal mapping recipes.

By default, this function derives clothing levels using a model developed by Schiavon, Stefano based on outdoor air temperature, which is implemented in the CBE comfort tool (https://comfort.cbe.berkeley.edu/).

The version of the model implemented here allows changing of the maximum and minimum clothing levels, which the Schiavon model sets at 1 and 0.46 respectively, and the temperatures at which these clothing levels occur, which the Schiavon model sets at -5 C and 26 C respectively.

Inputs

• temperature [Required]

A data collection or single number representing the temperature to which the human subject adapts their clothing. This is typically the dry bulb temperature obtained from the "LB Import EPW" component.

• period

If you have hooked up annual temperatures from the importEPW component, use this input to

• max_clo

A number for the maximum clo value that the human subject wears on the coldest days. (Default: 1 clo, per the original Schiavon clothing function).

• max_clo_temp

A number for the temperature below which the max_clo value is applied (in Celsius). (Default: -5 C, per the original Schiavon clothing function with outdoor temperature).

• min_clo

A number for the minimum clo value that the human subject wears wears on the hotest days. (Default: 0.46 clo, per the original Schiavon clothing function).

• min_clo_temp

A number for the temperature above which the min_clo value is applied (in Celsius). (Default: 26 C, per the original Schiavon clothing function).

Outputs

• report

Reports, errors, warnings, etc.

• clo

A single number or data collection of numbers representing the clothing that would be worn (in clo). Note that, if you have hooked up an hourly continuous data collection, the clothing levels will change on a 12-hour basis to simulate the typical cycle on which a human changes their clothing.

-

Calculate Mean Radiant Temperature (MRT) as a result of outdoor shortwave solar shining directly onto people as well as longwave radiant exchange with the sky.

This component uses the SolarCal model of ASHRAE-55 to estimate the effects of shortwave solar and a simple sky exposure method to determine longwave radiant exchange.

Inputs

• location [Required]

A Ladybug Location object, used to determine the altitude and azimuth of the sun.

• longwave_mrt [Required]

A single number or an hourly data collection with the long-wave mean radiant temperature around the person in degrees C. This includes the temperature of the ground and any other surfaces between the person and their view to the sky. Typically, indoor air temperature is used when such surface temperatures are unknown.

• dir_norm_rad [Required]

Hourly Data Collection with the direct normal solar irradiance in W/m2.

• diff_horiz_rad [Required]

Hourly Data Collection with diffuse horizontal solar irradiance in W/m2.

• fract_body_exp

A single number between 0 and 1 or a data collection for the fraction of the body exposed to direct sunlight. The "LB Human to Sky Relationship" component can be used to estimate this input for a given set of context geometry and position of the human. Note that this parameter does NOT include the body’s self-shading. It only includes the shading from furniture and surroundings. (Default: 1 for an area surrounded by glass).

• sky_exposure

A single number between 0 and 1 or a data collection representing the fraction of the sky vault in the human subject’s view. The "LB Human to Sky Relationship" component can be used to estimate this input for a given set of context geometry and position of the human. (Default: 0.5 for a person next to an all glass facade).

• ground_ref

A single number between 0 and 1 or a data collection that represents the reflectance of the floor. Default is for 0.25 which is characteristic of concrete.

• window_trans

A Data Collection or number between 0 and 1 that represents the broadband solar transmittance of the window through which the sun is coming. Such values tend to be slightly less than the SHGC. Values might be as low as 0.2 and could be as high as 0.85 for a single pane of glass. Default is 0.4 assuming a double pane window with a relatively mild low-e coating.

• solar_body_par

Optional solar body parameters from the "LB Solar Body Parameters" object to specify the properties of the human geometry assumed in the shortwave MRT calculation. The default assumes average skin/clothing absorptivity and a human subject always has their back to the sun at a 45-degree angle (SHARP = 135).

• run [Required]

Set to True to run the component.

Outputs

• report

Reports, errors, warnings, etc.

• erf

Data collection of effective radiant field (ERF) in W/m2.

• dmrt

Data collection of mean radiant temperature delta in C.

• mrt

Data collection of mean radiant temperature in C.

- [source code]

Calculate Physiological Equivalent Temperature (PET).

PET uses the Munich Energy Balance Model (MEMI), which is arguably the most detailed 3-node human energy balance model in common use today. It can account for various physiological features of the human subject, including age, sex, height, and body mass, making it one of the only models that is suitable for forecasting the thermal experience of a specific individual. This also makes it one of the better models for estimating core body temperature and whether a given set of conditions is likely to induce hypothermia or hyperthermia in a specific individual.

Inputs

• air_temp [Required]

Data Collection or individual value for air temperature in C.

• mrt

Data Collection or individual value of mean radiant temperature (MRT) in C. Default is the same as the air_temp.

• rel_humid [Required]

Data Collection or individual value for relative humidity in %. Note that percent values are between 0 and 100.

• air_speed

Data Collection or individual value for air speed in m/s. Default is a very low speed of 0.1 m/s, which is typical of the room air speeds induced by HVAC systems.

• pressure

A value or data collection representing atmospheric pressure [Pa] Default is to use air pressure at sea level (101,325 Pa).

• met_rate

Data Collection or individual value of metabolic rate in met. Note that the original PET model requires that the activity of the human subject be accounted for as additional Watts above the basal metabolism, which is often difficult to estimate. In order to accept an input in [met], it is assumed that 1 met refers to Resting Metabolic Rate (RMR) and this is 1.17 times the male Basal Metabolic Rate (BMR) or 1.22 times the female BMR. Default is set to 2.4 met for walking. Typical values include the following.

* 1 met = Metabolic rate of a resting seated person

* 1.2 met = Metabolic rate of a standing person

* 2.4 met = Metabolic rate of a person walking at ~1 m/s (2 mph)

• clothing

Data Collection or individual value of clothing insulation in clo. Default is set to 0.7 clo for long sleeve shirt and pants. Typical values include the following.

* 1 clo = Three-piece suit

* 0.5 clo = Shorts + T-shirt

* 0 clo = No clothing

• pet_par

Optional comfort parameters from the "LB PET Body Parameters" component to specify the body properties of the human subject. This includes the age, height, sex, body mass, and more. The default attempts to model as average of a human body as possible.

• run [Required]

Set to True to run the component.

Outputs

• report

Reports, errors, warnings, etc.

• pet

Physiological Equivalent Temperature (PET) [C]. PET is a "feels like" temperature value and is defined as the operative temperature of a reference environment that would cause the same physiological response in the human subject as the environment under study. That is, the same skin temperature and core body temperature.

• core_temp

The core body temperature of the human subject [C].

• skin_temp

The skin temperature of the human subject underneath the clothing layer [C].

• comfort

Integers noting whether the input conditions result in no thermal stress (aka. they are comfortable. Values are one of the following:

* 0 = uncomfortable

* 1 = comfortable

• condition

Integers noting the thermal status of a subject. Values are one of the following:

* -1 = cold

*  0 = netural

* +1 = hot

• category

Integers noting the thermal status on a nine-point scale. Values are one of the following:

* -4 = very strong/extreme cold stress

* -3 = strong cold stress

* -2 = moderate cold stress

* -1 = slight cold stress

* 0 = no thermal stress

* +1 = slight heat stress

* +2 = moderate heat stress

* +3 = strong heat stress

* +4 = very strong/extreme heat stress

• core_cond

Integers noting the classification of core body temperature. Values are one of the following:

* -2 = Hypothermia

* -1 = Cold

* 0 = Normal

* +1 = Hot

* +2 = Hyperthermia

• comf_obj

A Python object containing all inputs and results of the analysis. This can be plugged into components like the "Comfort Statistics" component to get further information.

- [source code]

Compute solar infomation about a day of the year at a particular location. This includes the time of sunrise, sunset, solar noon, and the length of the day in hours.

Note that these times are intended to represent a typical year and they will often vary by a few minutes depending on where in the leap year cycle a given year falls.

Inputs

• location [Required]

A ladybug Location that has been output from the "LB Import EPW" component or the "LB Construct Location" component.

• doy [Required]

An integer for the day of the year for which solar information is be computed. The "LB Calculate HOY" component can be used to compute the day of the year from month and day inputs.

• depression

An angle in degrees indicating the additional period before/after the edge of the sun has passed the horizon where the sun is still considered up. Setting this value to 0 will compute sunrise/sunset as the time when the edge of the sun begins to touch the horizon. Setting it to the angular diameter of the sun (0.5334) will compute sunrise/sunset as the time when the sun just finishes passing the horizon (actual physical sunset). Setting it to 0.833 will compute the apparent sunrise/sunset, accounting for atmospheric refraction. Setting this to 6 will compute sunrise/sunset as the beginning/end of civil twilight. Setting this to 12 will compute sunrise/sunset as the beginning/end of nautical twilight. Setting this to 18 will compute sunrise/sunset as the beginning/end of astronomical twilight. (Default: 0.5334 for the physical sunset).

• solar_time

A boolean to indicate if the output datetimes for sunrise, noon and sunset should be in solar time as opposed to the time zone of the location. (Default: False).

• dl_saving

An optional analysis period for daylight saving time. This will be used to adjust the output times by an hour when applicable. If unspecified, no daylight saving time will be used

Outputs

• sunrise

The time of sunrise expressed as HH:MM where hours range from 0 to 23. Note that this may be None if there is no sunrise or sunset on the specified day. (eg. at the north pole on the winter solstice).

• sunset

The time of sunset expressed as HH:MM where hours range from 0 to 23. Note that this may be None if there is no sunrise or sunset on the specified day. (eg. at the north pole on the winter solstice).

• solar_noon

The time of solar noon when the sun is at its highest point in the sky, expressed as HH:MM.

• noon_alt

The altitude of the sun at solar noon in degrees. This is the maximum altitude that will be expereinced on the input day.

• day_length

The length of the input day in hours.

- [source code]

Convert a hourly Ladybug data collection to a continuous collection at a specific timestep.

This will be done either through linear interpolation or by culling out values that do not fit the timestep. It can also be used to convert a discontinous data collection to a continuous one by linearly interpolating over holes in the data set.

Inputs

• data [Required]

A Ladybug Hourly DataCollection object. This can be either continuous or discontinuous.

• timestep

The timestep to which the data will be converted. If this is higher than the input _data timestep, values will be linerarly interpolated to the new timestep. If it is lower, values that do not fit the timestep will be removed from the DataCollection. (Defaut: 1)

Outputs

• data

A Continuous DataCollection at the input timestep.

- [source code]

Calculate date information from an hour of the year.

Date information includes the month of the year, day of the month and the hour + minute of the day.

Inputs

• hoy [Required]

A number between 0 and 8759 for an hour of the year.

Outputs

• month

The month of the year on which the input hoy falls.

• day

The day of the month on which the input hoy falls.

• hour

The hour of the day on which the input hoy falls.

• minute

The minute of the hour on which the input hoy falls.

• date

The input information as a human-readable date time.

- [source code]

Deconstruct a Ladybug Header into its components.

Inputs

• header [Required]

The header of the DataCollection (containing metadata).

Outputs

• data_type

Type of data (e.g. Temperature) (Default: unknown).

• unit

Units of the data_type (e.g. C) (Default: unknown)

• a_period

A Ladybug AnalysisPeriod object.

• metadata

Optional metadata associated with the Header.

- [source code]

Automatically download a .zip file from a URL where climate data resides, unzip the file, and open .epw, .stat, and ddy weather files.

Inputs

• weather_URL [Required]

Text representing the URL at which the climate data resides. To open the a map interface for all publicly availabe climate data, use the "LB EPWmap" component.

• folder

An optional file path to a directory into which the weather file will be downloaded and unziped. If None, the weather files will be downloaded to the ladybug default weather data folder and placed in a sub-folder with the name of the weather file location.

Outputs

• epw_file

The file path of the downloaded epw file.

• stat_file

The file path of the downloaded stat file.

• ddy_file

The file path of the downloaded ddy file.

- [source code]

Perform time interval operations on an hourly data collection.

This includes operations like: - Average - Total - Percentile

These actions can be performed over the following time intervals: - Daily - Monthly - Monthly per Hour

Inputs

• data [Required]

A Ladybug data collection object.

• operation

Text indicating the operation that should be performed on the input hourly data. Such text must be one of the following:

- average

- total

- [a number between 0 and 100]

In the case of the last option, the number will be interpreted as a percentile of the data over the time period. For example, inputting 75 will return the 75th percentile value of each day/month/hour, inputting 0 will give the minimum value of each day/month/hour and inputting 100 will give the max value of each day/month/hour. Default is 'average' if the input data type is not cumulative and 'total' if the data type is cumulative.

Outputs

• daily

Daily data collection derived from the input _data and operation.

• monthly

Monthly data collection derived from the input _data and operation.

• mon_per_hr

Monthly Per Hour data collection derived from the input _data and operation.

- [source code]

Calculate Adaptive thermal comfort.

The Adaptive thermal comfort model is for use on the interior of buildings where a heating or cooling system is not operational and occupants have the option to open windows for natural ventilation.

Note that, for fully conditioned buildings, the PMV thermal comfort model should be used.

Inputs

• out_temp [Required]

Outdoor temperatures in one of the following formats:

* A Data Collection of outdoor dry bulb temperatures recorded overthe entire year. This Data Collection must be continouous and must either be an Hourly Collection or Daily Collection. In the event that the input adapt_par_ has a _avgm_or_runmean_ set to True, Monthly collections are also acceptable here. Note that, because an annual input is required, this input collection does not have to align with the _air_temp or _mrt_ inputs. 

* A Data Collection of prevailing outdoor temperature values in C.This Data Collection must align with the _air_temp or _mrt_ inputs and bear the PrevailingOutdoorTemperature data type in its header. 

* A single prevailing outdoor temperature value in C to be usedfor all of the _air_temp or _mrt_ inputs. 

• air_temp [Required]

Data Collection or individual value for air temperature in C.

• mrt

Data Collection or individual value for mean radiant temperature (MRT) in C. Default is the same as the air_temp.

• air_speed

Data Collection or individual value for air speed in m/s. Note that higher air speeds in the adaptive model only widen the upper boundary of the comfort range at temperatures above 24 C and will not affect the lower temperature of the comfort range. Default is a very low speed of 0.1 m/s.

• adapt_par

Optional comfort parameters from the "LB Adaptive Comfort Parameters" component to specify the criteria under which conditions are considered acceptable/comfortable. The default will use ASHRAE-55 adaptive comfort criteria.

• run [Required]

Set to True to run the component.

Outputs

• report

Reports, errors, warnings, etc.

• prevail_temp

Data Collection of prevailing outdoor temperature in degrees C.

• neutral_temp

Data Collection of the desired neutral temperature in degrees C.

• deg_neutral

Data Collection of the degrees from desired neutral temperature in degrees C.

• comfort

Integers noting whether the input conditions are acceptable according to the assigned comfort_parameter. Values are one of the following:

* 0 = uncomfortable

* 1 = comfortable

• condition

Integers noting the thermal status of a subject according to the assigned comfort_parameter. Values are one of the following:

* -1 = cold

*  0 = netural

* +1 = hot

• comf_obj

A Python object containing all inputs and results of the analysis. This can be plugged into components like the "Comfort Statistics" component to get further information.

- [source code]

Get the hours, days, or months of the year associated with the values of a data collection.

Inputs

• data [Required]

An hourly, daily, or monthly collection from which hours, days, or months of the year will be retrieved.

Outputs

• hoys

Numbers for the, hours, days or months of the year in the data collection.

-

Get statitics of thermal comfort from a Ladybug Comfort Object.

Inputs

• comf_obj [Required]

A Ladybug ComfortCollection object from any of the comfort model components.

Outputs

• pct_hot

The percent of time that conditions are hotter than acceptable limits.

• pct_neutral

The percent of time that conditions are within acceptable limits (aka. the percent of time comfortable).

• pct_cold

The percent of time that conditions are colder than acceptable limits.

- [source code]

Calculate Mean Radiant Temperature (MRT) as a result of outdoor shortwave solar shining directly onto people as well as longwave radiant exchange with the sky.

This component uses the SolarCal model of ASHRAE-55 to estimate the effects of shortwave solar and a simple sky exposure method to determine longwave radiant exchange.

Inputs

• location [Required]

A Ladybug Location object, used to determine the altitude and azimuth of the sun.

• surface_temp [Required]

A single number or an hourly data collection with the temperature of surfaces around the person in degrees C. This includes the ground and any other surfaces blocking the view to the sky. Typically, outdoor dry bulb temperature is used when such surface temperatures are unknown.

• dir_norm_rad [Required]

Hourly Data Collection with the direct normal solar irradiance in W/m2.

• diff_horiz_rad [Required]

Hourly Data Collection with diffuse horizontal solar irradiance in W/m2.

• horiz_infrared [Required]

Hourly Data Collection with the horizontal infrared radiation intensity from the sky in W/m2.

• fract_body_exp

A single number between 0 and 1 or a data collection for the fraction of the body exposed to direct sunlight. The "LB Human to Sky Relationship" component can be used to estimate this input for a given set of context geometry and position of the human. Note that this parameter does NOT include the body’s self-shading. It only includes the shading from furniture and surroundings. (Default: 1 for an open area).

• sky_exposure

A single number between 0 and 1 or a data collection representing the fraction of the sky vault in the human subject’s view. The "LB Human to Sky Relationship" component can be used to estimate this input for a given set of context geometry and position of the human. (Default: 1 for a person standing in an open area).

• ground_ref

A single number between 0 and 1 or a data collection that represents the reflectance of the floor. Default is for 0.25 which is characteristic of outdoor grass or dry bare soil.

• solar_body_par

Optional solar body parameters from the "LB Solar Body Parameters" object to specify the properties of the human geometry assumed in the shortwave MRT calculation. The default assumes average skin/clothing absorptivity and a human subject always has their back to the sun at a 45-degree angle (SHARP = 135).

• run [Required]

Set to True to run the component.

Outputs

• report

Reports, errors, warnings, etc.

• short_erf

Data collection of shortwave effective radiant field (ERF) in W/m2.

• long_erf

Data collection of longwave effective radiant field (ERF) in W/m2.

• short_dmrt

Data collection of shortwave mean radiant temperature delta in C.

• long_dmrt

Data collection of longwave mean radiant temperature delta in C.

• mrt

Data collection of mean radiant temperature in C. This accounts for both the shortwave solar shining directly onto people as well as longwave radiant exchange with the sky.

- [source code]

Calculate the percentage of people dissatisfied from cold drafts at ankle-level.

The original tests used to create the model involved blowing cold air on subject's ankles at a height of 10 cm off of the ground. The formula was officially incorporated in the ASHRAE 55 standard in 2020 with a recommendation that PPD from ankle draft not exceed 20%.

For more information on the methods used to create this model see the following: Liu, S., S. Schiavon, A. Kabanshi, W. Nazaroff. 2016. "Predicted percentage of dissatisfied with ankle draft." Accepted Author Manuscript. Indoor Environmental Quality. http://escholarship.org/uc/item/9076254n

Inputs

• full_body_pmv [Required]

The full-body predicted mean vote (PMV) of the subject. Ankle draft depends on full-body PMV because subjects are more likely to feel uncomfortably cold at their extremities when their whole body is already feeling colder than neutral. The "LB PMV Comfort" component can be used to obatin this input here.

• draft_velocity [Required]

The velocity of the draft in m/s at ankle level (10cm above the floor).

Outputs

• ppd

The percentage of people dissatisfied (PPD) from cold drafts at ankle level.

-

Calculate Mean Radiant Temperature (MRT) as a result of shortwave solar using horizontal solar components (direct horizontal and diffuse horizontal solar).

This component uses the SolarCal model of ASHRAE-55 to estimate the effects of shortwave solar and a simple sky exposure method to determine longwave radiant exchange.

Inputs

• location [Required]

A Ladybug Location object.

• longwave_mrt [Required]

A single number or an hourly data collection with the long-wave mean radiant temperature around the person in degrees C. This includes the temperature of the ground and any other surfaces between the person and their view to the sky. Typically, air temperature is used when such surface temperatures are unknown.

• dir_horiz_rad [Required]

Hourly Data Collection with the direct horizontal solar irradiance in W/m2.

• diff_horiz_rad [Required]

Hourly Data Collection with diffuse horizontal solar irradiance in W/m2.

• fract_body_exp

A single number between 0 and 1 or a data collection representing the fraction of the body exposed to direct sunlight. Note that this does not include the body’s self-shading; only the shading from surroundings. Default is 1 for a person standing in an open area.

• ground_ref

A single number between 0 and 1 or a data collection that represents the reflectance of the floor. Default is for 0.25 which is characteristic of outdoor grass or dry bare soil.

• solar_body_par

Optional solar body parameters from the "LB Solar Body Parameters" object to specify the properties of the human geometry assumed in the shortwave MRT calculation. The default assumes average skin/clothing absorptivity and a human subject always has their back to the sun at a 45-degree angle (SHARP = 135).

• run [Required]

Set to True to run the component.

Outputs

• report

Reports, errors, warnings, etc.

• erf

Data collection of effective radiant field (ERF) in W/m2.

• dmrt

Data collection of mean radiant temperature delta in C.

• mrt

Data collection of mean radiant temperature in C.

-

Compute the hourly solar irradiance or illuminance falling on an unobstructed surface that faces any direction.

The calculation method of this component is faster than running "LB Incident Radiation" studies on an hour-by-hour basis and it is slighty more realistic since it accounts for ground reflection. However, this comes at the cost of not being able to account for any obstructions that block the sun.

Inputs

• location [Required]

A Ladybug Location object, used to determine the altitude and azimuth of the sun at each hour.

• direct_norm [Required]

Hourly Data Collection with the direct normal solar irradiance in W/m2 or Illuminance in lux.

• diffuse_horiz [Required]

Hourly Data Collection with diffuse horizontal solar irradiance in W/m2 or Illuminance in lux.

• srf_azimuth

A number between 0 and 360 that represents the azimuth at which irradiance is being evaluated in degrees. 0 = North, 90 = East, 180 = South, and 270 = West. (Default: 180).

• srf_altitude

A number between -90 and 90 that represents the altitude at which irradiance is being evaluated in degrees. A value of 0 means the surface is facing the horizon and a value of 90 means a surface is facing straight up. (Default: 0).

• ground_ref

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

• anisotrophic

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

Outputs

• report

...

• total

A data collection of total solar irradiance or illuminance in the direction of the srf_azimuth and srf_altitude.

• direct

A data collection of direct solar irradiance or illuminance in the direction of the srf_azimuth and srf_altitude.

• diff

A data collection of diffuse sky solar irradiance or illuminance in the direction of the srf_azimuth and srf_altitude.

• reflect

A data collection of ground reflected solar irradiance or illuminance in the direction of the srf_azimuth and srf_altitude.

-

Calculate thermal indices that have historically been used by meteorologists. All of them are "feels like" temperatures that attempt to account for factors beyond sir temperature. These include the following:

• Wet Bulb Globe Temperature (WBGT) * Heat Index (HI) * Wind Chill Temperature (WCT)

Most of these indices have fallen out of use in favor of Universal Thermal Climate Index (UTCI). However, they are still used in some regions and are a part of older codes and standards.

Inputs

• air_temp [Required]

Data Collection or individual value for air temperature in C. This input is used by all three metrics.

• mrt

Data Collection or individual value for mean radiant temperature (MRT) in C. Default is the same as the air_temp. This input only affects the WBGT.

• rel_humid [Required]

Data Collection or individual value for relative humidity in %. Note that percent values are between 0 and 100. This input affects WBGT as well as HI.

• wind_vel [Required]

Data Collection or individual value for meteoroligical wind velocity at 10 m above ground level in m/s. This is used by both WBGT and WCT.

Outputs

• wbgt

A data collection or value for Wet Bulb Globe Temperature (WBGT) [C]. WBGT is a type of feels-like temperature that is widely used as a heat stress index (ISO 7243). It is incorporates the effect of temperature, humidity, wind speed, and mean radiant temperature (optionally including the effect of sun).

• heat_index

A data collection or value for Heat Index (HI) temperature [C]. Heat index is derived from original work carried out by Robert G. Steadman, which defined heat index through large tables of empirical data. The formula here approximates the heat index to within +/- 0.7C and is the result of a multivariate fit. Heat index was adopted by the US's National Weather Service (NWS) in 1979.

• wind_chill

A data collection or value for Wind Cill Temperature (WCT) [C]. Wind Chill Index is derived from original work carried out by Gregorczuk. It qualifies thermal sensations of a person in wintertime. It is especially useful at low and very low air temperature and at high wind speed.

-

Calculate humidity metrics from relative humidity, dry bulb temperature and (if present) atmospheric pressure.

Inputs

• dry_bulb [Required]

A value or data collection representing dry bulb temperature [C]

• rel_humid [Required]

A value or data collection representing relative humidity [%]

• pressure

A value or data collection representing atmospheric pressure [Pa] Default is to use air pressure at sea level (101,325 Pa).

Outputs

• humid_ratio

A data collection or value for humidity ratio (aka. absolute humidity). Units are fractional (kg water / kg air).

• enthalpy

A data collection or value for enthalpy (kJ / Kg).

• wet_bulb

A data collection or value for wet bulb temperature (C).

• dew_point

A data collection or value for dew point temperature (C).

• Hourly Plot

• Monthly Chart

• Adaptive Chart

• PMV Polygon

• Psychrometric Chart

• UTCI Polygon

• Benefit Sky Matrix

• Cumulative Sky Matrix

• Sky Dome

• SunPath

• Radiation Dome

• Radiation Rose

• Wind Profile

• Wind Rose

- [source code]

Perform a "mass" arithmetic operation between Data Collections. For example, adding a list of Data Collections into one Data Collection.

Note that Data Collections must be aligned in order for this component to run successfully.

Using this component will often be much faster and more elegant compared to deconstructing the data collection, performing the operation with native Grasshopper components, and rebuilding the collection.

Inputs

• data [Required]

A list of Data Collections to be used in the arithmetic operation.

• operator

Text for the operator to use between the Data Collections. Valid examples include (+, -, *, /). By default this is + for addition.

• type

Optional text for a new "type" key in the Data Collection's metadata. This will usually show up in most Ladybug visualiztions and it should usually change for most types of operations.

Outputs

• data

A Ladybug data collection object derived from the operation between the two data inputs.

- [source code]

Create a chart in the Rhino scene with data organized by month.

Data will display as a bar chart if the input data is monthly or daily. If the data is hourly or sub-hourly, it will be plotted with lines and/or a colored mesh that shows the range of the data within specific percentiles.

Inputs

• data [Required]

Data collections (eg. HourlyCollection, MonthlyCollection, or DailyCollection), which will be used to generate the monthly chart.

• base_pt

An optional Point3D to be used as a starting point to generate the geometry of the chart (Default: (0, 0, 0)).

• x_dim

An optional number to set the X dimension of each month of the chart. (Default: 10 meters).

• y_dim

An optional number to set the Y dimension of the entire chart (Default: 40 meters).

• stack

Boolean to note whether multiple connected monthly or daily input _data with the same units should be stacked on top of each other. Otherwise, all bars for monthly/daily data will be placed next to each other. (Default: False).

• percentile

An optional number between 0 and 50 to be used for the percentile difference from the mean that hourly data meshes display at. For example, using 34 will generate hourly data meshes with a range of one standard deviation from the mean. Note that this input only has significance when the input data collections are hourly. (Default: 34)

• time_marks

Boolean to note whether the month labels should be replaced with marks for the time of day in each month. This is useful for displaying hourly data, particularly when the input data is only for a month and not the whole year.

• global_title

A text string to label the entire entire chart. It will be displayed in the lower left of the output chart. The default will display the metadata of the input _data.

• y_axis_title

A text string to label the Y-axis of the chart. This can also be a list of 2 Y-axis titles if there are two different types of data connected to _data and there are two axes labels on either side of the chart. The default will display the data type and units of the first (and possibly the second) data collection connected to _data.

• legend_par

An optional LegendParameter object to change the display of the chart (Default: None).

Outputs

• report

...

• data_mesh

A list of colored meshes that represent the different input data. These meshes will resemble a bar chart in the case of monthly or daily data and will resemble a band between two ranges for hourly and sub-hourly data. Multiple lists of meshes will be output for several input data streams.

• data_lines

A list of polylines that represent the input data. These will represent the average or total at each hour whenever the input data is hourly or monthly-per-hour data.

• col_lines

A list of colored polylines that represent the input data. These will only be output when the input data are monthly per hour.

• legend

Geometry representing the legend for the chart, noting which colors correspond to which input data.

• borders

A list of lines and polylines representing the axes and intervals of the chart.

• labels

A list of text objects that label the borders with month name and the intervals of the Y-axis.

• y_title

A text oject for the Y-axis title.

• title

A text object for the global_title.

• vis_set

An object containing VisualizationSet arguments for drawing a detailed version of the Monthly Chart in the Rhino scene. This can be connected to the "LB Preview Visualization Set" component to display this version of the Monthly Chart in Rhino.

- [source code]

Create a colored plot of any hourly data collection.

Inputs

• data [Required]

A HourlyContinuousCollection or HourlyDiscontinuousCollection which will be used to generate the hourly plot.

• base_pt

An optional Point3D to be used as a starting point to generate the geometry of the plot (Default: (0, 0, 0)).

• x_dim

A number to set the X dimension of the mesh cells (Default: 1 meters).

• y_dim

A number to set the Y dimension of the mesh cells (Default: 4 meters).

• z_dim

A number to set the Z dimension of the entire chart. This will be used to make the colored_mesh3d of the chart vary in the Z dimension according to the data. The value input here should usually be several times larger than the x_dim or y_dim in order to be noticable (e.g. 100). If 0, the colored_mesh3d will simply be flat. (Default: 0).

• reverse_y

Boolean to note whether the Y-axis of the chart is reversed If True, time over the course of the day will flow from the top of the chart to the bottom instead of the bottom to the top.

• clock_24

Boolean to note whether the hour labels on the Y-Axis of the chart should be in 24-hour clock format (eg. 18:00) or they should be in 12-hour clock format (eg. 6PM).

• legend_par

An optional LegendParameter object to change the display of the HourlyPlot. This can also be a list of legend parameters to be applied to the different connected _data.

• statement

A conditional statement as a string (e.g. a > 25). The variable of the first data collection should always be named 'a' (without quotations), the variable of the second list should be named 'b', and so on. For example, if three data collections are connected to _data and the following statement is applied: '18 < a < 26 and b < 80 and c > 2' The resulting collections will only include values where the first data collection is between 18 and 26, the second collection is less than 80 and the third collection is greater than 2.

• period

A Ladybug analysis period to be applied to all of the input _data.

Outputs

• report

...

• mesh

A colored mesh derived from the input _data. Multiple meshes will be output for several data collections are input.

• legend

Geometry representing the legend for each mesh.

• borders

A list of lines and polylines representing different time intervals of the plot.

• labels

A list of text objects that label the borders with the time intervals that they demarcate.

• title

A text object for the global_title.

• vis_set

An object containing VisualizationSet arguments for drawing a detailed version of the Hourly Plot in the Rhino scene. This can be connected to the "LB Preview Visualization Set" component to display this version of the Hourly Plot in Rhino.

- [source code]

Calculate the percentage of people dissatisfied from radiant asymmetry.

The comfort functions used here come from Figure 5.2.4.1 of ASHRAE 55 2010. Note that, if the resulting input results in a PPD beyond what is included in this Figure, the maximum PPD will simply be returned.

Inputs

• radiant_diff [Required]

A number for the the radiant temperature difference between two sides of the same plane where an occupant is located [C]. This can also be a data collection representing the radiant temperature difference over time [C].

• asymmetry_type [Required]

Text or an integer that representing the type of radiant asymmetry being evaluated. Occupants are more sensitive to warm ceilings and cool walls than cool ceilings and warm walls. Choose from the following options.

* 0 = WarmCeiling

* 1 = CoolWall

* 2 = CoolCeiling

* 3 = WarmWall

Outputs

• ppd

The percentage of people dissatisfied (PPD) for the input radiant asymmetry.

- [source code]

Draw an adaptive comfort chart in the Rhino scene and plot a set of prevailing and indoor operative temperature values on it.

Connected data can include outdoor temperatures from imported EPW weather data as well as indoor temperatures from an energy simulation.

Inputs

• out_temp [Required]

Outdoor temperatures in one of the following formats:

* A Data Collection of outdoor dry bulb temperatures recorded overthe entire year. This Data Collection must be continouous and must either be an Hourly Collection or Daily Collection. In the event that the input adapt_par_ has a _avgm_or_runmean_ set to True, Monthly collections are also acceptable here. Note that, because an annual input is required, this input collection does not have to align with the _air_temp or _mrt_ inputs. 

* A Data Collection of prevailing outdoor temperature values in C.This Data Collection must align with the _air_temp or _mrt_ inputs and bear the PrevailingOutdoorTemperature data type in its header. 

* A single prevailing outdoor temperature value in C to be usedfor all of the _air_temp or _mrt_ inputs. 

• air_temp [Required]

A hourly, daily, or sub-hourly data collection of temperature values for indoor air temperature (or operative temperature). If this input data collection is in in Farenheit, the entire chart will be drawn using IP units.

• mrt

A hourly, daily, or sub-hourly data collection for mean radiant temperature (MRT) in C. Default is the same as the air_temp, effectively interpreting the _air_temp as operative tempreature.

• air_speed

A number for the air speed values in m/s. Note that higher air speeds in the adaptive model only widen the upper boundary of the comfort range at temperatures above 24 C and will not affect the lower temperature of the comfort range. Default is a very low speed of 0.1 m/s.

• adapt_par

Optional comfort parameters from the "LB Adaptive Comfort Parameters" component to specify the criteria under which conditions are considered acceptable/comfortable. The default will use ASHRAE-55 adaptive comfort criteria.

• base_pt

A point to be used as the bottom-left-most point from which all geometry of the plot will be generated. (Default: (0, 0, 0)).

• scale

A number to set the dimensions of the chart. (Default: 1).

• prevail_range

An optional domain (or number for the upper temperature), which will be used to set the lower and upper boundaries of prevailing outdoor temperature on the chart. These should be in Celsius if the chart is plotted in Celsius and and Fahrenheit if it is in Fahrenheit. The default is 10C to 33C when ASHRAE-55 is used and 10C to 30C when the EN standard is used. This translates to 50F to 92F for ASHRAE-55 and 50F to 86F for the EN standard.

• operat_range

An optional domain (or number for the upper temperature), which will be used to set the lower and upper boundaries of indoor operative temperature on the chart. These should be in Celsius if the chart is plotted in Celsius and and Fahrenheit if it is in Fahrenheit. The default is 14C to 40C, which translates to 58F to 104F.

• legend_par

An optional LegendParameter object from the "LB Legend Parameters" component to change the display of the Adaptive Chart.

• data

Optional data collections, which are aligned with the input air_temp, which will be output from the data of this component and can be used to color points with data. This data can also be used along with the statement below to select out data that meets certain conditions.

• statement

A conditional statement as a string (e.g. a > 25). The variable of the first data collection should always be named 'a' (without quotations), the variable of the second list should be named 'b', and so on. For example, if three data collections are connected to _data and the following statement is applied: '10 < a < 30 and b < 33 and c > 2' The resulting collections will only include values where the first data collection is between 10 and 30, the second collection is less than 33 and the third collection is greater than 2. For this component, the input indoor air temperature will always be the last (or seconf-to-last) letter and this will be followed by the input mrt (if it is present).

• period

A Ladybug analysis period to be applied to the _out_temp and air_temp of the input data.

Outputs

• report

...

• total_comfort

The percent of the data on the adaptive chart that is inside the comfort polygon.

• comfort_data

Data collection or a 0/1 value noting whether each of the data points on the chart lies inside of the comfort polygon. This can be connected to the "LB Create Legend" component to generate a list of colors that can be used to color the points output from "LB Adaptive Chart" component to see exactly which points are comfortable and which are not. Values are one of the following: 0 = uncomfortable 1 = comfortable

• condition_data

Data collection of integers noting the thermal status of the human subject according to the assigned comfort parameters. This can be connected to the "LB Create Legend" component to generate a list of colors that can be used to color the points output from "LB Adaptive Chart" component to see exactly which points are hot, cold, and neutral. Values are one of the following:

* -1 = cold

*  0 = netural

* +1 = hot

• polygon

Brep representing the range of comfort for the input parameters.

• title

Text objects for the chart title and axes titles as well as a polyline for the outer border of the chart.

• prevail_lines

A list of line segments and text objects for the outdoor prevailing temperature labels on the chart.

• operative_lines

A list of line segments and text objects for the indoor operative temperature labels on the chart.

• mesh

A colored mesh showing the number of input hours that happen in each part of the adaptive chart.

• legend

A colored legend showing the number of hours that correspond to each color.

• points

Points representing each of the input prevailing and operative temperature values. By default, this ouput is hidden and it should be connected it to a native Grasshopper preview component to view it.

• data

The input data_ with the input statements or the periods applied to it. These can be deconstructed with the "LB Deconstruct Data" component and the resulting values can be plugged into the "LB Create Legend" component to generate colors that can be used to color the points above using the native Grasshopper "Custom Preview" component.

• vis_set

An object containing VisualizationSet arguments for drawing a detailed version of the Adaptive Chart in the Rhino scene. This can be connected to the "LB Preview Visualization Set" component to display this version of the Adaptive Chart in Rhino.

- [source code]

Draw a psychrometric chart in the Rhino scene and plot a set of temperatures and humidity values on it.

Connected data can be either outdoor temperature and humidty from imported EPW weather data or indoor temperature and humidity ratios from an energy simulation.

Inputs

• temperature [Required]

A hourly, daily, or sub-hourly data collection of temperature values or a single temperature value in Celcius to be used for the whole analysis. If this input data collection is in in Farenheit, the entire chart will be drawn using IP units. Operative temperature should be used if it is available. Otherwise, air temperature (aka. dry bulb temperature) is suitable.

• rel_humidity [Required]

A hourly, daily, or sub-hourly data collection of relative humidity values in % or a single relative humidity value to be used for the whole analysis. Note that the input data collection here must align with the _temperature input.

• pressure

A data collection of atmospheric pressure in Pascals or a single number for the average air pressure across the data plotted on the chart. It is recommended that the barometric pressure from the "Import EPW" component be used here as the default is not sutiable for higher elevations. (Default: 101325 Pa; pressure at sea level).

• base_pt

A point to be used as the bottom-left-most point from which all geometry of the plot will be generated. (Default: (0, 0, 0)).

• scale

A number to set the dimensions of the chart. (Default: 1).

• temp_range

An optional domain (or number for the upper temperature), which will be used to set the lower and upper boundaries of temperature on the psychrometric chart. (Default: -20 to 55 when the chart is in SI; -5 to 115 when the chart is in IP).

• plot_wet_bulb

Boolean to note whether the psychrometric chart should be ploted with lines of constant enthalpy (False) or lines of constant wet bulb temperature (True). (Default: False).

• legend_par

An optional LegendParameter object from the "LB Legend Parameters" component to change the display of the Pyschrometric Chart.

• data

Optional data collections, which are aligned with the input _temperature and rel_humidity, which will be output from the data of this component and can be used to color points with data. This data can also be used along with the statement below to select out data that meets certain conditions.

• statement

A conditional statement as a string (e.g. a > 25). The variable of the first data collection should always be named 'a' (without quotations), the variable of the second list should be named 'b', and so on. For example, if three data collections are connected to _data and the following statement is applied: '18 < a < 26 and b < 80 and c > 2' The resulting collections will only include values where the first data collection is between 18 and 26, the second collection is less than 80 and the third collection is greater than 2. For this component, temperature will always be the second-to-last letter and relative humidity will be the last letter.

• period

A Ladybug analysis period to be applied to the _temperature and rel_humidity of the input data.

Outputs

• report

...

• title

Text objects for the chart title and axes titles as well as a polyline for the outer border of the chart. Note that the polyline for the border excludes the saturation line.

• temp_lines

A list of line segments and text objects for the temperature labels on the chart.

• rh_lines

A list of curves and text objects for the relative humidity labels on the chart.

• hr_lines

A list of line segments and text objects for the humidty ratio labels on the chart.

• enth_wb_lines

A list of line segments and text objects for the enthalpy or wet bulb temperature labels on the chart.

• mesh

A colored mesh showing the number of input hours that happen in each part of the psychrometric chart.

• legend

A colored legend showing the number of hours that correspond to each color.

• points

Points representing each of the input temperature and humidity values. By default, this ouput is hidden and it should be connected it to a native Grasshopper preview component to view it.

• data

The input data_ with the input statements or the periods applied to it. These can be deconstructed with the "LB Deconstruct Data" component and the resulting values can be plugged into the "LB Create Legend" component to generate colors that can be used to color the points above using the native Grasshopper "Custom Preview" component.

• psych_chart

A Psychrometric Chart object, which can be connected to any of the "Comfort Polygon" components in order to plot polygons on the chart and perform thermal comfort analyses on the data.

• vis_set

An object containing VisualizationSet arguments for drawing a detailed version of the Psychrometric Chart in the Rhino scene. This can be connected to the "LB Preview Visualization Set" component to display this version of the Psychrometric Chart in Rhino.

- [source code]

Calculate relative humidity from Dry Bulb Temperature and Dew Point Temperature.

Inputs

• dry_bulb [Required]

A value or data collection representing dry bulb temperature [C]

• dew_point [Required]

A value or data collection representing dew point temperature [C]

Outputs

• rel_humid

A data collection or value indicating the relative humidity [%]

-

Visualize a sky matrix from the "LB Cumulative Sky Matrix" component as a colored dome, subdivided into patches with a radiation value for each patch.

Inputs

• sky_mtx [Required]

A Sky Matrix from the "LB Cumulative Sky Matrix" component or the "LB Benefit Sky Matrix" component, which describes the radiation coming from the various patches of the sky.

• center_pt

A point for the center of the dome. (Default: (0, 0, 0))

• scale

A number to set the scale of the sky dome. The default is 1, which corresponds to a radius of 100 meters in the current Rhino model's unit system.

• projection

Optional text for the name of a projection to use from the sky dome hemisphere to the 2D plane. If None, a 3D sky dome will be drawn instead of a 2D one. (Default: None) Choose from the following:

• irradiance

Boolean to note whether the sky dome should be plotted with units of cumulative Radiation (kWh/m2) [False] or with units of average Irradiance (W/m2) [True]. (Default: False).

• show_comp

Boolean to indicate whether only one dome with total radiation should be displayed (False) or three domes with the solar radiation components (total, direct, and diffuse) should be shown. (Default: False).

• legend_par

An optional LegendParameter object to change the display of the sky dome (Default: None).

Outputs

• report

...

• mesh

A colored mesh representing the intensity of radiation for each of the sky patches within the sky dome.

• compass

A set of circles, lines and text objects that mark the cardinal directions in relation to the sky dome.

• legend

A legend showing the kWh/m2 or W/m2 values that correspond to the colors of the mesh.

• title

A text object for the title of the sky dome.

• patch_vecs

A list of vectors for each of the patches of the sky dome. All vectors are unit vectors and point from the center towards each of the patches. They can be used to construct visualizations of the rays used to perform radiation analysis.

• patch_values

Radiation values for each of the sky patches in kWh/m2 or W/m2. This will be one list if show_comp_ is "False" and a list of 3 lists (aka. a Data Tree) for total, direct, diffuse if show_comp_ is "True".

• mesh_values

Radiation values for each face of the dome mesh in kWh/m2. This can be used to post-process the radiation data and then regenerate the dome visualization using the mesh output from this component and the "LB Spatial Heatmap" component. Examples of useful post- processing include converting the units to something other than kWh/m2, inverting the +/- sign of radiation values depending on whether radiation is helpful or harmful to building thermal loads, etc. This will be one list if show_comp_ is "False" and a list of 3 lists (aka. a Data Tree) for total, direct, diffuse if show_comp_ is "True".

• vis_set

An object containing VisualizationSet arguments for drawing a detailed version of the Sky Dome in the Rhino scene. This can be connected to the "LB Preview Visualization Set" component to display this version of the Sky Dome in Rhino.

-

Get a matrix representing the benefit/harm of radiation based on temperature data.

When this sky matrix is used in radiation studies or to produce radiation graphics, positive values represent helpful wintertime sun energy that can offset heating loads during cold temperatures while negative values represent harmful summertime sun energy that can increase cooling loads during hot temperatures.

Radiation benefit skies are particularly helpful for evaluating building massing and facade designs in terms of passive solar heat gain vs. cooling energy increase.

This component uses Radiance's gendaymtx function to calculate the radiation for each patch of the sky. Gendaymtx is written by Ian Ashdown and Greg Ward. Morere information can be found in Radiance manual at: http://www.radiance-online.org/learning/documentation/manual-pages/pdfs/gendaymtx.pdf

Inputs

• north

A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East. This can also be Vector for the direction to North. (Default: 0)

• location [Required]

A ladybug Location that has been output from the "LB Import EPW" component or the "LB Construct Location" component.

• temperature [Required]

An annual hourly DataCollection of temperature, which will be used to establish whether radiation is desired or not for each time step.

• bal_temp

The temperature in Celsius between which radiation switches from being a benefit to a harm. Typical residential buildings have balance temperatures as high as 18C and commercial buildings tend to have lower values around 12C. (Default 15C).

• bal_offset

The temperature offset from the balance temperature in Celsius where radiation is neither harmful nor helpful. (Default: 2).

• direct_rad [Required]

An annual hourly DataCollection of Direct Normal Radiation such as that which is output from the "LB Import EPW" component or the "LB Import STAT" component.

• diffuse_rad [Required]

An annual hourly DataCollection of Diffuse Horizontal Radiation such as that which is output from the "LB Import EPW" component or the "LB Import STAT" component.

• hoys

A number or list of numbers between 0 and 8760 that respresent the hour(s) of the year for which to generate the sky matrix. The "LB Calculate HOY" component can output this number given a month, day and hour. The "LB Analysis Period" component can output a list of HOYs within a certain hour or date range. By default, the matrix will be for the entire year.

• high_density

A Boolean to indicate whether the higher-density Reinhart sky matrix should be generated (True), which has roughly 4 times the sky patches as the (default) original Tregenza sky (False). Note that, while the Reinhart sky has a higher resolution and is more accurate, it will result in considerably longer calculation time for incident radiation studies. The difference in sky resolution can be observed with the "LB Sky Dome" component. (Default: False).

• ground_ref

A number between 0 and 1 to note the average ground reflectance that is associated with the sky matrix. (Default: 0.2).

• folder

The folder in which the Radiance commands are executed to produce the sky matrix. If None, it will be written to Ladybug's default EPW folder.

Outputs

• report

...

• sky_mtx

A sky matrix object containing the radiation benefit/harm coming from each patch of the sky. This can be used for a radiation study, a radition rose, or a sky dome visualization. It can also be deconstructed into its individual values with the "LB Deconstruct Matrix" component.

-

Draw thermal comfort polygons on a Psychrometric Chart using the PMV model for indoor thermal comfort.

This component can also plot passive strategy polygons on the psychrometric chart and can compute the number of hours that lie inside each of the comfort / strategy polygons.

Inputs

• psych_chart [Required]

A hourly, daily, or sub-hourly data collection of temperature values or a single temperature value in Celcius to be used for the whole analysis. If this input data collection is in in Farenheit, the entire chart will be drawn using IP units. Operative temperature should be used if it is available. Otherwise, air temperature (aka. dry bulb temperature) is suitable.

• mrt

A number or list of numbers for the mean radiant temperature. These should be in Celsius if the Psychrometric Chart is in SI and Farenheit if the Psychrometric Chart is in IP. If None, a polygon for operative temperature will be plot, assuming that radiant temperature and air temperature are the same. (Default: None).

• air_speed

A number or list of numbers for the air speed values in m/s. If None, a low air speed of 0.1 m/s wil be used for all polygons. (Default: None).

• met_rate

A number or list of numbers for the metabolic rate in met. If None, a met rate of 1.1 met will be used for all polygons, indicating a human subject who is seated, typing. (Default: None).

• clothing

A number or list of numbers for the clothing level in clo. If None, a clo level of 0.7 clo will be used for all polygons, indicating a human subject with a long sleeve shirt and pants. (Default: None).

• pmv_par

Optional PMVParameter object to specify parameters under which conditions are considered acceptable. If None, default will assume a PPD threshold of 10%, no absolute humidity constraints and a still air threshold of 0.1 m/s.

• merge_poly

Boolean to note whether all comfort polygons should be merged into a single polygon instead of separate polygons for each set of input conditions. (Default: False).

• strategies

An optional text input of passive strategies to be plot on the psychrometric chart as polygons. It is recommended that the "LB Passive Strategy" component be used to select which polygons to plot.

• strategy_par

Optional passive strategy parameters from the "LB Passive Strategy Parameters" component. This can be used to adjust various inputs used to generate strategy polygons including the maximum comfortable air speed, the building balance temperature, and the temperature limits for thermal mass and night flushing.

• solar_data

An annual hourly continuous data collection of irradiance (or radiation) in W/m2 (or Wh/m2) that aligns with the data points on the psychrometric chart. This is only required when plotting a "Passive Solar Heating" strategy polygon on the chart. The irradiance values should be incident on the orientation of the passive solar heated windows. So using global horizontal radiation assumes that all windows are skylights (like a greenhouse). The "LB Directional Irradiance" component can be used to get irradiance data for a specific surface orientation.

Outputs

• report

...

• total_comfort

The percent of the data on the psychrometric chart that are inside all comfort and passive strategy polygons.

• total_comf_data

Data collection or a 0/1 value noting whether each of the data points on the psychrometric chart lies inside of a comfort polygon or a strategy polygon. This can be connected to the "LB Create Legend" component to generate a list of colors that can be used to color the points output from "LB Psychrometric Chart" component to see exactly which points are comfortable and which are not. Values are one of the following: 0 = uncomfortable 1 = comfortable

• polygon_names

A list of names for each of the polygons. This will include both the comfort polygons and the passive strategy polygons. The order of these names correspondsto the total_strategies and strategies_data outputs.

• polygon_comfort

The percent of the input data that are in each of the comfort or passive strategy polygons. Each number here corresponds to the names in the polygon_names output above.

• polygon_data

A list of data collections or 0/1 values indicating whether each of the data points on the psychrometric chart lies inside each of the comfort or a strategy polygons. Each data collection or here corresponds to the names in the polygon_names output above. Values are one of the following: 0 = uncomfortable 1 = comfortable

• comfort_poly

Brep representing the range of comfort for the input mrt, air speed, metabolic rate and clothing level. If multiple values have been input, multiple polygons will be output here.

• strategy_poly

Brep representing the area of the chart made comfortable by any input passive strategies. If multiple strategies have been input to the strategies_ input, multiple polygons will be output here.

-

Get a matrix containing radiation values from each patch of a sky dome.

Creating this matrix is a necessary pre-step before doing incident radiation analysis with Rhino geometry or generating a radiation rose.

This component uses Radiance's gendaymtx function to calculate the radiation for each patch of the sky. Gendaymtx is written by Ian Ashdown and Greg Ward. Morere information can be found in Radiance manual at: http://www.radiance-online.org/learning/documentation/manual-pages/pdfs/gendaymtx.pdf

Inputs

• north

A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East. This can also be Vector for the direction to North. (Default: 0)

• location [Required]

A ladybug Location that has been output from the "LB Import EPW" component or the "LB Construct Location" component.

• direct_rad [Required]

An annual hourly DataCollection of Direct Normal Radiation such as that which is output from the "LB Import EPW" component or the "LB Import STAT" component.

• diffuse_rad [Required]

An annual hourly DataCollection of Diffuse Horizontal Radiation such as that which is output from the "LB Import EPW" component or the "LB Import STAT" component.

• hoys

A number or list of numbers between 0 and 8760 that respresent the hour(s) of the year for which to generate the sky matrix. The "LB Calculate HOY" component can output this number given a month, day and hour. The "LB Analysis Period" component can output a list of HOYs within a certain hour or date range. By default, the matrix will be for the entire year.

• high_density

A Boolean to indicate whether the higher-density Reinhart sky matrix should be generated (True), which has roughly 4 times the sky patches as the (default) original Tregenza sky (False). Note that, while the Reinhart sky has a higher resolution and is more accurate, it will result in considerably longer calculation time for incident radiation studies. The difference in sky resolution can be observed with the "LB Sky Dome" component. (Default: False).

• ground_ref

A number between 0 and 1 to note the average ground reflectance that is associated with the sky matrix. (Default: 0.2).

• folder

The folder in which the Radiance commands are executed to produce the sky matrix. If None, it will be written to Ladybug's default EPW folder.

Outputs

• report

...

• sky_mtx

A sky matrix object containing the radiation coming from each patch of the sky. This can be used for a radiation study, a radition rose, or a sky dome visualization. It can also be deconstructed into its individual values with the "LB Deconstruct Matrix" component.

-

Draw thermal comfort polygons on a Psychrometric Chart using the UTCI outdoor thermal comfort model.

Inputs

• psych_chart [Required]

A hourly, daily, or sub-hourly data collection of temperature values or a single temperature value in Celcius to be used for the whole analysis. If this input data collection is in in Farenheit, the entire chart will be drawn using IP units. Operative temperature should be used if it is available. Otherwise, air temperature (aka. dry bulb temperature) is suitable.

• mrt

A number or list of numbers for the mean radiant temperature. These should be in Celsius if the Psychrometric Chart is in SI and Farenheit if the Psychrometric Chart is in IP. If None, a polygon for operative temperature will be plot, assuming that radiant temperature and air temperature are the same. (Default: None).

• wind_speed

A number or list of numbers for for the meteorological wind speed values in m/s (measured 10 m above the ground). If None, this will default to a low wind speed of 0.5 m/s, which is the lowest input speed that is recommended for the UTCI model.

• utci_par

Optional UTCIParameter object to specify parameters under which conditions are considered acceptable. If None, default will assume comfort thresholds consistent with those used by meteorologists to categorize outdoor conditions.

• merge_poly

Boolean to note whether all comfort polygons should be merged into a single polygon instead of separate polygons for each set of input conditions. (Default: False).

• plot_stress

Boolean to note whether polygons for heat/cold stress should be plotted in the output. This will include 3 polygons on either side of the comfort polygon(s) for...

Outputs

• report

...

• total_comfort

The percent of the data on the psychrometric chart that are inside all comfort polygons.

• total_comf_data

Data collection or a 0/1 value noting whether each of the data points on the psychrometric chart lies inside of a comfort polygon. This can be connected to the "LB Create Legend" component to generate a list of colors that can be used to color the points output from "LB Psychrometric Chart" component to see exactly which points are comfortable and which are not. Values are one of the following: 0 = uncomfortable 1 = comfortable

• polygons

A list of Breps representing the range of comfort (or heat/cold stress) for the input mrt and air speed.

• polygon_names

A list of names for each of the polygons which correspond with the polygons output above. This will include both the comfort polygons and the cold/heat stress polygons.

• polygon_data

A list of data collections or 0/1 values indicating whether each of the data points on the psychrometric chart lies inside each of the comfort polygons. Each data collection or here corresponds to the names in the polygon_names output above. Values are one of the following: 0 = outside 1 = inside

-

Output a Sunpath (aka. sun plot) graphic into the Rhino scene.

The component also outputs sun vectors that can be used for solar access analysis and shading design.

Inputs

• north

A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East. This can also be Vector for the direction to North. (Default: 0)

• location [Required]

A ladybug Location that has been output from the "LB Import EPW" component or the "LB Construct Location" component.

• hoys

A number or list of numbers between 0 and 8760 that represent the hour of the year at which to evaluate the sun position. The "LB Calculate HOY" component can output this number given a month, day and hour. The "LB Analysis Period" component can output a list of HOYs within a certain hour or date range.

• dl_saving

An optional analysis period for daylight saving time. If None, no daylight saving time will be used. (Default: None)

• solar_time

A boolean to indicate if the input hours should be treated as solar time instead of standard or daylight time. (Default: False)

• center_pt

A point for the center of the sun path. (Default: (0, 0, 0))

• scale

A number to set the scale of the sun path. The default is 1, which corresponds to a radius of 100 meters in the current Rhino model's unit system.

• projection

Optional text for the name of a projection to use from the sky dome hemisphere to the 2D plane. If None, a 3D sun path will be drawn instead of a 2D one. (Default: None) Choose from the following:

• daily

Boolean to note whether the sunpath should display only one daily arc for each unique day in the input hoys_ (True) or whether the output sun path geometry should be for the entire year, complete with analemmas for all sun-up hours and a daily arc for each month (False). (Default: False)

• data

Optional HourlyContinuousCollection objects, which will be used to generate colors that align with each of the sun_pts. This data can also be used along with the statement_ below to select out sun positions that meet certain conditions.

• statement

A conditional statement as a string (e.g. a > 25). The variable of the first data collection should always be named 'a' (without quotations), the variable of the second list should be named 'b', and so on. For example, if three data collections are connected to _data and the following statement is applied: '18 < a < 26 and b < 80 and c > 2' The resulting collections will only include values where the first data collection is between 18 and 26, the second collection is less than 80 and the third collection is greater than 2.

• legend_par

An optional LegendParameter object to change the display of the data on the sun path. This can also be a list of legend parameters to be applied to the different connected data_.

Outputs

• report

Reports, errors, warnings, etc.

• vectors

Vector(s) indicating the direction of sunlight for each sun position on the sun path. Note that these vectors point downwards towards the ground.

• altitudes

Number(s) indicating the sun altitude(s) in degrees for each sun position on the sun path.

• azimuths

Number(s) indicating the sun azimuths in degrees for each sun position on the sun path.

• hoys

The hour of the year for each sun positions on the sun path.

• sun_pts

Point(s) representing the location of the sun on the sunpath.

• analemma

A set of curves that mark the hourly positions of the sun throughout the different months of the year.

• daily

A set of arcs that mark the path of the sun across the sky dome over the course of a day.

• compass

A set of circles, lines and text objects that mark the cardinal directions in relation to the sun path.

• legend

Geometry representing the legend for the input data_. Will be None if no _data is connected.

• title

A text object for the title of the sunpath.

• color_pts

A list of points colored with the input data_, which will display in the Rhino scene in accordance with the legend. Note that the text representation of these objects bears the RGB color of each point. So casting this output to text and then to a color will yeild color objects that can be used for previewing other types of geometry with the input data_. Will be None if no _data is connected.

• vis_set

An object containing VisualizationSet arguments for drawing a detailed version of the Sunpath in the Rhino scene. This can be connected to the "LB Preview Visualization Set" component to display this version of the Sunpath in Rhino.

- [source code]

Create a plot of any hourly data by wind directions.

Inputs

• north

An optional number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East. This can also be Vector for the direction to North

• data [Required]

A HourlyContinuousCollection or HourlyDiscontinuousCollection of values corresponding to the wind directions, which is "binned" by the direction intervals. This input usually consists of wind speed values, but is not limited to this data type. It can also be a list of data collections in which case multiple wind roses will be output.

• wind_direction [Required]

A HourlyContinuousCollection or HourlyDiscontinuousCollection of wind directions which will be used to "bin" the _data items for the windrose.

• dir_count

Number that determines the number of directions to the wind rose will display. The number of directions must be greater then three to plot the wind rose (Default: 36).

• center_pt

Point3D to be used as a starting point to generate the geometry of the plot (Default: (0, 0, 0)).

• show_calm

A boolean to indicate if the wind rose should display the fraction of time with zero wind speed using a circle in the center of the plot. The radius of this circle corresponds to the total amount of time with zero values divided by the number of directions. This means that the time period representing zero values is evenly distrobuted across all directions. (Default: False).

• show_avg

A boolean to note whether the average value in each wind direction bin should be displayed instead of the complete frequency of _data values. (Default: False).

• freq_dist

The distance for the frequency interval in model units. If show_calm_ is True, then the initial frequency interval corresponds to the number of calm hours in the data collection, which may not align with this freq_dist_ (Default: 5 meters)

• freq_hours

The number of hours in each frequency interval (Default: 50).

• max_freq_lines

A number representing the maximum frequency intervals in the rose, which determines the maximum amount of hours represented by the outermost ring of the windrose. Specifically, this number multiplied by the freq_hours parameter will equal the maximum hours in that outermost ring. By default, this value is determined by the wind direction with the largest number of hours (the highest frequency) but you may want to change this if you have several wind roses that you want to compare to each other. For example, if you have wind roses for different months or seasons, which each have different maximum frequencies.

• legend_par

An optional LegendParameter object to change the display of the WindRose plot. The number of segments in the legend determines the number of frequency intervals in the wind rose. If nothing is provided, a default LegendParameter object is computed using values from the wind data with 11 segments (Default: None).

• statement

A conditional statement as a string (e.g. a > 25) for the _data and _wind_direction inputs. The variable of the first collection input to _data should always be named 'a' (without quotations), the variable of the second list should be named 'b', and so on. The wind direction is always the last variable, though most statements won't have a need for it. For example, if three data collections are connected to _data and the following statement is applied: '18 < a < 26 and b < 80 and c > 2' The resulting collections will only include values where the first data collection is between 18 and 26, the second collection is less than 80 and the third collection is greater than 2.

• period

An optional Ladybug analysis period to be applied to all of the input data.

Outputs

• report

...

• mesh

A colored mesh representing the wind rose derived from the input data. Multiple meshes will be output for several data collections are input.

• compass

A set of circles, lines and text objects that mark the cardinal directions in relation to the wind rose.

• orient_line

Line geometries representing the edges (or "spokes") of the wind rose directions.

• freq_line

Polygon geometries representing the frequency intervals of the wind rose.

• windrose_line

Polygon geometries representing the windrose outlines. This output is hidden by default and should be connected to a native Grasshopper Geometry component in order to be visualized.

• legend

Geometry representing the legend for the wind rose.

• title

A text object for the global_title.

• prevailing

The predominant direction of the outpt wind rose in clockwise degrees from north. 0 is North, 90 is East, 180 is South, 270 is West.

• angles

A list of angles corresponding to each windrose directions.

• calm_hours

The number of hours with calm wind speeds. Only returns a value if the input _data is wind speed.

• histogram

The input _data in a histogram structure after it has gone through any of the statement or period operations input to this component.

• vis_set

An object containing VisualizationSet arguments for drawing a detailed version of the Wind Rose in the Rhino scene. This can be connected to the "LB Preview Visualization Set" component to display this version of the Wind Rose in Rhino.

- [source code]

Visualize the radiation falling on an object from different directions over a dome.

The Radiation Dome depicts the amount of solar energy received by all directions over a dome. This is useful for understanding the optimal orientation of solar panels and how the performance of the panel might change if it's orientation is off from the optimal position. It can also be used to identify the optimal wall orientation for passive solar heating when used with skies of radiation harm/benefit. When used with clear sky matrices, it can identify the orientations that result in the highest and lowest peak cooling load.

The Radiation Dome can be understood in different ways: 1) It's a 3D representation of the "LB Radiation Rose," depicting all tilt angles for that rose at once. 2) It's the reciprocal of the "LB Sky Dome," since it shows how the radiation from that sky falls onto a hemispherical object. 3) It's an radiation study of a hemisphere. The results here are effectively the same as running a hemisphere through the "LB Incident Radiation" component.

Inputs

• sky_mtx [Required]

A Sky Matrix from the "LB Cumulative Sky Matrix" component or the "LB Benefit Sky Matrix" component, which describes the radiation coming from the various patches of the sky.

• context

Rhino Breps and/or Rhino Meshes representing context geometry that can block solar radiation to the center of the radiation dome.

• az_count

An integer greater than or equal to 3, which notes the number of horizontal orientations to be evaluated on the dome. (Default: 72).

• alt_count

An integer greater than or equal to 3, which notes the number of vertical orientations to be evaluated on the dome. (Default: 18).

• center_pt

A point for the center of the radiation dome. (Default: (0, 0, 0))

• scale

A number to set the scale of the Radiation Dome. The default is 1, which corresponds to a radius of 100 meters in the current Rhino model's unit system.

• projection

Optional text for the name of a projection to use from the sky dome hemisphere to the 2D plane. If None, a 3D sky dome will be drawn instead of a 2D one. (Default: None) Choose from the following:

* Orthographic

* Stereographic

• irradiance

Boolean to note whether the radiation dome should be plotted with units of cumulative Radiation (kWh/m2) [False] or with units of average Irradiance (W/m2) [True]. (Default: False).

• show_comp

Boolean to indicate whether only one dome with total radiation should be displayed (False) or three domes with the solar radiation components (total, direct, and diffuse) should be shown. (Default: False).

• legend_par

An optional LegendParameter object to change the display of the radiation dome (Default: None).

Outputs

• report

...

• mesh

A colored mesh of a dome, representing the intensity of radiation/irradiance from different cardinal directions.

• compass

A set of circles, lines and text objects that mark the cardinal directions in relation to the radiation dome.

• legend

A legend showing the kWh/m2 or W/m2 values that correspond to the colors of the mesh.

• title

A text object for the title of the radiation dome.

• dir_vecs

A list of vectors for each of the directions the dome is facing. All vectors are unit vectors.

• dir_values

Radiation values for each of the dome directions in kWh/m2 or W/m2. This will be one list if show_comp_ is "False" and a list of 3 lists (aka. a Data Tree) for total, direct, diffuse if show_comp_ is "True".

• max_pt

A point on the radiation dome with the greatest amount of solar radiation/irradiance. For a radiation benefit sky, this is the orientation with the greatest benefit. This can be used to understand the optimalorientation of solar panels or the best direction to face for passive solar heating.

• max_info

Information about the direction with the greates amount of radiation. This includes the altitude, azimuth, and radiation/irradiance value.

• vis_set

An object containing VisualizationSet arguments for drawing a detailed version of the Radiation Dome in the Rhino scene. This can be connected to the "LB Preview Visualization Set" component to display this version of the Radiation Dome in Rhino.

- [source code]

Visualize a wind profile curve for a given terrain type.

Wind profiles assist with understanding how wind speed decreases as one approaches the ground or increases as one leaves the ground.

By default, the wind profile output by this component will be an average over the _met_wind_vel data collection (or it can be for a single meteorological wind velocity for point-in-time studies).

If a met_wind_dir_ data collection is connected, the wind profile will point in the direction of prevailing wind direction by default. A profile_dir_ can then be connected to understand the average wind profile from a specific cardinal direction (eg. NE).

Inputs

• north

A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East. This can also be Vector for the direction to North. (Default: 0)

• met_wind_vel [Required]

A data collection of meteorological wind speed measured at the met_height with the _met_terrian [m/s]. Typically, this comes from the "LB Import EPW" component. This can also be a single number for the meteorological wind speed in m/s.

• met_wind_dir

An optional number between 0 and 360 representing the degrees from north that the meteorological wind is blowing. 0 = North, 90 = East, 180 = South, 270 = West. This can also a data collection of meteorological wind directions. in which case the wind profile will be oriented towards the prevailing wind (unless a profile_dir_ is connected). When unspecified, the wind profile is simply drawn in the XY plane.

• profile_dir

An optional text string representing the cardinal direction that the wind profile represents. This input only has an effect when a data collection is connected for met_wind_dir_. It will be used to draw a wind profile for only the hours of the data collection where the wind is blowing in the specified direction. This can also be an integer that codes for a particular orientation. Choose from the following. 0 = N 1 = NE 2 = E 3 = SE 4 = S 5 = SW 6 = W 7 = NW

• terrain

Text string that sets the terrain class associated with the wind profile. This can also be an integer that codes for the terrain. (Default: city). Must be one the following. 0 = city - 50% of buildings above 21m over a distance of at least 2000m upwind. 1 = suburban - suburbs, wooded areas. 2 = country - open, with scattered objects generally less than 10m high. 3 = water - flat areas downwind of a large water body (max 500m inland).

• met_height

A number for the height above the ground at which the meteorological wind speed is measured in meters. (Default: 10 meters, which is the standard used by most airports and EPW files).

• met_terrain

Text string that sets the terrain class associated with the meteorological wind speed. This can also be an integer that codes for the terrain. (Default: country, which is typical of most airports where wind measurements are taken). Must be one the following. 0 = city - 50% of buildings above 21m over a distance of at least 2000m upwind. 1 = suburban - suburbs, wooded areas. 2 = country - open, with scattered objects generally less than 10m high. 3 = water - flat areas downwind of a large water body (max 500m inland).

• log_law

A boolean to note whether the wind profile should use a logarithmic law to determine wind speeds instead of the default power law, which is used by EnergyPlus. (Default: False).

• base_pt

A point that sets the ground level frm which the wind profile is drawn. By default, the profile is generated at the scene origin.

• max_speed

Script variable WindProfile

• profile_height

A number in meters to specify the maximum height of the wind profile. (Default: 30 meters).

• vec_spacing

A number in meters to specify the difference in height between each of the mesh arrows. (Default 2 meters).

• vec_scale

A number to denote the length dimension of a 1 m/s wind vector in meters. This can be used to change the scale of the wind vector meshes in relation to the height of the wind profile curve. (Default: 5 meters).

• legend_par

An optional LegendParameter object to change the display of the wind profile.

Outputs

• report

Reports, errors, warnings, etc.

• wind_speeds

A list of wind speeds in [m/s] that correspond to the wind vectors slong the height of the wind profile visualization.

• wind_vectors

A list of vectors that built the profile. Note that the magnitude of these vectors is scaled based on the vec_scale input and a vec_scale of 1 will make the magnitude of the vector equal to the wind speed in [m/s].

• anchor_pts

A list of anchor points for each of the vectors above, which correspond to the height above the ground for each of the vectors.

• mesh_arrows

A list of colored mesh objects that represent the wind speeds along the height of the wind profile.

• profile_curve

A curve outlining the wind speed as it changes with height.

• speed_axis

A list of line segments and text objects that mark the X axis, which relates to the wind speed in (m/s).

• height_axis

A list of line segments and text objects that mark the Y axis, which relates to the the height above the ground in Rhino model units.

• legend

A legend for the colored mesh_arrows, which notes their speed.

• title

A text object for the global_title.

• vis_set

An object containing VisualizationSet arguments for drawing a detailed version of the Wind Profile in the Rhino scene. This can be connected to the "LB Preview Visualization Set" component to display this version of the Wind Profile in Rhino.

- [source code]

Calculate the number of hours of direct sunlight received by geometry using sun vectors obtained from the "LB SunPath" component.

Such direct sun calculations can be used for shadow studies of outdoor enviroments or can be used to estimate glare potential from direct sun on the indoors.

Note that this component uses the CAD environment's ray intersection methods, which can be fast for geometries with low complexity but does not scale well for complex geometries or many test points. For such complex studies, honeybee-radiance should be used.

Inputs

• vectors [Required]

Sun vectors from the "LB SunPath" component, which will be used to determine the number of hours of direct sunlight received by the test _geometry.

• timestep

A positive integer for the number of timesteps per hour at which the "LB SunPath" component generated sun vectors. This is used to correctly interpret the time duration represented by each of the input sun vectors. (Default: 1 for 1 vector per hour).

• geometry [Required]

Rhino Breps and/or Rhino Meshes for which direct sun analysis will be conducted. If Breps are input, they will be subdivided using the _grid_size to yeild individual points at which analysis will occur. If a Mesh is input, direct sun analysis analysis will be performed for each face of this mesh instead of subdividing it.

• context

Rhino Breps and/or Rhino Meshes representing context geometry that can block sunlight to the test _geometry.

• grid_size [Required]

A positive number in Rhino model units for the size of grid cells at which the input _geometry will be subdivided for direct sun analysis. The smaller the grid size, the higher the resolution of the analysis and the longer the calculation will take. So it is recommended that one start with a large value here and decrease the value as needed. However, the grid size should usually be smaller than the dimensions of the smallest piece of the geometry and context in order to yield meaningful results.

• offset_dist

A number for the distance to move points from the surfaces of the input _geometry. Typically, this should be a small positive number to ensure points are not blocked by the mesh. (Default: 10 cm in the equivalent Rhino Model units).

• legend_par

Optional legend parameters from the "LB Legend Parameters" that will be used to customize the display of the results.

• cpu_count

An integer to set the number of CPUs used in the execution of the intersection calculation. If unspecified, it will automatically default to one less than the number of CPUs currently available on the machine or 1 if only one processor is available.

• run [Required]

Set to "True" to run the component and perform direct sun analysis.

Outputs

• report

...

• points

The grid of points on the test _geometry that are be used to perform the direct sun analysis.

• results

A list of numbers that aligns with the points. Each number indicates the number of hours of direct sunlight received by each of the points. Note that is is the number of hours out of the total number of connected _vectors.

• mesh

A colored mesh of the test _geometry representing the hours of direct sunlight received by this input _geometry

• legend

A legend showing the number of hours that correspond to the colors of the mesh.

• title

A text object for the study title.

• int_mtx

A Matrix object that can be connected to the "LB Deconstruct Matrix" component to obtain detailed vector-by-vector results of the study. Each sub-list of the matrix (aka. branch of the Data Tree) represents one of the points used for analysis. The length of each sub-list matches the number of _vectors used for the analysis. Each value in the sub-list is either a "1", indicating that the sun is visible for that vector, or a "0", indicating that the sun is not visible for that vector.

• Direct Sun Hours

• Incident Radiation

• View Factors

• View Percent

• View Rose

• Visibility Percent

• Human to Sky Relation

• Sky Mask

• Solar Envelope

• Surface Ray Tracing

• Shade Benefit

• Thermal Shade Benefit

• Set Rhino Sun

• View From Sun

• Real Time Incident Radiation

- [source code]

Visualize the solar energy falling on different direction as a rose.

By default, the Radiation Rose depicts the amount of solar energy received by a vertical wall facing each of the directions of the compass rose.

This is useful for understanding the radiation harm/benefit experienced by different building orientations or the orientations with the highest peak cooling load (for sky matrices of clear skies). The tilt_angle can be used to assess the solar energy falling on geometries that are not perfectly vertical, such as tilted photovoltaic panels.

Inputs

• sky_mtx [Required]

A Sky Matrix from the "LB Cumulative Sky Matrix" component or the "LB Benefit Sky Matrix" component, which describes the radiation coming from the various patches of the sky.

• context

Rhino Breps and/or Rhino Meshes representing context geometry that can block solar radiation to the center of the radiation rose.

• dir_count

An integer greater than or equal to 3, which notes the number of arrows to be generated for the radiation rose. (Default: 36).

• tilt_angle

A number between 0 and 90 that sets the vertical tilt angle (aka. the altitude) for all of the directions. By default, the Radiation Rose depicts the amount of solar energy received by a vertical wall (tilt_angle=0). The tilt_angle can be changed to a specific value to assess the solar energy falling on geometries that are not perfectly vertical, such as a tilted photovoltaic panel. (Default: 0).

• center_pt

A point for the center of the radiation rose. (Default: (0, 0, 0))

• scale

A number to set the scale of the Radiation Rose. The default is 1, which corresponds to a radius of 100 meters in the current Rhino model's unit system.

• arrow_scale

A fractional number to note the scale of the radiation rose arrows in relation to the entire graphic. (Default: 1).

• max_rad

An optional number to set the level of radiation or irradiance associated with the full radius of the rose. If unspecified, this is determined by the maximum level of radiation in the input data but a number can be specified here to fix this at a specific value. This is particularly useful when comparing different roses to one another.

• irradiance

Boolean to note whether the radiation rose should be plotted with units of cumulative Radiation (kWh/m2) [False] or with units of average Irradiance (W/m2) [True]. (Default: False).

• show_comp

Boolean to indicate whether only one rose with total radiation should be displayed (False) or three roses with the solar radiation components (total, direct, and diffuse) should be shown. (Default: False).

• legend_par

An optional LegendParameter object to change the display of the Radiation Rose.

Outputs

• report

...

• mesh

A colored mesh of arrows, representing the intensity of radiation from different cardinal directions.

• compass

A set of circles, lines and text objects that mark the cardinal directions in relation to the radiation rose.

• orient_lines

A list of line segments marking the orientation of each arrow.

• legend

A legend showing the kWh/m2 or W/m2 values that correspond to the colors of the mesh.

• title

A text object for the title of the radiation rose.

• dir_vecs

A list of vectors for each of the directions the rose is facing. All vectors are unit vectors.

• dir_values

Radiation values for each of the rose directions in kWh/m2 or W/m2. This will be one list if show_comp_ is "False" and a list of 3 lists (aka. a Data Tree) for total, direct, diffuse if show_comp_ is "True".

• vis_set

Script variable RadRose

- [source code]

Evaluate the percent view to the outdoors or sky from input geometry through context.

Such view calculations can be used to estimate the quality of a view to the outdoors from a given location on the indoors. They can also be used on the outdoors to evaluate the openness of street canyons to the sky, which has implications for the pedestrian expereince as well as the rate of radiant heat loss from urban surfaces and the sky at night.

Note that this component uses the CAD environment's ray intersection methods, which can be fast for geometries with low complexity but does not scale well for complex geometries or many test points. For such complex studies, honeybee-radiance should be used.

Inputs

• view_type [Required]

Text or an integer representing the type of view analysis to conduct. Choose from the following options. 0 - HorizontalRadial - The percentage of the 360 horizontal view plane that is not blocked by the context geometry. 1 - Horizontal30DegreeOffset - The percentage of the 360 horizontal view band bounded on top and bottom by a 30 degree offset from the horizontal plane. 30 degrees corresponds roughly to the vertical limit of human peripheral vision. 2 - Spherical - The percentage of the sphere surrounding each of the test points that is not blocked by context geometry. This is equivalent to a solid angle and gives equal weight to all portions of the sphere. 3 - SkyExposure - The percentage of the sky that is visible from each of the the test points. This is distinct from SkyView, which is the amount of sky seen by a surface. SkyExposure is equivalent to a solid angle and gives equal weight to all portions of the sky. 4 - SkyView - The percentage of the sky that is visible from the _geometry surfaces. This is distinct from SkyExposure, which treats each part of the sky with equal weight. SkyView weights the portions of the sky according to thier projection into the plane of the surface being evaluated. So SkyView for a horizontal surface would give more importance to the sky patches that are overhead vs. those near the horizon.

• resolution

A positive integer for the number of times that the original view vectors are subdivided. 1 indicates that 145 evenly-spaced vectors are used to describe a hemisphere, 2 indicates that 577 vectors describe a hemisphere, and each successive value will roughly quadruple the number of view vectors used. Setting this to a high value will result in a more accurate analysis but will take longer to run. (Default: 1).

• geometry [Required]

Rhino Breps and/or Rhino Meshes for which view analysis will be conducted. If Breps are input, they will be subdivided using the _grid_size to yeild individual points at which analysis will occur. If a Mesh is input, view analysis analysis will be performed for each face of this mesh instead of subdividing it.

• context

Rhino Breps and/or Rhino Meshes representing context geometry that can block view from the test _geometry.

• grid_size [Required]

A positive number in Rhino model units for the size of grid cells at which the input _geometry will be subdivided for direct sun analysis. The smaller the grid size, the higher the resolution of the analysis and the longer the calculation will take. So it is recommended that one start with a large value here and decrease the value as needed. However, the grid size should usually be smaller than the dimensions of the smallest piece of the geometry and context in order to yield meaningful results.

• offset_dist

A number for the distance to move points from the surfaces of the input _geometry. Typically, this should be a small positive number to ensure points are not blocked by the mesh. (Default: 10 cm in the equivalent Rhino Model units).

• geo_block

Set to "True" to count the input _geometry as opaque and set to "False" to discount the geometry from the calculation and only look at context that blocks the view. The default depends on the _view_type used. It is "True" for:

* SkyExposure

* SkyView

It is "False" for:

* HorizontalRadial

* Horizonta30DegreeOffset

* Spherical

• legend_par

Optional legend parameters from the "LB Legend Parameters" that will be used to customize the display of the results.

• cpu_count

An integer to set the number of CPUs used in the execution of the intersection calculation. If unspecified, it will automatically default to one less than the number of CPUs currently available on the machine or 1 if only one processor is available.

• run [Required]

Set to "True" to run the component and perform view analysis of the input _geometry.

Outputs

• report

...

• points

The grid of points on the test _geometry that are be used to perform the view analysis.

• view_vecs

A list of vectors which are projected from each of the points to evaluate view.

• results

A list of numbers that aligns with the points. Each number indicates the percentage of the view_vecs that are not blocked by context geometry.

• mesh

A colored mesh of the test _geometry representing the percentage of the input _geometry's view that is not blocked by context.

• legend

A legend that correspond to the colors of the mesh and shows the percentage of the view_vecs that are not blocked by context geometry.

• title

A text object for the study title.

• int_mtx

A Matrix object that can be connected to the "LB Deconstruct Matrix" component to obtain detailed vector-by-vector results of the study. Each sub-list (aka. branch of the Data Tree) represents one of the points used for analysis. The length of each sub-list matches the number of view_vecs used for the analysis. Each value in the sub-list is either a "1", indicating that the vector is visible for that vector, or a "0", indicating that the vector is not visible for that vector.

-

Calculate view factors from a point or plane to a set of geometries.

View factors are used in many thermal comfort calculations such as mean radiant temperture (MRT) or discomfort from radiant assymetry.

Inputs

• study_point [Required]

A point or plane from which view vectors will be projected. Note that, if a point is connected, all view vectors will be weighted evenly (assuming no directional bias). However, if a plane is connected, vectors will be weighted based on their angle to the plane normal, producing view factors for a surface in the connected plane. The first is useful for MRT calculations while the latter is needed for radiant assymetry calculations. This input can also be a list of several points or planes.

• view_geo [Required]

A list of breps, surfaces, or meshes to which you want to compute view factors. Note that by meshing and joining several goemtries together, the combined view factor to these geometries can be computed.

• context

Optional context geometry as breps, surfaces, or meshes that can block the view to the _view_geo.

• resolution

A positive integer for the number of times that the original view vectors are subdivided. 1 indicates that 145 evenly-spaced vectors are used to describe a hemisphere, 2 indicates that 577 vectors describe a hemisphere, and each successive value will roughly quadruple the number of view vectors used. Setting this to a high value will result in a more accurate analysis but will take longer to run. (Default: 1).

• cpu_count

An integer to set the number of CPUs used in the execution of the intersection calculation. If unspecified, it will automatically default to one less than the number of CPUs currently available on the machine or 1 if only one processor is available.

• run [Required]

Set to True to run the component and claculate view factors.

Outputs

• report

...

• view_vecs

A list of vectors which are projected from each of the points to evaluate view.

• patch_mesh

A mesh that represents the sphere of view patches around the _study_point at the input resolution. There is one face per patch and this can be used along with the int_mtx to create a colored visualization of patches corresponding to different geometries around the point. Specifically, the "LB Spaital Heatmap" component is recommended for such visualizations. Note that only one sphere is ever output from here and, in the event that several _study_points are connected, this sphere will be located at the first point. Therefore, to create visualizations for the other points, this mesh should be moved using the difference between the first study point and following study points.

• view_factors

A list of view factors that describe the fraction of sperical view taken up by the input surfaces. These values range from 0 (no view) to 1 (full view). If multiple _study_points have been connected, this output will be a data tree with one list for each point.

• int_mtx

A Matrix object that can be connected to the "LB Deconstruct Matrix" component to obtain detailed vector-by-vector results of the study. Each sub-list (aka. branch of the Data Tree) represents one of the points used for analysis. Each value in this sub-list corresponds to a vector used in the study and the value denotes the index of the geometry that each view vector hit. This can be used to identify which view pathces are intersected by each geometry. If no geometry is intersected by a given vector, the value will be -1.

-

Visualize the view openness around a given point as a colored mesh that fills a circle, sphere, or hemisphere (depending on the specified view type).

The input context will block the view, resulting in a decresed view rose size and a change in the view rose color.

Inputs

• context [Required]

Rhino Breps or Meshes representing context geometry that can block the view around the center point.

• center_pt [Required]

A point for the center of the view rose from which view openness will be evaluated.

• radius

A number for the radius of the view rose in Rhino model units. This is also used to evaluate the distance at which context is no longer able to block the view from the center point. This value should typically be increased if the view rose does not extend past the _context geometry. (Default: 100 meters in the current Rhino model units system).

• view_type

Text or an integer representing the type of view analysis to conduct. Choose from the following options. (Default: 0 - HorizontalRadial) 0 - HorizontalRadial - The percentage of the 360 horizontal view plane that is not blocked by the context geometry. 1 - Horizontal30DegreeOffset - The percentage of the 360 horizontal view band bounded on top and bottom by a 30 degree offset from the horizontal plane. 30 degrees corresponds roughly to the vertical limit of human peripheral vision. 2 - Spherical - The percentage of the sphere surrounding each of the test points that is not blocked by context geometry. This is equivalent to a solid angle and gives equal weight to all portions of the sphere. 3 - SkyExposure - The percentage of the sky that is visible from each of the the test points.

• resolution

A positive integer for the number of times that the original view vectors are subdivided. For a circle, 1 indicates that 72 evenly-spaced vectors are used to describe a circle, 2 indicates that 144 vectors describe a circle, and each successive value will roughly double the number of view vectors used. For a dome, 1 indicates that 1225 are used to describe the dome, 2 indicates that 5040 view vectors describe the some and each successive value will roughly quadruple the number of view vectors used. Setting this to a high value will result in a more accurate analysis but will take longer to run. (Default: 1).

• legend_par

Optional legend parameters from the "LB Legend Parameters" that will be used to customize the display of the results.

Outputs

• report

...

• view_vecs

A list of vectors which are projected from each of the points to evaluate view.

• results

A list of numbers that aligns with the vertices of the mesh. Each number indicates the distance from the _center_pt at which the view is blocked from a particular direction.

• mesh

A colored mesh representing the visible area from the viewpoint past the _context geometry. Colors indicate how open the view is from a given direction.

• legend

A legend that correspond to the colors of the mesh and shows the distance at which vectors are blocked.

-

Calculate parameters for the relationship between human geometry and the sky given the position of a human subject and context geometry surrounding this position.

The outputs of this component can be plugged into either the "LB Outdoor Solar MRT" or the "LB Indoor Solar MRT" in order to account for context shading around a human subject in these MRT calculations.

Inputs

• north

A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East. This can also be Vector for the direction to North. (Default: 0)

• location [Required]

A ladybug Location that has been output from the "LB Import EPW" component, the "LB Import Location" component, or the "LB Construct Location" component. This will be used to compute hourly sun positions for the fract_body_exp.

• position [Required]

A point for the position of the human subject in the Rhino scene. This is used to understand where a person is in relationship to the _context. The point input here should be at the feet of the human a series of points will be generated above. This can also be a list of points, which will result in several outputs.

• context [Required]

Rhino Breps and/or Rhino Meshes representing context geometry that can block the human subject's direct sun and view to the sky.

• pt_count

A positive integer for the number of points used to represent the human subject geometry. Points are evenly distributed over the height and are used to compute fracitonal values for the fract_body_exp in the case that only some of the points can see the sun. When context shade around the subject is large or coarse, using a single point is likely to return similar results as using several points. However, this number should be increased when context is detailed and has the potential to shade only part of the human subject at a given time. (Default: 1).

• height

A number for the the height of the human subject in the current Rhino Model units. (Default: 1.8 m in the equivalent Rhino Model units; roughly the average height of a standing adult).

• cpu_count

An integer to set the number of CPUs used in the execution of the intersection calculation. If unspecified, it will automatically default to one less than the number of CPUs currently available on the machine or 1 if only one processor is available.

• run [Required]

Set to "True" to run the component and compute the human/sky relationship. If set to "False" but all other required inputs are specified, this component will output points showing the human subject.

Outputs

• report

...

• human_points

The points used to represent the human subject in the calculation of the fraction of the body exposed to sun. Note that these are generated even when _run is set to "False".

• human_line

Line representing the height of the human subject. Note that this is generated even when _run is set to "False".

• fract_body_exp

A data collection for the fraction of the body exposed to direct sunlight at each hour of the year. This can be plugged into the "Solar MRT" components in order to account for context shading in the computation of MRT.

• sky_exposure

A single number between 0 and 1 for the fraction of the sky vault in human subject’s view. This can be plugged into the "Solar MRT" components in order to account for context shading in the computation of MRT.

-

Calculate the incident radiation on geometry using a sky matrix from the "Cumulative Sky Matrix" component.

Such studies of incident radiation can be used to apprxomiate the energy that can be collected from photovoltaic or solar thermal systems. They are also useful for evaluating the impact of a building's orientation on both energy use and the size/cost of cooling systems. For studies of photovoltaic potential or building energy use impact, a sky matrix from EPW radiation should be used. For studies of cooling system size/cost, a sky matrix derived from the STAT file's clear sky radiation should be used.

NOTE THAT NO REFLECTIONS OF SOLAR ENERGY ARE INCLUDED IN THE ANALYSIS PERFORMED BY THIS COMPONENT.

Ground reflected irradiance is crudely acounted for by means of an emissive "ground hemisphere," which is like the sky dome hemisphere and is derived from the ground reflectance that is associated with the connected _sky_mtx. This means that including geometry that represents the ground surface will effectively block such crude ground reflection.

Also note that this component uses the CAD environment's ray intersection methods, which can be fast for geometries with low complexity but does not scale well for complex geometries or many test points. For such complex cases and situations where relfection of solar energy are important, honeybee-radiance should be used.

Inputs

• sky_mtx [Required]