Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Construct a Ladybug Header to be used to create a ladybug DataCollection.
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
header
A Ladybug Header object.
Deconstruct a Ladybug DataCollection into a header and values.
data [Required]
A Ladybug DataCollection object.
header
The header of the DataCollection (containing metadata).
values
The numerical values of the DataCollection.
Calculate hour of the year from month, day, hour, minute.
month
Integer for month (1-12).
day
Integer for day (1-31).
hour
Integer for hour (0-23).
minute
Integer for minute (0-59).
hoy
Hour of the year.
doy
Day of the year.
date
Human readable date time.
Construct a Ladybug DataType to be used in the header of a ladybug DataCollection.
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
type
A Ladybug DataType object that can be assigned to the header of a Ladybug DataCollection.
-
Create an Analysis Period to describe a slice of time during the year.
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
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.
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.
data
A list of Data Collections that have been filtered by the statement_.
-
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.
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.
data
A Ladybug data collection object derived from the operation between the two data inputs.
-
Calculate heating and cooling degree-days from outdoor dry bulb temperature.
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.
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.
-
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
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:
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.
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.
-
Construct a Ladybug data collection from header and values.
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).
data
A Ladybug data collection object.
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.
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.
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.
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.
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:
condition
Integers noting the thermal status of a subject. Values are one of the following:
category
Integers noting the thermal status on a nine-point scale. Values are one of the following:
core_cond
Integers noting the classification of core body temperature. 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.
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.
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.
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.
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.
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:
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:
condition
Integers noting the thermal status of a subject according to the assigned comfort_parameter. Values are one of the following:
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:
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.
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:
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.
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.
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.
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.
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.
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.
-
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.
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).
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.
-
Get statitics of thermal comfort from a Ladybug Comfort Object.
comf_obj [Required]
A Ladybug ComfortCollection object from any of the comfort model components.
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.
-
Get the hours, days, or months of the year associated with the values of a data collection.
data [Required]
An hourly, daily, or monthly collection from which hours, days, or months of the year will be retrieved.
hoys
Numbers for the, hours, days or months of the year in the data collection.
-
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.
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.
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.
-
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.
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)
data
A Continuous DataCollection at the input timestep.
-
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
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).
ppd
The percentage of people dissatisfied (PPD) from cold drafts at ankle level.
-
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.
hoy [Required]
A number between 0 and 8759 for an hour of the year.
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.
-
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.
out_temp [Required]
Outdoor temperatures in one of the following formats:
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.
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:
condition
Integers noting the thermal status of a subject according to the assigned comfort_parameter. 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.
-
Deconstruct a Ladybug Header into its components.
header [Required]
The header of the DataCollection (containing metadata).
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.
-
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.
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).
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 relative humidity from Dry Bulb Temperature and Dew Point Temperature.
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]
rel_humid
A data collection or value indicating the relative humidity [%]
-
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.
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.
ppd
The percentage of people dissatisfied (PPD) for the input radiant asymmetry.
-
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.
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
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.
-
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.
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.
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.
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).
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).
-
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.
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.
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.
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.
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.
data
A Ladybug data collection object derived from the operation between the two data inputs.
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.
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).
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.