Ladybug Primer

Ladybug
Primer
Table of Contents
What is this premier?
Components
0 | Ladybug
1.1
Ladybug
1.1.1
Import_epw
1.1.2
Open_EPW_And_STAT_Weather_Files
1.1.3
Open_EPW_Weather_File
1.1.4
download_EPW_Weather_File
1.1.5
Construct_Location
1.1.6
Decompose_Location
1.1.7
Import_Location
1.1.8
Import_stat
1.1.9
Open_STAT_File
1.1.10
Create_LB_Header
1.1.11
1 | AnalyzeWeatherData
1.2
Analysis_Period
1.2.1
Average_Data
1.2.2
Branch_Data
1.2.3
Separate_data
1.2.4
CDD_HDD
1.2.5
Wind_Speed_Calculator
1.2.6
Adaptive_Comfort_Calculator
1.2.7
Outdoor_Comfort_Calculator
1.2.8
PMV_Comfort_Calculator
1.2.9
Thermal_Comfort_Indices
1.2.10
CDH_HDH
1.2.11
Clothing_Function
1.2.12
Humidity_Ratio_Calculator
1.2.13
2 | VisualizeWeatherData
3D_Chart
1.3
1.3.1
Ladybug Primer
Adaptive_Comfort_Chart
1.3.2
Monthly_Bar_Chart
1.3.3
Psychrometric_Chart
1.3.4
GenCumulativeSkyMtx
1.3.5
selectSkyMtx
1.3.6
Colored_Sky_Visualizer
1.3.7
Outdoor_Solar_Temperature_Adjustor
1.3.8
Radiation_Calla_Lily
1.3.9
Radiation_Rose
1.3.10
Sky_Dome
1.3.11
SunPath
1.3.12
Wind_Boundary_Profile
1.3.13
Wind_Rose
1.3.14
Import_Ground_Temp
1.3.15
3 | EnvironmentalAnalysis
1.4
Radiation_Analysis
1.4.1
Sunlight_Hours_Analysis
1.4.2
Bounce_from_Surface
1.4.3
View_Analysis
1.4.4
View_From_Sun
1.4.5
view_Rose
1.4.6
Comfort_Shade_Benefit_Evaluator
1.4.7
ShadingDesigner
1.4.8
SolarEnvelope
1.4.9
SolarFan
1.4.10
DC_to_AC_derate_factor
1.4.11
Photovoltaics_Performance_Metrics
1.4.12
Photovoltaics_Surface
1.4.13
Sunpath_Shading
1.4.14
Tilt_And_Orientation_Factor
1.4.15
Forward_Raytracing
1.4.16
SolarEnvelopeBasic
1.4.17
SolarFanBasic
1.4.18
4 | Extra
1.5
3
Ladybug Primer
Mesh-To-Hatch
1.5.1
North
1.5.2
Recolor_Mesh
1.5.3
True_North
1.5.4
Adaptive_Comfort_Parameters
1.5.5
Body_Characteristics
1.5.6
Gradient_Library
1.5.7
Legend_Parameters
1.5.8
PMV_Comfort_Parameters
1.5.9
Passive_Strategy_List
1.5.10
Real_Time_Radiation_Analysis
1.5.11
Capture_View
1.5.12
Orient_to_Camera
1.5.13
Set_the_View
1.5.14
fly
1.5.15
C2F
1.5.16
DOY_HOY
1.5.17
Day_Month_Hour
1.5.18
F2C
1.5.19
Activities_Met_List
1.5.20
BTU2Wh
1.5.21
CombineSolarEnvelopes
1.5.22
Comfort_Mannequin
1.5.23
Construct_Time
1.5.24
Create_Legend
1.5.25
L2G
1.5.26
Orientation_Study_Parameters
1.5.27
Passive_Strategy_Parameters
1.5.28
Shading_Parameters_List
1.5.29
Wh2BTU
1.5.30
Wh2kWh
1.5.31
kWh2Wh
1.5.32
ms2mph
1.5.33
Ladybug Primer
rIP2rSI
1.5.34
uIP2uSI
1.5.35
5 | Developers
1.6
Export_Ladybug
1.6.1
Update_Ladybug
1.6.2
6 | WIP
1.7
Bioclimatic_Chart
1.7.1
Shadow_Study
1.7.2
PV_SWH_System_Size
1.7.3
Photovoltaics_Module
1.7.4
Cold_Water_Temperature
1.7.5
Commercial_Public_Apartment_Hot_Water
1.7.6
Residential_Hot_Water
1.7.7
Solar_Water_Heating_Performance_Metrics
1.7.8
Solar_Water_Heating_Surface
1.7.9
Solar_Water_Heating_System
1.7.10
Solar_Water_Heating_System_Detailed
1.7.11
Shading_Mask
1.7.12
Shading_Mask_II
1.7.13
Ladybug Primer
ladybug-primer
This primer is generated by script. Feel free to edit the pages and send pull requests. Here
is the source of this premier.
Ladybug for Grasshopper

Ladybug is a free and open source environmental plugin for Grasshopper to help designers
create an environmentally-conscious architectural design. The initial step in the design
process should be the weather data analysis; a thorough understanding of the weather data
will, more likely, lead designers to high-performance design decisions.
Ladybug imports standard EnergyPlus Weather files (.EPW) in Grasshopper and provides a
variety of 2D and 3D designer-friendly interactive graphics to support the decision-making
process during the initial stages of design. The tool also provides further support for
designers to test their initial design options for implications from radiation and sunlight-hours
analyses results. Integration with Grasshopper allows for an almost instantaneous feedback
on design modifications, and as it runs within the design environment, the information and
analysis is interactive.
Ladybug Primer
Useful links
Ladybug on Github
Ladybug group page on Grasshopper
Facebook page
Ladybug on Twitter
Ladybug Primer
Component list:
Ladybug
Import_epw
Construct_Location
Decompose_Location
Import_Location
Import_stat
Open_STAT_File
Create_LB_Header
0 | Ladybug
Ladybug Primer
Ladybug
This component carries all of Ladybug's main classes. Other components refer to these
classes to run the studies. Therefore, you need to let her fly before running the studies so
the classes will be copied to Rhinos shared space. So let her fly! - Ladybug: A Plugin for
Environmental Analysis (GPL) started by Mostapha Sadeghipour Roudsari You should have
received a copy of the GNU General Public License along with Ladybug; If not, see
http://www.gnu.org/licenses/. @license GPL-3.0+ http://spdx.org/licenses/GPL-3.0+ Source
code is available at: https://github.com/mostaphaRoudsari/ladybug -
Inputs
Ladybug
Ladybug Primer
defaultFolder [Optional]
Optional input for Ladybug default folder. If empty default folder will be set to C:\ladybug
or C:\Users\%USERNAME%\AppData\Roaming\Ladybug\
Outputs
Vviiiiiiiiiizzz!
Current Ladybug mood!!!
Check Hydra Example Files for Ladybug
Ladybug
10
Ladybug Primer
Import epw
Use this component to import lists of weather data into Grasshopper from a standard .epw
file. For detailed information about the structure of an epw file, you may want to read the
"Weather Converter Program" section in "Auxiliary EnergyPlus Programs" document. All
descriptions of importaed data are borrowed from this document. The document is available
online at this address:
"http://apps1.eere.energy.gov/buildings/energyplus/pdfs/auxiliaryprograms.pdf" -
Inputs
epwFile [Required]
Import_epw
11
Ladybug Primer
An .epw file path on your system as a string.
Outputs
readMe!
...
latitude
The latitude of the weather file location.
location
A list of text summarizing the location data in the weather file (use this to construct the
sun path).
dryBulbTemperature
"This is 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."
dewPointTemperature
"This is 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."
relativeHumidity
"This is the hourly Relative Humidity in percent. Valid values range from 0% to 110%.
Missing value for this field is 999."
windSpeed
"This is the hourly wind speed in m/sec. Values can range from 0 to 40. Missing value is
999."
windDirection
"This is the hourly Wind Direction in degrees where the convention is that 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."
directNormalRadiation
Import_epw
12
Ladybug Primer
"This is the hourly Direct Normal Radiation in Wh/m2. (Amount of solar radiation in
Wh/m2 received directly from the solar disk on a surface perpendicular to the sun's
rays, during the number of minutes preceding the time indicated.) If the field is missing (
9999) or invalid (<0), it is set to 0. Counts of such missing values are totaled and
presented at the end of the runperiod."
diffuseHorizontalRadiation
"This is the hourly Diffuse Horizontal Radiation in Wh/m2. (Amount of solar radiation in
Wh/m2 received from the sky (excluding the solar disk) on a horizontal surface during
the number of minutes preceding the time indicated.) If the field is missing ( 9999) or
invalid (<0), it is set to 0. Counts of such missing values are totaled and presented at
the end of the runperiod."
globalHorizontalRadiation
"This is the hourly Global Horizontal Radiation in Wh/m2. (Total amount of direct and
diffuse solar radiation in Wh/m2 received on a horizontal surface during the number of
minutes preceding the time indicated.) It is not currently used in EnergyPlus
calculations. It should have a minimum value of 0; missing value for this field is 9999."
directNormalIlluminance
"This is the hourly Direct Normal Illuminance in lux. (Average amount of illuminance in
hundreds of lux received directly from the solar disk on a surface perpendicular to the
sun's rays, during the number of minutes preceding the time indicated.) It is not
currently used in EnergyPlus calculations. It should have a minimum value of 0; missing
value for this field is 999999 and will be considered missing of >= 999900."
diffuseHorizontalIlluminance
"This is the hourly Diffuse Horizontal Illuminance in lux. (Average amount of illuminance
in hundreds of lux received from the sky (excluding the solar disk) on a horizontal
surface during the number of minutes preceding the time indicated.) It is not currently
used in EnergyPlus calculations. It should have a minimum value of 0; missing value for
this field is 999999 and will be considered missing of >= 999900."
globalHorizontalIlluminance
"This is the hourly Global Horizontal Illuminance in lux. (Average total amount of direct
and diffuse illuminance in hundreds of lux received on a horizontal surface during the
number of minutes preceding the time indicated.) It is not currently used in EnergyPlus
calculations. It should have a minimum value of 0; missing value for this field is 999999
and will be considered missing of >= 999900."
Import_epw
13
Ladybug Primer
totalSkyCover
"This is the fraction for total sky cover (tenths of coverage). (i.e. 1 is 1/10 covered. 10 is
total coverage). (Amount of sky dome in tenths covered by clouds or obscuring
phenomena at the hour indicated at the time indicated.) Minimum value is 0; maximum
value is 10; missing value is 99."
liquidPrecipitationDepth
"The amount of liquid precipitation(mm) observed at the indicated hour for the period
indicated in the liquid precipitation quantity field. If this value is not missing, then it is
used and overrides the precipitation flag as rainfall. Conversely, if the precipitation flag
shows rain and this field is missing or zero, it is set to 1.5 (mm)."
barometricPressure
"This is the hourly weather station pressure in Pa. Valid values range from 31,000 to
120,000... Missing value for this field is 999999."
modelYear
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.
Check Hydra Example Files for Import epw
Import_epw
14
Ladybug Primer
Open EPW And STAT Weather Files
Use this component to automatically download a .zip file from the Department of Energy's
(DOE) database, unzip the file, and open both the .epw and .stat weather files into
Grasshopper. The component requires the URL of the zipped file for the specific climate that
you want to import from the DOE's website. To open the DOE's website, use the
Ladybug_download EPW Weather File component. Note that you can copy the zip file URL
to your clipboard by right-clicking on the "ZIP" link for the climate that you want on the DOE's
website and choosing "Copy Link Address." -
Inputs
15
Ladybug Primer
weatherFileURL [Required]
A text string representing the .zip file URL from the Department of Energy's (DOE's)
website. To open the DOE's website, use the Ladybug_download EPW Weather File
component. Note that you can copy the zip file URL to your clipboard by right-clicking
on the "ZIP" link for the climate that you want on the DOE's website and choosing "Copy
Link Address."
workingDir [Optional]
An optional text string representing a file path to a working directory on your computer
where you would like to download and unzip the file. If nothing is set, the weather files
will be downloaded to C:/ladybug/ and placed in a folder with the name of the weather
file location.
Outputs
epwFile
The file path of the downloaded epw file.
statFile
The file path of the downloaded stat file.
Check Hydra Example Files for Open EPW And STAT Weather Files
16
Ladybug Primer
Open EPW Weather File
Use this component to open an .epw weather file from a location on your computer. -
Inputs
open [Required]
Set Boolean to True to browse for a weather file on your system.
Outputs
17
Ladybug Primer
epwFile
The file path of the selected epw file.
Check Hydra Example Files for Open EPW Weather File
18
Ladybug Primer
download EPW Weather File
Use this component to open the epwmap page in your default web browser and download
an .epw weather file. -
Inputs
download [Required]
Set Boolean to True to open the epw map page
Outputs
19
Ladybug Primer
readMe!
Will read 'Happy downloading...' in the case of successfully opening your browser
Check Hydra Example Files for download EPW Weather File
20
Ladybug Primer
Construct Location
Use this component if you do not have an .epw weather file but have a latitude or other
information on the site. The location output of this component can be used to make a sun
plot in the absence of an .epw weather file. -
Inputs
locationName [Required]
A name for the location you are constructing. (ie. Steventon Island, Antarctica)
Construct_Location
21
Ladybug Primer
latitude [Required]
The latitude of the location you are constructing. Values must be between -90 and 90.
Default is set to the equator.
longitude [Default]
An optional numerical value representing the longitude of the location you are
constructing. This can improve the accuracy of the resulting sun plot.
timeZone [Default]
An optional integer representing the time zone of the location you are constructing. This
can improve the accuracy of the resulting sun plot. The time zone should follow the epw
convention and should be between -12 and +12, where 0 is at Greenwich, UK, positive
values are to the East of Greenwich and negative values are to the West.
elevation [Default]
An optional numerical value representing the elevation of the location you are
constructing.
Outputs
location
sun path).
Check Hydra Example Files for Construct Location
Construct_Location
22
Ladybug Primer
Decompose Location
Use this component to separate and exctract the information in the 'location' output of the
importEPW or constructLocation component. -
Inputs
location [Required]
The output from the importEPW or constructLocation component. This is essentially a
list of text summarizing a location on the earth.
Decompose_Location
23
Ladybug Primer
Outputs
locationName
Name of the location.
latitude
Latitude of the location.
longitude
Longitude of the location.
timeZone
Time zone of the location.
elevation
Elevation of the location.
Check Hydra Example Files for Decompose Location
Decompose_Location
24
Ladybug Primer
Import Location
Use this component to import location data from a standard .epw file. You can use the output
to draw a sunpath. -
Inputs
epwFile [Required]
An .epw file path on your system as a string.
Outputs
Import_Location
25
Ladybug Primer
location
sun path).
Check Hydra Example Files for Import Location
Import_Location
26
Ladybug Primer
Import stat
Use this component to import climate data found in the .stat file that downloads with the
.epw file (in the same .zip folder). Sepcifcally, this allows you to import the ASHRAE and
Koppen climate zones as well as design temperatures representing the temperature
extremes of the climate that should be used to design and size heating and cooling systems.
Lastly, this component brings in the typical and extreme weeks of the year as ladybug
analysis periods that can be plugged into the other ladybug components. -
Inputs
statFile [Required]
Import_stat
27
Ladybug Primer
A .stat file path on your system from the Open STAT file component (or typed out as a
string).
Outputs
readMe!
...
ashraeClimateZone
The estimated ASHRAE climate zone of the STAT file. ASHRAE climate zones are
frequently used to make suggestions for heating and cooling systems and correspond to
recommendations for insulation levels of a building. For more information, see this pdf:
https://www.ashrae.org/File%20Library/docLib/Public/20081111_CZTables.pdf
koppenClimateZone
The estimated Koppen climate zone of the STAT file. The Koppen climate classification
is the most widely used climate classification system and is based on the concept that
native vegetation is the best expression of climate. Thus, Koppen climate zones
combine average annual and monthly temperatures, precipitation, and the seasonality
of precipitation. For more information, see the wikipendia page on Koppen climate:
http://en.wikipedia.org/wiki/K%C3%B6ppen_climate_classification.
heatingDesignTemp
The temperature in Celcius that ASHRAE recommends using to design a heating
system for a building. It rempresents the one of the coldest temperatures of the year for
which only 0.4% of the hours are below.
coolingDesignTemp
The temperature in Celcius that ASHRAE recommends using to design a cooling
system for a building. It rempresents the one of the hottest temperatures of the year for
which only 0.4% of the hours are above.
extremeHotWeek
An analysis period representing the hottest week of the typical mean year. If the stat file
does not specify an extreme hot week, it is the most extreme week of the hottest
season.
typicalHotWeek
Import_stat
28
Ladybug Primer
An analysis period representing a typical week of the hottest season in the typical mean
year. Not all stat files specify such a week and, in this case, the output here will be
"Null."
typicalWeek
An analysis period representing a typical week of the typical mean year. If the stat file
does not specify a typical week, it is the typical week of Autumn.
typicalColdWeek
An analysis period representing a typical week of the coldest season in the typical mean
year. Not all stat files specify such a week and, in this case, the output here will be
"Null."
extremeColdWeek
An analysis period representing the coldest week of the typical mean year. If the stat file
does not specify an extreme cold week, it is the most extreme week of the coldest
season.
Check Hydra Example Files for Import stat
Import_stat
29
Ladybug Primer
Open STAT File
Use this component to open a .stat file, which downloads with the .epw weather file and
contains information such as the climate zone and maximum temperatures for designing
heating/cooling systems. This component opens the file from a location on your computer. -
Inputs
open [Required]
Set Boolean to True to browse for a .stat file on your system.
Open_STAT_File
30
Ladybug Primer
Outputs
statFile
The file path of the selected .stat file.
Check Hydra Example Files for Open STAT File
Open_STAT_File
31
Ladybug Primer
Create LB Header
Use this component to generates a Ladybug Header that can be combined with any raw
data in order to format it for use with the Ladybug/Honeybee components. _ This component
is particularly useful if you are bringing in data from other plugins or from instrumental
measurements and you want to visualize it or analyze it with the Ladybug and Honeybee
components. It is also useful if you want to replace the header on Ladybug data. -
Inputs
location [Optional]
Create_LB_Header
32
Ladybug Primer
A text string that represents the name of the location where the data was collected. If no
value is connected here, the default will be "Somewhere."
dataType [Optional]
A text string that represents the type of data that the header corresponds to. This can be
"Temperature", "Wind", etc. If no value is connected here, the default will be "Some
Data."
units [Optional]
A text string that represents the units of the data. This can be "C", "m/s", etc. If no value
is connected here, the default will be "Some Units."
timeStep [Optional]
A text string that represents the time step of the data. Acceptable values include
"Hourly", "Daily", "Monthly", or "Annually." If no value is connected here, the default will
be "Hourly."
analysisPeriod [Optional]
An optional analysis period from the Analysis Period component. If no analysis period is
given, the default will be for the enitre year: (1,1,1)(12,31,24).
Outputs
LBHeader
Script variable Python
Check Hydra Example Files for Create LB Header
Create_LB_Header
33
Ladybug Primer
Component list:
Analysis_Period
Average_Data
Branch_Data
Separate_data
CDD_HDD
CDH_HDH
Clothing_Function
1 | AnalyzeWeatherData
34
Ladybug Primer
Analysis Period
Use this component to set an analysis period, which can be used as input for a variety of
other Ladybug and Honeybee components. Default analysis period without any inputs is set
to the entire year. -
Inputs
fromMonth [Default]
A number between 1 and 12 that represents the month of the year for the start of the
analysis. Default starting month is set to 1 (January).
Analysis_Period
35
Ladybug Primer
fromDay [Default]
A number between 1 and 31 that represents the day of the month for the start of the
analysis. Default starting day is set to 1 (the first of the month).
fromHour [Default]
A number between 1 and 24 that represents the hour of the day for the start of the
analysis. Default starting hour is set to 1 (the first hour of the day after midnight).
toMonth [Default]
A number between 1 and 12 that represents the month of the year for the end of the
analysis. Default end month is set to 12 (December).
toDay [Default]
A number between 1 and 31 that represents the day of the month for the end of the
analysis. Default end day is set to 31 (the 31st of the month).
toHour [Default]
A number between 1 and 24 that represents the hour of the day for the end of the
analysis. Default end hour is set to 24 (the last hour of the day before midnight)
Outputs
readMe!
A text confirmation of the analysis period.
analysisPeriod
Two tuples that represent the running period (fromMonth, fromDay, fromHour) to
(toMonth, toDay, toHour)
Check Hydra Example Files for Analysis Period
Analysis_Period
36
Ladybug Primer
Average Data
Use this component to select the data out of an annual hourly data stream (from the
importEPW component) using the "Analysis Period" component. This componenent also
averages or totals the connected hourly data for each day, month, and average hour of each
month in the analysis period. -
Inputs
annualHourlyData [Required]
An hourly data stream from the "Import epw" component.
Average_Data
37
Ladybug Primer
analysisPeriod [Default]
The "analysisPeriod" Output from "Analysis Period" component. If no input is provided,
the default analysis period is set to the whole year.
totalOrAverage [Optional]
Set to 'True' to have the component total the values for the given periods and set to
'False' to have the component average them. The default is set to 'False' to average
data.
Outputs
readMe!
A text confirmation of the analysis period.
selHourlyData
The hourly data stream for the analysis period.
averagedDaily
The averaged data for each day during the analysis period.
averagedMonthly
The averaged data for each month during the analysis period.
avrMonthlyPerHour
The data for the average hour of each month during the analysis period.
avrAnalysisPeriod
The averaged data for the analysis period.
Check Hydra Example Files for Average Data
Average_Data
38
Ladybug Primer
Branch Data
Use this component to convert any list of annual data into a data tree branched by day of the
year, month of the year, or hour of the day. If the data is not 8760 value sof each hour, the
number of data items should match number of items in HOY. -
Inputs
data [Required]
A list of data to be branched for each month, day and hour. Note that this can be either
a list of 8760 values for each hour of the year, the output of the "Import EPW"
Branch_Data
39
Ladybug Primer
component, or a custom list of data that is matched by the data in the HOY_ input.
HOY [Optional]
A list of numbers between 1 and 8760 that represents an hour of the year.
Outputs
dataEachDayOfYear
The input data that has been branched data for each day of the year. The paths of the
branches are in the following format {month ; dayOfMonth}.
dataEachMonth
The input data that has been branched for each month of the year. Branch paths are
from 0 to 11.
dataEachHourOfDay
The input data that has been branched for each hour of the day. Branches are from 0 to
23.
Check Hydra Example Files for Branch Data
Branch_Data
40
Ladybug Primer
Separate data
Use this component to separate the text strings from the numbers in the climate data
streams output from the Import EPW component. You can then perform mathamatical
functions on the numerical climate data using the Grasshopper math components or quickly
preview the numerical data stream using the Grasshopper "Quick Graph" component. This
component can also be used generally to separate any data stream that contains both
numbers and text strings. -
Inputs
inputList [Required]
Separate_data
41
Ladybug Primer
A list of data that contains both text srtings and numbers. For example, a data stream
output from the Import EPW component.
Outputs
numbers
The numbers from in the _inputList data. Note that the order of numbers in this list is the
same as the _inputList.
strings
The text strings from in the _inputList data. Note that the order of text strings in this list
is the same as the _inputList.
Check Hydra Example Files for Separate data
Separate_data
42
Ladybug Primer
CDD_HDD
Calculates heating and cooling degree-days. Traditionally, degree-days are defined as the
difference between a base temperature and the average ambient air temperature multiplied
by the number of days that this difference exists. By default, this component uses a more
accurate calculation than the traditional method based on the minimum and maximum
temperature of each day. You may check the formulas in this page:
"http://www.vesma.com/ddd/ddcalcs.htm" If you rather to use the traditional method, set
useDailyAvrMethod to True. -
Inputs
CDD_HDD
43
Ladybug Primer
hourlyDryBulbTemperature [Required]
Annual dry bulb temperature from the Import epw component (in degrees Celsius).
coolingBaseTemperature [Default]
Base temperature for cooling (in degrees Celsius). Default is set to 23.3C but this can
be much lower if the analysis is for a building with high heat gain or insulation.
heatingBaseTemperature [Default]
Base temperature for heating (in degrees Celsius). Default is set to 18.3C but this can
useDailyAvrMethod [Optional]
set to "True" to use the traditional method of degree days calculation, which will
calculate the average temperature of each day and sum up all of these temperatures
over the year. This is opoosed to this component's default analysis, which will will
examine each hour of the year and then convert results to degree-days.
Outputs
readMe!
A summary of the input.
daily_coolingDegDays
Cooling degree-days summed for each day of the year. For visualizations of over the
whole year, connect this to the grasshopper chart/graph component.
daily_heatingDegDays
Heating degree-days summed for each day of the year. For visualizations of over the
monthly_coolingDegDays
Cooling degree-days summed for each month of the year.
monthly_heatingDegDays
Heating degree-days summed for each month of the year.
annual_coolingDegDays
CDD_HDD
44
Ladybug Primer
The total cooling degree-days for the entire year.

annual_heatingDegDays
The total heating degree-days for the entire year.
Check Hydra Example Files for CDD_HDD
CDD_HDD
45
Ladybug Primer
Wind Speed Calculator
Use this component to calculate wind speed at a specific height for a given terrain type. By
default, the component will calculate ground wind speed, which is useful for comfrt
calculations. Also, by hooking up wind data from an epw file, you can use the resulting data
to create a wind rose at any height. -
Inputs
north [Optional]
Input a vector to be used as a true North direction for the sun path or a number between
46
Ladybug Primer
0 and 360 that represents the degrees off from the y-axis to make North. The default
North direction is set to the Y-axis (0 degrees).
windSpeed_tenMeters [Required]
The wind speed from the import EPW component or a number representing the wind
speed at 10 meters off the ground in agricultural or airport terrian. This input also
accepts lists of numbers representing different speeds at 10 meters.
windDirection [Optional]
The wind direction from the import EPW component or a number in degrees represeting
the wind direction from north, This input also accepts lists of numbers representing
different directions.
terrainType [Optional]
An interger from 0 to 3 that sets the terrain class associated with the output
windSpeedAtHeight. Interger values represent the following terrain classes: 0 = Urban:
large city centres, 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, unobstructed areas exposed to
wind flowing over a large water body (no more than 500m inland).
epwTerrain [Optional]
An optional interger from 0 to 3 that sets the terrain class associated with the output
windSpeedAtHeight. The default is set to 2 for flat clear land, which is typical for most
EPW files that are recorded at airports. Interger values represent the following terrain
classes: 0 = Urban: large city centres, 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, unobstructed areas
exposed to wind flowing over a large water body (no more than 500m inland).
heightAboveGround [Optional]
Optional. This is the height above ground for which you would like to measure wind
speed. Providing more than one value will generate a list of speeds at each given
height. Default height is 1 m above ground, which is what a person standing on the
ground would feel.
If you have connected data from an EPW component, plug in an analysis period from
47
Ladybug Primer
the Ladybug_Analysis Period component to calculate data for just a portion of the year.
The default is Jan 1st 00:00 - Dec 31st 24:00, the entire year.
averageData [Optional]
Set to "True" to average all of the wind data that you have connected into a single
speed and wind vector. The default is False, which means the component will return a
list of all hours within the analysis period. If se tot Ture, the wind data will be averaged
for the entire analysis period into a single value.
Outputs
readMe!
...
windSpeedAtHeight
The wind speed at the connected height above the ground. If averageData = True, this
will be a single value representing the average speed for all connected values or values
within the analysis period at each height. If averageData = False, this returns a list of
wind speeds for every hour within the analysis period at each height. Note than when
averageData_ = False, the list will include a header specific to each list. This header
can be removed by using the "Ladybug_Separate Data" component.
windVectorAtHeight
Returns a list of vectors representing wind speed and direction at every hour within the
analysis period, at each height provided.
Check Hydra Example Files for Wind Speed Calculator
48
Ladybug Primer
Adaptive Comfort Calculator
Use this component to calculate the adaptive comfort for a given set of input conditions. This
component will output a stream of 0's and 1's indicating whether certain conditions are
comfortable given the prevailing mean monthly temperature that ocuppants tend to adapt
themselves to. This component will also output a series of interger numbers that indicate the
following: -1 = The average monthly temperature is too extreme for the adaptive model. 0 =
The input conditions are too cold for occupants. 1 = The input conditions are comfortable for
occupants. 2 = The input conditions are too hot for occupants. Lastly, this component
outputs the percent of time comfortable, hot, cold and monthly extreme as well as a lit of
numbers indicating the upper temperature of comfort and lower temperature of comfort. The
adaptive comfort model was created in response to the shortcomings of the PMV model that
49
Ladybug Primer
became apparent when it was applied to buildings without air conditioning. Namely, the PMV
model was over-estimating the discomfort of occupants in warm conditions of nautrally
ventilated buildings. Accordingly, the adaptive comfort model was built on the work of
hundreds of field studies in which people in naturally ventilated buildings were asked asked
about how comfortable they were. Results showed that users tended to adapt themselves to
the monthly mean temperature and would be comfortable in buildings so long as the building
temperature remained around a value close to that monthly mean. This situation held true so
long as the monthly mean temperature remained above 10 C and below 33.5 C. The comfort
models that make this component possible were translated to python from a series of
validated javascript comfort models coded at the Berkely Center for the Built Environment
(CBE). The Adaptive model used by both the CBE Tool and this component was originally
published in ASHARAE 55. Special thanks goes to the authors of the online CBE Thermal
Comfort Tool who first coded the javascript: Hoyt Tyler, Schiavon Stefano, Piccioli Alberto,
Moon Dustin, and Steinfeld Kyle. http://cbe.berkeley.edu/comforttool/ -
Inputs
dryBulbTemperature [Required]
A number representing the dry bulb temperature of the air in degrees Celcius. This input
can also accept a list of temperatures representing conditions at different times or the
direct output of dryBulbTemperature from the Import EPW component.
meanRadiantTemperature [Optional]
A number representing the mean radiant temperature of the surrounding surfaces in
degrees Celcius. If no value is plugged in here, this component will assume that the
mean radiant temperature is equal to air temperature value above. This input can also
accept a list of temperatures representing conditions at different times or the direct
output of dryBulbTemperature from the Import EPW component.
prevailingOutdoorTemp [Required]
A number representing the average monthly outdoor temperature in degrees Celcius.
This average monthly outdoor temperature is the temperature that occupants in
naturally ventilated buildings tend to adapt themselves to. For this reason, this input can
also accept the direct output of dryBulbTemperature from the Import EPW component if
houlry values for the full year are connected for the other inputs of this component.
windSpeed [Optional]
A number representing the wind speed of the air in meters per second. If no value is
plugged in here, this component will assume a very low wind speed of 0.3 m/s,
50
Ladybug Primer
characteristic of most naturally ventilated buildings. This input can also accept a list of
wind speeds representing conditions at different times or the direct output of windSpeed
from of the Import EPW component.
comfortPar [Optional]
Optional comfort parameters from the "Ladybug_Adaptive Comfort Parameters"
component. Use this to select either the US or European comfort model, set the
threshold of acceptibility for comfort or compute prevailing outdoor temperature by a
monthly average or running mean. These comfortPar can also be used to set a
levelOfConditioning, which makes use of research outside of the official published
standards that surveyed people in air conditioned buildings.
An optional analysis period from the Analysis Period component. If no Analysis period is
given and epw data from the ImportEPW component has been connected, the analysis
will be run for the enitre year.
runIt [Required]
Set to "True" to run the component and calculate the adaptive comfort metrics.
Outputs
readMe!
...
comfortableOrNot
A stream of 0's and 1's (or "False" and "True" values) indicating whether occupants are
comfortable under the input conditions given the fact that these occupants tend to adapt
themselves to the prevailing mean monthly temperature. 0 indicates that a person is not
comfortable while 1 indicates that a person is comfortable.
conditionOfPerson
A stream of interger values from -1 to +1 that correspond to each hour of the input data
and indicate the following: -1 = The input conditions are too cold for occupants. 0 = The
input conditions are comfortable for occupants. +1 = The input conditions are too hot for
occupants.
degreesFromTarget
51
Ladybug Primer
A stream of temperature values in degrees Celcius indicating how far from the target
temperature the conditions of the people are. Positive values indicate conditions hotter
than the target temperature while negative values indicate degrees below the target
temperture.
targetTemperature
A stream of temperature values in degrees Celcius indicating the mean target
temperture or neutral temperature that the most people will find comfortable.
upperTemperatureBound
A stream of temperature values in degrees Celcius indicating the highest possible
temperature in the comfort range for each hour of the input conditions.
lowerTemperatureBound
A stream of temperature values in degrees Celcius indicating the lowest possible
temperature in the comfort range for each hour of the input conditions.
percentOfTimeComfortable
The percent of the input data for which the occupants are comfortable. Comfortable
conditions are when the indoor temperature is within the comfort range determined by
the prevailing outdoor temperature.
percentHotCold
A list of 2 numerical values indicating the following: 0) The percent of the input data for
which the occupants are too hot. 1) The percent of the input data for which the
occupants are too cold.
Check Hydra Example Files for Adaptive Comfort Calculator
52
Ladybug Primer
Outdoor Comfort Calculator
Use this component to calculate the Universal Thermal Climate Index (UTCI) for a set of
input climate conditions. Perhaps the most familiar application of Univeral Thermal Climate
Index (UTCI) is the temperature given by TV weathermen and women when they say that,
"even though the dry bulb temperature outside is a certain value, the temperature actually
"feels like" something higher or lower." UTCI is this temperature of what the weather "feels
like" and it takes into account the radiant temperature (sometimes including solar radiation),
relative humidity, and wind speed. UTCI uses these variables in a human energy balance
model to give a temperature value that is indicative of the heat stress or cold stress felt by a
human body in the outdoors. A UTCI between 9 and 26 degrees Celcius indicates no
thermal stress or comfortable conditions outdoors. A UTCI between 26 and 28 degrees
53
Ladybug Primer
Celcius indicates slight heat stress (comfortable for short periods of time). Between 28 and
32 degrees, UTCI indicates moderate heat stress (hot but not dangerous). Between 32 and
38 degrees, UTCI indicates strong heat stress (dangerous beyond short periods of time).
Above 38, UTCI indicates very strong to extreme heat stress (very dangerous). A UTCI
between 0 and 9 degrees Celcius indicates slight cold stress (comfortable for short periods
of time). Between 0 and -13 degrees, UTCI indicates moderate cold stress (cold but not
dangerous). Between -13 and -27 degrees, UTCI indicates strong cold stress (dangerous
beyond short periods of time). Below -27, UTCI indicates very stong to extreme cold stress
(very dangerous). UTCI is result of the world's leading comfort specailists' attempt to make
an interational standard of outdoor temperature sensation that fills the follwoing
requirements: 1) Thermo-physiological significance in the whole range of heat exchange
conditions of existing thermal environments 2) Valid in all climates, seasons, and scales 3)
Useful for key applications in human biometeorology. _ The code that makes this component
possible is a Python version of the original Fortran code for calculating UTCI. Information on
UTCI and the original Fortran code can be found here: http://www.utci.org/. -
Inputs
windSpeed_tenMeters [Optional]
characteristic of most indoor conditions. This input can also accept a list of wind speeds
representing conditions at different times or the direct output of windSpeed from of the
Import EPW component.
relativeHumidity [Required]
A number between 0 and 100 representing the relative humidity of the air in percentage.
54
Ladybug Primer
This input can also accept a list of relative humidity values representing conditions at
different times or the direct output of relativeHumidity from of the Import EPW
component.
runIt [Required]
Script variable UTCIComfortCalculator
Outputs
readMe!
...
universalThermalClimateIndex
The UTCI of the input conditions in degrees Celcius. Perhaps the most familiar
application of Univeral Thermal Climate Index (UTCI) is the temperature given by TV
weathermen and women when they say that, even though the dry bulb temperature
outside is a certain value, the temperature actually "feels like" something higher or
lower. UTCI is this temperature of what the weather "feels like" and it takes into account
radiant temperature (usually including solar radiation), relative humidity, wind speed and
uses them in a human energy balance model to give a temperature value that is
indicative of the heat stress or cold stress felt by the human body.
comfortableOrNot
A stream of 0's and 1's (or "False" and "True" values) indicating whether a person
outside is comfortable for each hour of the input conditions. 0 indicates that a person is
not comfortable while 1 indicates that a person is comfortable. A person is considered to
be comfortable when he/she experiences no thermal stress (9 < UTCI < 26).
thermalStress
A stream of interger values from -1 to +1 that indicate the following: -1 - Cold Stress cold conditions (UTCI < 9C). 0 - No Thermal Stress - comfortable conditions (9C < UTCI
< 26C). +1 - Heat Stress - hot conditions (UTCI > 26C).
55
Ladybug Primer
conditionOfPerson
A stream of interger values from -3 to +3 that indicate the following: -3 - Strong Cold
Stress - potential public health hazard with higher-than-normal mortality rates (UTCI <
-13C). -2 - Moderate Cold Stress - cold but no public health hazard (-13C < UTCI < 0C).
-1 - Slight Cold Stress - cool but comfortable for short periods of time (0C < UTCI < 9C)
0 - No Thermal Stress - comfortable conditions (9C < UTCI < 26C). +1 - Slight Heat
Stress - warm but comfortable for short periods of time (26C < UTCI < 28C). +2 Moderate Heat Stress - hot but no public health hazard (28C < UTCI < 32C). +3 Strong Heat Stress - potential public health hazard with higher-than-normal mortality
rates (UTCI > 32C).
The percent of the input data for which the UTCI indicates no thermal stress
(comfortable conditions). Comfortable conditions are when the UTCI is between 9 and
26 degrees Celcius.
percentComfForShortPeriod
The percent of the input data for which the UTCI indicates slight heat/cold stress. This
indicates conditions that are comfortable for short periods of time with proper attire. This
includes all conditions when the UTCI is between 0 and 9 degrees Celcius or between
26 and 28 degrees Celcius.
percentHeatStress
The percent of the input data for which the UTCI indicates moderate-to-extreme heat
stress. This indicates conditions that are not comfortable. This includes all conditions
are when the UTCI is above 28 degrees Celcius.
percentColdStress
The percent of the input data for which the UTCI indicates moderate-to-extreme cold
stress. This indicates conditions that are not comfortable. This includes all conditions
are when the UTCI is below 0 degrees Celcius.
Check Hydra Example Files for Outdoor Comfort Calculator
56
Ladybug Primer
PMV Comfort Calculator
Use this component to calculate comfort metrics of Predicted Mean Vote (PMV), the Percent
of People Dissatisfied (PPD), and the Standard Effective Temperature (SET) for a set of
climate conditions and occupant behavior/clothing. This component can also calculate
Outdoor Standard Effective Temperature (OUT-SET) if EPW weather data is connected.
HOWEVER, if you are interested in knowing whether outdoor conditions are actually
comfortable, it is highly recommended that you use the Ladybug UTCI Comfort Calculator.
OUT-SET has been shown to be a poor indicator of outdoor comfort and is better used as a
tool to help understand what clothing and metabolic rate a comfortable person might have in
the outdoors AFTER running a UTCI study. Predicted Mean Vote (PMV) is a seven-point
scale of occupant comfort from cold (-3) to hot (+3) that was used in the comfort surveys of
57
Ladybug Primer
P.O. Fanger, who initially developed the scale and the PMV comfort model off of it. Each
interger value of the PMV scale indicates the following: -3:Cold, -2:Cool, -1:Slightly Cool,
0:Neutral, +1:Slightly Warm, +2:Warm, +3:Hot. The range of comfort is generally accepted
as a PMV between -1 and +1. Exceeding +1 will result in an uncomfortably warm occupant
while dropping below -1 will result in an uncomfortably cool occupant. PMV is a MEAN vote
because is meant to represent the average vote of all people under the input conditions.
This component will output the PMV of the occupant for the input conditions as well as an
estimated Percentage of People Dissatisfied (PPD) under the given conditions. PPD refers
to the perceont of people that would give a PMV greater than/equal to 1 or less than/equal to
-1. Note that, with this model, it is not possible to get a PPD of 0% and most engineers just
aim to have a PPD below 20% when designing a HVAC system. This component will also
output Standard Effective Temperature (SET), which is an ajusted temperature scale meant
to reflect the heat stress or cold felt by the occupant. Specifically, SET is definied as the
equivalent temperature of an imaginary environment at 50% relative humidity, <0.1 m/s air
speed, and mean radiant temperature equal to air temperature, in which the total heat loss
from the skin of an imaginary occupant is the same as that from a person existing under the
input conditions. It is also important to note that the imaginary occupant is modeled with an
activity level of 1.0 met and a clothing level of 0.6 clo. The actual occupant in the real
environment can have different values from these. The original PMV studies by Fanger
involved placing subjects in an air conditioned climate chamber for an hour in which the
subjects had no means to adjust their conditions to make them comfortable. Subjects where
then asked to pick an interger on the PMV scale. Since PMV subjects could not change their
layers of clothing or open windows to make themselves comfortable, the PMV model is most
useful when applied to these conditions of an air conditioned building in which users cannot
open windows, turn on fans or change dress code. For comfort in conditions where people
can adjust these factors, the adaptive comfort calculator or UTCI comfort calculator would be
most useful. _ The comfort models that make this component possible were translated to
python from a series of validated javascript comfort models coded at the Berkely Center for
the Built Environment (CBE). The PMV model used by both the CBE Tool and this
component was originally published in ASHARAE 55. Special thanks goes to the authors of
the online CBE Thermal Comfort Tool who first coded the javascript comfort models: Hoyt
Tyler, Schiavon Stefano, Piccioli Alberto, Moon Dustin, and Steinfeld Kyle.
http://cbe.berkeley.edu/comforttool/ -
Inputs
58
Ladybug Primer
representing conditions at different times or the direct output of windSpeed from of the
Import EPW component.
component.
metabolicRate [Optional]
A number representing the metabolic rate of the human subject in met. This input can
also accept text inputs for different activities. Acceptable text inputs include Sleeping,
Reclining, Sitting, Typing, Standing, Driving, Cooking, House Cleaning, Walking,
Walking 2mph, Walking 3mph, Walking 4mph, Running 9mph, Lifting 10lbs, Lifting
100lbs, Shoveling, Dancing, and Basketball. If no value is input here, the component will
assume a metabolic rate of 1 met, which is the metabolic rate of a seated human being.
This input can also accept lists of metabolic rates.
clothingLevel [Optional]
A number representing the clothing level of the human subject in clo. If no value is input
here, the component will assume a clothing level of 1 clo, which is roughly the insulation
provided by a 3-piece suit. A person dressed in shorts and a T-shirt has a clothing level
of roughly 0.5 clo and a person in a thick winter jacket can have a clothing level as high
as 2 to 4 clo. This input can also accept lists of clothing levels.
Optional comfort parameters from the "Ladybug_PMV Comfort Parameters" component.
59
Ladybug Primer
Use this to adjust maximum and minimum acceptable humidity ratios. These comfortPar
can also change whether comfort is defined by eighty or ninety percent of people
comfortable. By default, comfort is defined as 90% of the occupants comfortable and
there are no limits on humidity when there is no thermal stress.
calcBalanceTemperature [Optional]
Set to "True" to have the component calculate the balance temperature for the input
windSpeed, _relativeHumidity, metabolicRate, and clothingLevel_. The balance
temperature is essentially the temperature for these conditions at which the PMV is
equal to 0 (or the energy flowing into the human body is equal to the energy flowing
out). Note that calculating the balance temperature for a whole year with epw
windspeed can take as long as 10 minutes and so, by default, this option is set to
"False".
runIt [Required]
Set to "True" to run the component and calculate the PMV comfort metrics.
Outputs
readMe!
...
predictedMeanVote
The estimated predicted mean vote (PMV) of test subjects under the input conditions.
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. The range of comfort is
generally accepted as a PMV between -1 and +1. Exceeding +1 will result in an
uncomfortably warm occupant while dropping below -1 will result in an uncomfortably
cool occupant. For detailed information on the PMV scale, see P.O. Fanger's original
paper: Fanger, P Ole (1970). Thermal Comfort: Analysis and applications in
environmental engineering.
percentPeopleDissatisfied
60
Ladybug Primer
The estimated percentage of people dissatisfied (PPD) under the given input conditions.
Specifically, this is defined by the percent of people who would have a PMV less than -1
or greater than +1 under the conditions. Note that, with this model, it is not possible to
get a PPD of 0% and most engineers just aim to have a PPD below 20%.
standardEffectiveTemperature
The standard effective temperature (SET) for the given input conditions in degrees
Celcius. SET is an ajusted temperature scale meant to reflect the heat stress or cold felt
by the occupant. Specifically, SET is definied as the equivalent temperature of an
imaginary environment at 50% relative humidity, <0.1 m/s air speed, and mean radiant
temperature equal to air temperature, in which the total heat loss from the skin of an
imaginary occupant is the same as that from a person existing under the input
conditions. It is also important to note that the imaginary occupant is modeled with an
activity level of 1.0 met and a clothing level of 0.6 clo. The actual occupant in the real
environment can have different values from these.
comfortableOrNot
A stream of 0's and 1's (or 'False' and 'True' values) indicating whether the occupant is
comfortable for each hour of the input conditions. 0 indicates that the occupant is not
comfortable while 1 indicates that the occupant is comfortable.
The percent of input conditions for which the occupant is comfortable. Note that this
output is only menaingful when multiple values are connected for the input conditions.
balanceTemperature
The balance temperature is the temperature for the input windSpeed, _relativeHumidity,
metabolicRate, and clothingLevel_ at which the PMV is equal to 0 (or the energy flowing
into the human body is equal to the energy flowing out). Setting the dry bulb and radiant
temperatures to this value will produce a PMV of 0 and will yield the lowest possible
PPD.
Check Hydra Example Files for PMV Comfort Calculator
61
Ladybug Primer
Thermal Comfort Indices
Use this component to calculate various

thermal comfort indices:
HI (Heat Index)
humidex (humidity index)
DI (Discomfort Index)
WCI (Wind Chill Index)
WCT (Wind Chill Temperature)
62
Ladybug Primer
WBGT (Wet-Bulb Globe Temperature) indoors

WBGT (Wet-Bulb Globe Temperature) outdoors
TE (Effective Temperature)
AT (Apparent Temperature)
TS (Thermal Sensation)
ASV (Actual Sensation Vote)
MRT (Mean Radiant Temperature)
Iclp (Predicted Insulation Index Of Clothing)
HR (Heart Rate)
DhRa (Dehydration Risk)
PET (Physiological Equivalent Temperature)
THI (Temperature Humidity Index)
PHS (Predicted Heat Strain) -
Inputs
comfortIndex [Required]
Choose one of the comfort indices: 0 - HI (Heat Index) 1 - humidex (humidity index) 2 DI (Discomfort Index) 3 - WCI (Wind Chill Index) 4 - WCT (Wind Chill Temperature) 5 WBGT (Wet-Bulb Globe Temperature) indoors 6 - WBGT (Wet-Bulb Globe
Temperature) outdoors 7 - TE (Effective Temperature) 8 - AT (Apparent Temperature) 9
- TS (Thermal Sensation) 10 - ASV (Actual Sensation Vote) 11 - MRT (Mean Radiant
Temperature) 12 - Iclp (Predicted Insulation Index Of Clothing) 13 - HR (Heart Rate) 14
- DhRa (Dehydration Risk) 15 - PET (Physiological Equivalent Temperature) for
temperate climates 16 - PET (Physiological Equivalent Temperature) for tropical and
subtropical humid climates 17 - THI (Temperature Humidity Index) 18 - PHS (Predicted
Heat Strain)
location [Required]
Input data from Ladybug's "Import epw" "location" output, or create your own location
data with Ladybug's "Construct Location" component.
Air temperature. Input a single value or a whole list from "Import epw" component's
"dryBulbTemperature" output. - In Celsius degrees (C).
An average temperature of the surfaces that surround the analysis location. For indoor
conditions or outdoor in-shade, it should be equal to air temperature. So just input the
63
Ladybug Primer
same data you inputted to "_dryBulbTemperature". - If nothing supplied, it will be

calculated for outdoor conditions (both in-shade and out-shade). - In Celsius degrees
(C).
dewPointTemperature [Optional]
Dew point temperature. Input a single value or a whole list from "Import epw"
component's "dewPointTemperature" output. - If not supplied, it will be calculated from
dryBulbTemperature and relativeHumidity data. - In Celsius degrees (C).
relativeHumidity [Optional]
Relative humidity. Input a single value or a whole list from "Import epw" component's
"relativeHumidity" output. - If not supplied 50% will be used as a default (indoor
conditions). - In percent (from 0% to 110%).
Wind speed at 1.1 meters height from analysis surface (height of standing persons
gravity center). It can be a single value or a list of values. Take the "windSpeed" output
from "Import epw" component and plug it to "Wind Speed Calculator" component's
"windSpeed_tenMeters" input. Set the "heightAboveGround" input to "1.1". Then plug in
the data from "Wind Speed Calculator" component's "windSpeedAtHeight" output to this
component's "windSpeed_" input. In this way we converted the 10 meter wind speed
from the .epw file to required 1.1m. - If not supplied, default value of 0.3 m/s is used
(meaning: the analysis is conducted in outdoor no wind conditions, or indoor
conditions). - In meters/second.
globalHorizontalRadiation [Optional]
Total amount of direct and diffuse solar radiation that an analysis person received. Use
the "globalHorizontalRadiation" data from Ladybug's "Import epw" component for
analysis without shading. For analysis with shading included, use the
"shadedSolarRadiationPerHour" output from "Sunpath shading" component instead. - If
not supplied, default value of 0 Wh/m2 will be used (meaning: the analysis is conducted
in outdoor in shade conditions, or indoor conditions). - In Wh/m2.
totalSkyCover [Optional]
Amount of sky dome covered by clouds. Input a single value or a whole list from "Import
epw" component's "totalSkyCover" output. It ranges from from 1 to 10. For example: 1 is
1/10 covered. 10 is total coverage (10/10). - If not supplied 6/10 will be used (cloud
coverage of temperate humid climate). - In tenths of sky cover.
64
Ladybug Primer
bodyCharacteristics [Optional]
A list of body characteristics in the following order: age, sex, height, weight,
bodyPosition, clothingInsulation, acclimated, metabolicRate, activityDuration. Use
Ladybug's "Body Characteristics" component to generate it. -
If not supplied, the following default values

will be used:
30 - age "male" - sex 175 - height in centimeters 75 - weight in kilograms "standing" bodyPosition None (clothingInsulation - "None" means that it will be calculated based on
air temperature) 37 - clothingAlbedo in % (for medium colored clothes) "unacclimated" acclimated 2.32 - metabolicRate in mets (2.32 corresponds to walking 4km/h) 480 activityDuration in minutes
HOY [Optional]
An hour (or hours) of the year for which you would like to calculate thermal indices.
These hours must be a value between 1 and 8760. This input will override the
analysisPeriod_ input below. - If not supplied, this input will be ignored.
An optional analysis period from the "Analysis Period" component. - If not supplied, the
whole year period will be used as an analysis period.
runIt [Required]
...
Outputs
readMe!
...
comfortIndexValue
The value of the chosen comfort.
comfortIndexLevel
The level (category, sensation) of the chosen index.
65
Ladybug Primer
comfortableOrNot
Indication of whether that person is comfortable (1) or not (0) at particular hour.
percentComfortable
Percentage of time, during which chosen index falls into the comfortable category.
percentHotExtreme
Percentage of time, during which chosen index falls into the hot extreme category.
percentColdExtreme
Percentage of time, during which chosen index falls into the cold extreme category.
Check Hydra Example Files for Thermal Comfort Indices
66
Ladybug Primer
CDH_HDH
Calculates heating and cooling degree-hours. Degree-hours are defined as the difference
between the base temperature and the average ambient outside air temperature multiplied
by the number of hours that this difference condition exists. -
Inputs
hourlyDryBulbTemperature [Required]
Annual dry bulb temperature from the Import epw component (in degrees Celsius).
CDH_HDH
67
Ladybug Primer
coolingBaseTemperature [Default]
Base temperature for cooling (in degrees Celsius). Default is set to 23.3C but this can
heatingBaseTemperature [Default]
Base temperature for heating (in degrees Celsius). Default is set to 18.3C but this can
Outputs
readMe!
A ummary of the input.
hourly_coolingDegHours
Cooling degree-hours for each hour of the year. For visualizations over the whole year,
connect this to the grasshopper chart/graph component.
hourly_heatingDegHours
Heating degree-days for each hour of the year. For visualizations over the whole year,
connect this to the grasshopper chart/graph component.
daily_coolingDegHours
Cooling degree-days summed for each day of the year. For visualizations of over the
daily_heatingDegHours
Heating degree-days summed for each day of the year. For visualizations of over the
monthly_coolingDegHours
Cooling degree-days summed for each month of the year.
monthly_heatingDegHours
Heating degree-days summed for each month of the year.
annual_coolingDegHours
The total cooling degree-days for the entire year.
CDH_HDH
68
Ladybug Primer
annual_heatingDegHours
The total heating degree-days for the entire year.
Check Hydra Example Files for CDH_HDH
CDH_HDH
69
Ladybug Primer
Clothing Function
Use this component to generate a list of values representing a clothing schedule based on
outdoor air temperature. This schedule can be plugged into the clothingLevel_ input of the
PMV Comfort Calculator component. By default, this function used to derive clothing levels
based on outside temperature was developed by Schiavon, Stefano and implemented on the
CBE comfort tool (http://smap.cbe.berkeley.edu/comforttool/). This version of the component
allows users to change the maximum and minimum clothing levels, which Schiavon set at 1
and 0.46 respectively, and the temperatures at which these clothing levels occur, which
Schiavon set at 26C and -5 C respectively. Note that Schiavon did not endorse the changing
of these values but they are provided here to allow users an additional level of freedom. -
Clothing_Function
70
Ladybug Primer
Inputs
outdoorAirTemperature [Required]
A number or list of numbers representing the dry bulb temperature of the air in degrees
Celcius. This input can also accept the direct output of dryBulbTemperature from the
Import EPW component and this is recommended for hourly comfort analysis.
If you have hooked up annual temperatures from the importEPW component, use this
input to
maxClo [Optional]
An optional number representing the maximum clo value that someone will wear on the
coldest days of the outdoorAirTemperature input. The default is set to 1 clo, which
corresponds to a 3-piece suit.
maxCloTemp [Optional]
An optional number representing the temperature at which the maxClo value will be
applied. The default is set to -5C, which means that any lower temperature will get the
maxClo value.
minClo [Optional]
An optional number representing the minimum clo value that someone will wear on the
hotest days of the outdoorAirTemperature input. The default is set to 0.46 clo, which
corresponds to shorts and a T-shirt.
minCloTemp [Optional]
An optional number representing the temperature at which the minClo value will be
applied. The default is set to 26C, which means that any higher temperature will get the
minClo value.
Outputs
readMe!
...
cloValues
A list of numbers representing the clothing that would be worn at each hour of the
Clothing_Function
71
Ladybug Primer
_outdoorAirTemperature. Note that, if the component senses that you have hooked up a
stream of hourly data, the clothing levels will alternate on a 12-hour basis.
Check Hydra Example Files for Clothing Function
Clothing_Function
72
Ladybug Primer
Humidity Ratio Calculator
Calculates the humidity ratio from the ladybug weather file import parameters Conversion
formulas are taken from the following publications: Vaisala. (2013) Humidity Conversion
Formulas: Calculation Formulas for Humidity.
www.vaisala.com/Vaisala%20Documents/Application%20notes/Humidity_Conversion_Form
ulas_B210973EN-F.pdf W. Wagner and A. Pru:" The IAPWS Formulation 1995 for the
Thermodynamic Properties of Ordinary Water Substance for General and Scientific Use ",
Journal of Physical and Chemical Reference Data, June 2002 ,Volume 31, Issue 2, pp.
387535 -
Inputs
73
Ladybug Primer
The dry bulb temperature from the Import epw component.
The relative humidity from the Import epw component.
barometricPressure [Required]
The barometric pressure from the Import epw component.
Outputs
readMe!
...
humidityRatio
The hourly humidity ratio (kg water / kg air).
enthalpy
The hourly enthalpy of the air (kJ / kg).
partialPressure
The hourly partial pressure of water vapor in the atmosphere (Pa).
saturationPressure
The saturation pressure of water vapor in the atmosphere (Pa).
Check Hydra Example Files for Humidity Ratio Calculator
74
Ladybug Primer
Component list:
3D_Chart
Monthly_Bar_Chart
Psychrometric_Chart
GenCumulativeSkyMtx
selectSkyMtx
Radiation_Rose
Sky_Dome
SunPath
Wind_Rose
Import_Ground_Temp
2 | VisualizeWeatherData
75
Ladybug Primer
3D Chart
Use this component to make a 3D chart in the Rhino scene of any climate data or hourly
simulation data. -
Inputs
inputData [Required]
A list of input data to plot.
basePoint [Default]
3D_Chart
76
Ladybug Primer
An optional point with which to locate the 3D chart in the Rhino Model. The default is set
to the Rhino origin at (0,0,0).
xScale [Default]
The scale of the X axis of the graph. The default will plot the X axis with a length of
3650 Rhino model units (for 365 days of the year). Connect a list of values for multiple
graphs.
yScale [Default]
The scale of the Y axis of the graph. The default will plot the Y axis with a length of 240
Rhino model units (for 24 hours of the day). Connect a list of values for multiple graphs.
zScale [Default]
The scale of the Z axis of the graph. The default will plot the Z axis with a number of
Rhino model units corresponding to the input data values. Set to 0 to see graphCurves
appear on top of the mesh. Connect a list of values for multiple graphs.
yCount [Default]
The number of segments on your y-axis. The default is set to 24 for 24 hours of the day.
This variable is particularly useful for input data that is not for each hour of the year.
legendPar [Optional]
Optional legend parameters from the Ladybug Legend Parameters component.
condStatement [Optional]
An optional conditional statement, which will remove data from the chart that does not fit
the conditions. The input must be a valid python conditional statement (e.g. a > 25).
bakeIt [Optional]
If set to True, the chart will be Baked into the Rhino scene as a colored mesh. Text will
be baked as Rhino text objects, which facilitates easy export to PDF or vector-editing
programs.
Outputs
readMe!
...
3D_Chart
77
Ladybug Primer
graphMesh
A 3D plot of the input data as a colored mesh. Multiple meshes will be output for several
input data streams or graph scales.
graphCurves
A list of curves and text surfaces representing the time periods corresponding to the
input data. Note that if the time period of the input data is not clear, no curves or labels
will be generated here.
legend
A legend of the chart. Connect this output to a grasshopper "Geo" component in order
to preview the legend in the Rhino scene.g
legendBasePts
The legend base point, which can be used to move the legend in relation to the chart
with the native rasshopper "Move" component.
title
The title text of the chart. Hook this up to a native Grasshopper 'Geo' component to
preview it separately from the other outputs.
titleBasePts
Points for placement of the title and axes labels of the chart, which can be used to move
these text items in relation to the chart with the native Grasshopper "Move" component.
dataPts
Points representing the location of each piece of data on the chart. Use this to label the
points of the chart with text lables using a native grasshopper "Text Tag" component.
conditionalHOY
The input data for the hours of the year that pass the conditional statement.
Check Hydra Example Files for 3D Chart
3D_Chart
78
Ladybug Primer
Adaptive Comfort Chart
Use this component to calculate the adaptive comfort for a given set of input conditions. This
component will output a stream of 0's and 1's indicating whether certain conditions are
comfortable given the prevailing mean monthly temperature that ocuppants tend to adapt
themselves to. This component will also output a series of interger numbers that indicate the
following: -1 = The average monthly temperature is too extreme for the adaptive model. 0 =
The input conditions are too cold for occupants. 1 = The input conditions are comfortable for
occupants. 2 = The input conditions are too hot for occupants. Lastly, this component
outputs the percent of time comfortable, hot, cold and monthly extreme as well as a lit of
numbers indicating the upper temperature of comfort and lower temperature of comfort. The
adaptive comfort model was created in response to the shortcomings of the PMV model that
79
Ladybug Primer
became apparent when it was applied to buildings without air conditioning. Namely, the PMV
model was over-estimating the discomfort of occupants in warm conditions of nautrally
ventilated buildings. Accordingly, the adaptive comfort model was built on the work of
hundreds of field studies in which people in naturally ventilated buildings were asked asked
about how comfortable they were. Results showed that users tended to adapt themselves to
the monthly mean temperature and would be comfortable in buildings so long as the building
temperature remained around a value close to that monthly mean. This situation held true so
long as the monthly mean temperature remained above 10 C and below 33.5 C. The comfort
models that make this component possible were translated to python from a series of
validated javascript comfort models coded at the Berkely Center for the Built Environment
(CBE). The Adaptive model used by both the CBE Tool and this component was originally
published in ASHARAE 55. Special thanks goes to the authors of the online CBE Thermal
Comfort Tool who first coded the javascript: Hoyt Tyler, Schiavon Stefano, Piccioli Alberto,
Moon Dustin, and Steinfeld Kyle. http://cbe.berkeley.edu/comforttool/ -
Inputs
direct output of dryBulbTemperature from the 'Read EP Result' or 'Import EPW'
component.
output from the 'Read EP Result' or 'Import EPW' component.
prevailingOutdoorTemp [Required]
A number representing the prevailing outdoor temperature in degrees Celcius. For the
ASHRAE standard, this is the average monthly outdoor temperature and, for the
European standard, this is a running mean outdoor temperature calculated from the
conditions of the last week. For this reason, this input can also accept the direct output
of dryBulbTemperature from the 'Import EPW' component if houlry values for the full
year are connected for the other inputs of this component. This input from the 'Import
EPW' component is recommended.
80
Ladybug Primer
plugged in here, this component will assume a low wind speed of < 0.2 m/s,
characteristic of most naturally ventilated buildings without fans. This input can also
accept several wind speeds to generate multiple comfort polygons. Lastly, this
component can accept the direct output of windSpeed from of the Import EPW
component and, from this data, two comfort polygons will be drawn representing the
maximum and minumu wind speed.
Optional comfort parameters from the "Ladybug_Adaptive Comfort Parameters"
component. Use this to select either the US or European comfort model, set the
threshold of acceptibility for comfort or compute prevailing outdoor temperature by a
monthly average or running mean. These comfortPar can also be used to set a
levelOfConditioning, which makes use of research outside of the official published
standards that surveyed people in air conditioned buildings.
includeColdTime [Optional]
Set to "True" to have the component include the time period where the outdoor
temperature is too cold for the official ASHRAE or European standard and set to "False"
to exclude it. When the outdoor temperatue is too cold for these standards, a correlation
from recent research is used. The default is set to "True" to include the cold period in
the visualization and output.
given and epw or energy simulation data has been connected, the analysis will be run
for the enitre year.
annualHourlyData [Optional]
An optional list of hourly data from the 'Import EPW' component, which will be used to
create hourPointColors that correspond to the hours of the data (e.g. windSpeed). You
can connect up several different annualHourly data here.
conditionalStatement [Optional]
This input allows users to remove data that does not fit specific conditions or criteria
from the adaptive chart. The conditional statement input here should be a valid
condition statement in Python, such as "a>25" or "b<80" (without quotation marks). The
81
Ladybug Primer
current version of this component accepts "and" and "or" operators. To visualize the
hourly data, only lowercase English letters should be used as variables, and each letter
alphabetically corresponds to each of the lists (in their respective order): "a" always
represents the 1st list plugged into annualHourlyData, "b" always represents the 2nd list
plugged into annualHourlyData, "c" always represents the 3rd list plugged into
annualHourlyData_, etc. For example, if you want to plot the data for the time period
when temperature is between 18C and 23C, and humidity is less than 80%, the
conditional statement should be written as 18<a<23 and b<80 (without quotation
marks).
basePoint [Optional]
An optional base point that will be used to place the adaptive chart in the Rhino scene.
If no base point is provided, the base point will be the Rhino model origin.
scale [Optional]
An optional number to change the scale of the adaptive chart in the Rhino scene. By
default, this value is set to 1.
runIt [Required]
Set to "True" to run the component and generate an Adaptive comfort chart.
Outputs
readMe!
...
comfPercentOfTime
The percent of the input data for which the occupants are comfortable. Comfortable
conditions are when the indoor temperature is within the comfort range determined by
the prevailing outdoor temperature.
percentHotCold
A list of 2 numerical values indicating the following: 0) The percent of the input data for
which the occupants are too hot. 1) The percent of the input data for which the
occupants are too cold.
82
Ladybug Primer
comfortableOrNot
A stream of 0's and 1's (or "False" and "True" values) indicating whether occupants are
comfortable under the input conditions given the fact that these occupants tend to adapt
themselves to the prevailing mean monthly temperature. 0 indicates that a person is not
comfortable while 1 indicates that a person is comfortable.
conditionOfPerson
A stream of interger values from -1 to +1 that correspond to each hour of the input data
and indicate the following: -1 = The input conditions are too cold for occupants. 0 = The
input conditions are comfortable for occupants. +1 = The input conditions are too hot for
occupants.
degreesFromTarget
A stream of temperature values in degrees Celcius indicating how far from the target
temperature the conditions of the people are. Positive values indicate conditions hotter
than the target temperature while negative values indicate degrees below the target
temperture.
chartCurvesAndTxt
The chart curves and text labels of the adaptive chart.
adaptiveChartMesh
A colored mesh showing the number of input hours happen in each part of the adaptive
chart.
legend
A colored legend showing the number of hours that correspond to each color.
legendBasePt
with the grasshopper "move" component.
comfortPolygons
A brep representing the range of comfort for.
chartHourPoints
Points representing each of the hours of input temperature and opTemperity ratio. By
83
Ladybug Primer
default, this ouput is hidden and, to see it, you should connect it to a Grasshopper
preview component.
hourPointColors
Colors that correspond to the chartHourPoints above and can be hooked up to the
"Swatch" input of a Grasshopper Preview component that has the hour points above
connected as geometry. By default, points are colored red if they lie inside comfort
polygon and are colored blue if they do not meet such comfort criteria. In the event that
you have hooked up annualHourlyData_ this output will be a grafted list of colors. The
first list corresponds to the comfort conditions while the second list colors points based
on the annualHourlyData.
hourPointLegend
A legend that corresponds to the hour point colors above. In the event that
annualHourlyData_ is connected, this output will be a grafted list of legends that each
correspond to the grafted lists of colors.
Check Hydra Example Files for Adaptive Comfort Chart
84
Ladybug Primer
Monthly Bar Chart
Use this component to make a bar chart in the Rhino scene of any monhtly or
avrMonthyPerHour climate data or simulation data. _ This component can also plot daily or
hourly data but, for visualizing this type of data, it is recommended that you use the
"Ladybug_3D Chart" component. -
Inputs
inputData [Required]
A list of input data to plot. This should usually be data out of the 'Ladybug_Average
Monthly_Bar_Chart
85
Ladybug Primer
Data' component or monthly data from an energy simulation but can also be hourly or
daily data from the 'Ladybug_Import EPW.' However, it is recommended that you use
the 'Ladybug_3D Chart' component for daily or hourly data as this is usually a bit
clearer.
comfortModel [Optional]
An optional interger to draw the comfort model on the chart. Choose from the following:
0 - No comfort range 1 - PMV comfort range (indoor) 2 - Adaptive confort range
(naturally ventilated) 3 - UTCI Comfort (outdoor) Note that this option is only available
when temperature is connected so, by default, it is set to 0 for no comfort range.
bldgBalancePt [Optional]
An optional float value to represent the outdoor temperature at which the energy
passively flowing into a building is equal to that flowing out of the building. This is
usually a number that is well below the comfort temperture (~ 12C - 18C) since the
internal heat of a building and its insulation keep the interior warmer then the exterior.
However, by default, this is set to 23.5C for fully outdoor conditions.
stackValues [Optional]
Set to 'True' if you have multiple connected monthly or daily _inputData with the same
units and want them to be drawn as bars stacked on top of each other. Otherwise, all
bars for monthly/daily data will be placed next to each other. The default is set to 'False'
to have these bars placed next to each other.
plotFromZero [Optional]
Set to 'True' to have the component plot all bar values starting from zero (as opposed
from the bottom of the chart, which might be a negative number). This is useful when
you are plotting the terms of an energy balance where you want gains to be above zero
and losses to be below. It can be detrimental if you are plotting temperatures in degrees
celcius and do not want negative values to go below zero. As such, the default is set to
'False' to not plot from zero.
altTitle [Optional]
An optional text string to replace the default title of the chart of the chart. The default is
set to pick out the location of the data connected to 'inputData.'
altYAxisTitle [Optional]
An optional text string to replace the default Y-Axis label of the chart. This can also be a
Monthly_Bar_Chart
86
Ladybug Primer
list of 2 y-axis titles if there are two different types of data connected to _inputData. The
default is set to pick out the names of the first (and possibly the second) list connected
to the 'inputData.'
basePoint [Default]
An optional point with which to locate the 3D chart in the Rhino Model. The default is set
to the Rhino origin at (0,0,0).
xScale [Default]
The scale of the X axis of the graph. The default is set to 1 and this will plot the X axis
with a length of 120 Rhino model units (for 12 months of the year).
yScale [Default]
The scale of the Y axis of the graph. The default is set to 1 and this will plot the Y axis
with a length of 50 Rhino model units.
Outputs
readMe!
...
dataMesh
A series of meshes that represent the different monthly (or daily) input data. Multiple
lists of meshes will be output for several input data streams.
dataCurves
A list of curves that represent the different avrMonthyPerHour and hourly input data.
Multiple lists of curves will be output for several input data streams.
dataCrvColors
A list of colors that correspond to the dataCurves above. Hook this up to the 'swatch'
input of the native Grasshopper 'Preview' component and the curves above up to the
'geometry input to preview the curves with their repective color.
graphAxes
Monthly_Bar_Chart
87
Ladybug Primer
A list of curves representing the axes of the chart.

graphLabels
A list of text meshes representing the time periods corresponding to the input data
title
A title for the chart. By default, this is just the location of the data but you can input a
custom title with the altTitle_ input.
titleBasePt
The title base point, which can be used to move the title in relation to the chart with the
grasshopper "move" component.
legend
A legend of the chart that tells what each connected data stram's color is. Connect this
output to a grasshopper "Geo" component in order to preview the legend in the Rhino
scene.
legendBasePt
dataLabelPts
A series of points that mark where each of the bars or lines of the chart lie. You can use
this to label the bars or lines with numerical values using a native grasshopper "text tag"
component and the data that you have connected to the _inputData of this component.
comfortBand
A series of meshes that represent the comfort range in each month according to the
input comfortModel_.
Check Hydra Example Files for Monthly Bar Chart
Monthly_Bar_Chart
88
Ladybug Primer
Psychrometric Chart
Use this component to draw a psychrometric chart in the Rhino scene and evaluate a set of
temperatures and humidity ratios in terms of indoor comfort. Connected data can include
either outdoor temperature and humidty ratios from imported EPW weather data, indoor
temperature and humidity ratios from an energy simulation, or indivdual numerical inputs of
temperature and humidity. The input data will be plotted alongside polygons on the chart
representing comfort as well as polygons representing the efects of passive building
strategies on comfort. The specific human energy balance model used by the psychrometric
chart is the Predicted Mean Vote (PMV) model developed by P.O. Fanger. PMV is a sevenpoint scale from cold (-3) to hot (+3) that is used in comfort surveys. Each interger value of
the scale indicates the following: -3:Cold, -2:Cool, -1:Slightly Cool, 0:Neutral, +1:Slightly
Psychrometric_Chart
89
Ladybug Primer
Warm, +2:Warm, +3:Hot. The range of comfort is generally accepted as a PMV between -1
and +1 and this is what defines the range of the comfort polygon on the psychrometric chart.
Accordingly, this component will also output the PMV of the occupant for the input conditions
as well as an estimated percentage of people dissatisfied (PPD) in the given conditions. The
comfort models that make this component possible were translated to python from a series
of validated javascript comfort models developed at the Berkely Center for the Built
Environment (CBE). Specific documentation on the comfort models can be found here:
https://code.google.com/p/cbe-comfort-tool/wiki/ComfortModels Special thanks goes to the
authors of the online CBE Thermal Comfort Tool who first made the javascript models in
order to power the tool: Hoyt Tyler, Schiavon Stefano, Piccioli Alberto, Moon Dustin, and
Steinfeld Kyle, 2013, CBE Thermal Comfort Tool. Center for the Built Environment,
University of California Berkeley, http://cbe.berkeley.edu/comforttool/ The information for the
polygons representing passive strategies comes from the climate consultant psychrometric
chart. Further information on how these polygons are calculated can be found here:
http://apps1.eere.energy.gov/buildings/tools_directory/software.cfm/ID=123/pagename=alph
a_list -
Inputs
direct output of dryBulbTemperature from the Import EPW component. Indoor
temperatures from Honeybee energy simulations are also possible inputs. Finally, this
component can also acccept temperatures in Farenheit in order to draw a chart with IP
units but, in order for this component to sense that the values are Farenheit, there must
be at least one 'F' or 'F' in the stream of connected data.
component.
barometricPressure [Optional]
A number representing the barometric pressure in Pascals. If no value is connected
here, the default pressure will be 101325 Pa, which is air pressure at sea level. It is
recommended that you connect the barometric pressure from the Import epw
component here as the air pressure at sea level can cause some misleading results for
Psychrometric_Chart
90
Ladybug Primer
cities at higher elevations.

meanRadTemperature [Optional]
A number representing the mean radiant temperature of the surrounding surfaces. This
value should be in degrees Celcius unless you have connected values in Farenheit to
the dryBulbTemperature and you are seeing a chart in IP units. If no value is plugged in
here, this component will assume that the mean radiant temperature is equal to 23 C.
This input can also accept a list of temperatures and this will produce several comfort
polygons (one for each mean radiant temperature).
representing conditions and this will produce several comfort polygons (one for each
wind speed).
This input can also accept lists of metabolic rates and will produce multiple comfort
polygons accordingly.
as 2 to 4 clo. This input can also accept lists of clothing levels and will produce multiple
comfort polygons accordingly.
mergeComfPolygons [Optional]
Set to "True" if you have connected multiple values for any of the four comfort variables
in the section above and you wish to merge all of the computed comfort polygons into
one.
Psychrometric_Chart
91
Ladybug Primer
Optional comfort parameters from the "Ladybug_PMV Comfort Parameters" component.
Use this to adjust maximum and minimum acceptable humidity ratios. These comfortPar
can also change whether comfort is defined by eighty or ninety percent of people
comfortable.
passiveStrategy [Optional]
An optional text input of passive strategies to be laid over the psychrometric chart as
polygons. It is recommended that you use the "Ladybug_Passive Strategy List" to select
which polygons you would like to display. Otherwise, acceptable text inputs include
"Evaporative Cooling", "Thermal Mass + Night Vent", "Occupant Use of Fans", "Internal
Heat Gain", and "Dessicant Dehumidification".
strategyPar [Optional]
Optional passive strategy parameters from the "Ladybug_Passive Strategy Parameters"
component. Use this to adjust the maximum comfortable wind speed, the building
balance temperature, and the temperature limits for thermal mass and night flushing.
mollierHX [Optional]
Set to "True" to visualize the psychrometric chart as a mollier-hx diagram. This is
essentially a psychrometric chart where the axes have been switched, which is popular
in Europe.
enthalpyOrWetBulb [Optional]
Set to "True" to have the psychrometric chart plot lines of constant enthalpy and set to
"False" to have the chart plot linest of constant wet bulb temperature. The default is set
to "True" for enthalpy.
An optional analysis period from the Ladybug_Analysis Period component. If no
Analysis period is given and epw data from the ImportEPW component has been
connected, the analysis will be run for the enitre year.
An optional list of hourly data from the Import epw component, which will be used to
create hourPointColors that correspond to the hours of the data (e.g. windSpeed). You
can connect up several different annualHourly data here.
Psychrometric_Chart
92
Ladybug Primer
from the psychrometric chart. The conditional statement input here should be a valid
condition statement in Python, such as "a>25" or "b<80" (without quotation marks). The
current version of this component accepts "and" and "or" operators. To visualize the
hourly data, only lowercase English letters should be used as variables, and each letter
alphabetically corresponds to each of the lists (in their respective order): "a" always
represents dryBulbtemperature, "b" always represents the relativeHumidity, "c" always
represents the 1st list plugged into annualHourlyData_, "d" represents the 2nd list, etc.
For example, if you want to plot the data for the time period when temperature is
between 18C and 23C, and humidity is less than 80%, the conditional statement should
be written as 18<a<23 and b<80 (without quotation marks).
An optional base point that will be used to place the Psychrometric Chart in the Rhino
scene. If no base point is provided, the base point will be the Rhino model origin.
scale [Optional]
An optional number to change the scale of the spychrometric chart in the Rhino scene.
By default, this value is set to 1.
runIt [Required]
Set to "True" to run the component and generate a psychrometric chart!
Outputs
readMe!
...
totalComfortPercent
The percent of the input data that are inside all comfort and passive strategy polygons.
totalComfortOrNot
A list of 0's and 1's indicating, for each hour of the input data, if the hour is inside a
Psychrometric_Chart
93
Ladybug Primer
comfort or strategy polygon (1) or not(0).

strategyNames
A list of names for the comfort polygons and strategeis that corresponds to the numbers
in the following outputs.
strategyPercentOfTime
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 "strategyNames" output
above.
strategyOrNot
A list of 0's and 1's indicating, for each hour of the input temperature and humidity ratio,
if the hour is inside a given comfort or passive strategy polygon (1) or not(0). If there are
multiple comfort polyogns or passive strategies connected to the passiveStrategy_
input, this output will be a grafted list for each polygon. Each list here corresponds to the
names in the "strategyNames" output above.
chartCurvesAndTxt
The chart curves and text labels of the psychrometric chart.
psychChartMesh
A colored mesh showing the number of input hours happen in each part of the
psychrometric chart.
legend
A colored legend showing the number of hours that correspond to each color.
legendBasePt
comfortPolygons
A brep representing the range of comfort for the input radiant temperature, wind speed,
metabolic rate and clothing level. IF multiple values have been hooked up for any of
these inputs, multiple polygons will be output here.
strategyPolygons
Psychrometric_Chart
94
Ladybug Primer
A brep representing the area of the chart made comfortable by the passive strategies. If
multiple strategies have been hooked up to the passiveStrategy_ input, multiple
polygons will be output here.
chartHourPoints
Points representing each of the hours of input temperature and humidity ratio. By
preview component.
hourPointColors
Colors that correspond to the chartHourPoints above and can be hooked up to the
"Swatch" input of a Grasshopper Preview component that has the hour points above
connected as geometry. By default, points are colored red if they lie inside comfort or
strategy polygons and are colored blue if they do not meet such comfort criteria. In the
event that you have hooked up annualHourlyData_ this output will be a grafted list of
colors. The first list corresponds to the comfort conditions while the second list colors
points based on the annualHourlyData.
hourPointLegend
A legend that corresponds to the hour point colors above. In the event that
annualHourlyData_ is connected, this output will be a grafted list of legends that each
correspond to the grafted lists of colors.
Check Hydra Example Files for Psychrometric Chart
Psychrometric_Chart
95
Ladybug Primer
GenCumulativeSkyMtx
This component uses Radiance's gendaymtx function to calculate the sky's radiation for
each hour of the year. This is a necessary pre-step before doing radiation analysis with
Rhino geometry or generating a radiation rose. The first time you use this component, you
will need to be connected to the internet so that the component can download the
"gendaymtx.exe" function to your system. Gendaymtx is written by Ian Ashdown and Greg
Ward. For more information, check the Radiance manual at: http://www.radianceonline.org/learning/documentation/manual-pages/pdfs/gendaymtx.pdf -
Inputs
GenCumulativeSkyMtx
96
Ladybug Primer
epwFile [Required]
The output of the Ladybug Open EPW component or the file path location of the epw
weather file on your system.
skyDensity [Default]
Set to 0 to generate a Tregenza sky, which will divide up the sky dome with a coarse
density of 145 sky patches. Set to 1 to generate a Reinhart sky, which will divide up the
sky dome using a very fine density of 580 sky patches. Note that, while the Reinhart sky
is more accurate, it will result in considerably longer calculation times. Accordingly, the
default is set to 0 for a Tregenza sky.
An optional working directory in your system where the sky will be generated. Default is
set to C:\Ladybug or C:\Users\yourUserName\AppData\Roaming\Ladybug. The latter is
used if you cannot write to the C:\ drive of your computer. Any valid file path location
can be connected.
useOldRes [Optional]
Set this to "True" if you have already run this component previously and you want to use
the already-generated data for this weather file.
runIt [Required]
Set to "True" to run the component and generate a sky matrix.
Outputs
readMe!
...
cumulativeSkyMtx
The result of the gendaymtx function. Use the selectSkyMtx component to select a
desired sky matrix from this output for use in a radiation study, radition rose, or sky
dome visualization.
Check Hydra Example Files for GenCumulativeSkyMtx
GenCumulativeSkyMtx
97
Ladybug Primer
selectSkyMtx
Use this component to select a specific sky matrix (skyMxt) for an hour of the year or for an
analysis period. -
Inputs
cumulativeSkyMtx [Required]
The output from a GenCumulativeSkyMtx component.
HOY [Optional]
selectSkyMtx
98
Ladybug Primer
An hour of the year for which you would like to select a sky. This must be a value
between 1 and 8760.
An analysis period from Analysis Period component. This will override an input HOY
(hour of the year).
removeDiffuse [Optional]
Set to "True" if you want to remove the diffuse component of the selected sky.
removeDirect [Optional]
Set to "True" if you want to remove the direct component of the selected sky.
Outputs
readMe!
...
selectedSkyMtx
The selected sky matrix (SkyMtx) for the input hour of the year or an analysis period.
Check Hydra Example Files for selectSkyMtx
selectSkyMtx
99
Ladybug Primer
Colored Sky Visualizer
Use this component to visualize a Perez sky as a colored mesh in the Rhino scene using the
weather file location, a time and date, and an estimate of turbidity (or amount of particulates
in the atmosphere. -
Inputs
north [Optional]
Input a vector to be used as a true North direction for the sky dome or a number
between 0 and 360 that represents the degrees off from the y-axis to make North. The
100
Ladybug Primer
default North direction is set to the Y-axis (0 degrees).

location [Required]
hour [Default]
A number between 1 and 24 (or a list of numbers) that represent hour(s) of the day to
position sun on the sky dome. The default is 12, which signifies 12:00 PM.
day [Default]
A number between 1 and 31 (or a list of numbers) that represent days(s) of the month to
position sun on the sky dome. The default is 21, which signifies the 21st of the month
(when solstices and equinoxes occur).
month [Default]
A number between 1 and 12 (or a list of numbers) that represent months(s) of the year
to position sun on the sky dome. The default is 12, which signifies December.
turbidity [Optional]
A number between 2 and 15 that represents the level of particulate matter in the
atmosphere of the sky. A rural location might have a low turbidity of 2 while a place like
Beijing might have a turbidity as high as 10 or 12. The default is set to 3 for a relatively
clear sky without much pollution.
resolution [Optional]
An optional input for the resolution of the generated mesh. A higher resolution will
produce a less-splotchy image but will take longer to calculate. The default is set to 10
for a realtively quick calculation.
scale [Optional]
An optional input to scale the dome mesh. The default is set to 1.
centerPt [Optional]
An optional point to move the center of the sky dome mesh. The default is set to the
Rhino origin.
domeOrRect [Optional]
101
Ladybug Primer
Set to "True" to generate a sky color mesh that is in the shape of a dome and set to
"False" to generate a sky as a flat rectangular mesh. The default is set to "True" to
generate the sky as a dome.
Outputs
readMe!
...
coloredMesh
A colored mesh of the sky.
meshLabels
Time and date lables for the sky mesh.
skyColorRGB
The RGB colors that correspond to the vertices of the mesh above.
skyColorXYZ
The XYZ colors that correspond to the vertices of the mesh above.
Check Hydra Example Files for Colored Sky Visualizer
102
Ladybug Primer
Outdoor Solar Temperature Adjustor
Use this component to adjust an existing Mean Radiant Temperature for shortwave solar
radiation. This adjusted mean radiant temperature can then be used in comfort studies. Note
that this component assumes that you have already accounted for longwave radiation in the
form of the _meanRadTemperature input. If you do not hook up a _meanRadTemperature,
this component will assume that the surrounding radiant temperature is the same as the air
temperature, which is a decent assumption for someone standing in an unobstructed field.
However, the more obstacles that surround the person (and the more "context" that you
add), the more important it is to derive a starting mean radiant temperature from a Honeybee
Energy simulation. Also note that this component is not meant to account for shortwave
radiation passing through glass. This component uses Radiance functions in order to
103
Ladybug Primer
determine the amount of direct and diffuse solar radiation falling on a comfort mannequin.
The portion reflected off of the ground to the comfort mannequin is derived from these
values of direct and diffuse radiation. Lastly, the formulas to translate this radiation into an
effective radiant field and into a solar-adjusted mean radiant temperature come from this
paper: Arens, Edward; Huang, Li; Hoyt, Tyler; Zhou, Xin; Shiavon, Stefano. (2014). Modeling
the comfort effects of short-wave solar radiation indoors. Indoor Environmental Quality
(IEQ). http://escholarship.org/uc/item/89m1h2dg#page-4 -
Inputs
location [Required]
The location output from the 'Ladybug_Import epw' component.
cumSkyMtxOrDirNormRad [Required]
Either the output from a GenCumulativeSkyMtx component (for high-resolution analysis)
or the directNormallRadiation ouput from the 'Ladybug_Import epw' component (for
simple, low-resolution analsysis).
meanRadTemperature [Required]
A number or list of numbers representing the mean radiant temperature of the
surrounding surfaces in degrees Celcius. This number will be modified to account for
solar radiation. This input can be air temperature data from the 'Importepw' component
and will follow the assumption that the surrounding mean radiant temperature is the
same as the air temperature. This assumption is ok for a person in an outdoor open
field. However, the more obstacles that surround the person (and the more
'contextShading' that you add), the more important it is to derive a starting mean radiant
temperature from a Honeybee Energy simulation.
bodyPosture [Optional]
An interger between 0 and 5 to set the posture of the comfort mannequin, which can
have a large effect on the radiation for a given sun position. 0 = Standing, 1 = Sitting, 2
= Lying Down, 3 = Low-Res Standing, 4 = Low-Res Sitting, and 5 = Low-Res Lying
Down. The default is set to 1 for sitting.
rotationAngle [Optional]
An optional rotation angle in degrees. Use this number to adjust the angle of the comfort
mannequin in space. The angle of the mannequin in relation to the sun can have a large
effect on the amount of radiation that falls on it and thus largely affect the resulting
mean radiant temperature.
104
Ladybug Primer
bodyLocation [Optional]
An optional point that sets the position of the comfort mannequin in space. Use this to
move the comfort mannequin around in relation to contextShading_ connected below.
Note that this point should be the center of gravity of your person. The default is set to a
person just above the Rhino origin.
contextShading [Optional]
Optional breps or meshes that represent shading or opaque solar obstructions around
the mannequin. If you are using this component for indoor studies, windows or any
transparent materials should not be included in this geometry. You should factor the
transmissivity of these materials in with the windowTransmissivity_ input. Also, note
that, if you have a lot of this context geometry, you should make sure that you input a
starting _meanRadTemperature that accounts for the temperature of all the temperture
of these shading surfaces.
north [Optional]
groundReflectivity [Optional]
An optional decimal value between 0 and 1 that represents the fraction of solar radiation
reflected off of the ground. By default, this is set to 0.25, which is characteristic of
outdoor grass or dry bare soil. You may want to increase this value for concrete or
decrease it for water or dark soil.
clothingAbsorptivity [Optional]
An optional decimal value between 0 and 1 that represents the fraction of solar radiation
absorbed by the human body. The default is set to 0.7 for (average/brown) skin and
average clothing. You may want to increase this value for darker skin or darker clothing.
windowTransmissivity [Optional]
An optional decimal value between 0 and 1 that represents the transmissivity of
windows around the person. This can also be a list of 8760 values between 0 and 1 that
represents a list of hourly window transmissivties, in order to represent the effect of
occupants pulling blinds over the windows, etc. Note that you should only set a value
here if you are using this component for indoor analysis where the only means by which
sunlight will hit an occupant is if it comes through a window. The default is set to 1 for
105
Ladybug Primer
outdoor conditions.
analysisPeriodOrHOY [Optional]
An optional analysis period from the 'Analysis Period component' or an hour of the year
between 1 and 8760 for which you want to conduct the analysis. If no value is
connected here, the component will run for noon on the winter solstice.
tempOrRad [Optional]
Set to 'True' to have the mannequin labled with adjusted perceived radiant temperature
and set to 'False' to have the mannequin labled with total radiation falling on the person.
parallel [Optional]
Set to 'True' to run the component using multiple CPUs. This can dramatically decrease
calculation time but can interfere with other intense computational processes that might
be running on your machine. For this reason, the default is set to 'True.'
runIt [Required]
with the grasshopper 'move' component.
Outputs
readMe!
...
effectiveRadiantField
The estimated effective radiant field of the comfort mannequin induced by the sun for
each hour of the analysis period. This is in W/m2.
MRTDelta
The estimated change in mean radiant temperature for the comfort mannequin induced
by the solar radiation. This is in degreed Celcius.
solarAdjustedMRT
106
Ladybug Primer
The estimated solar adjusted mean radiant temperature for each hour of the analysis
period. This is essentially the change in mean radiant temperature above added to the
hourly _meanRadTemperature input. This is in degreed Celcius and can be plugged into
any comfort components for comfort studies.
mannequinMesh
A colored mesh of a comfort mannequin showing the amount of radiation falling over the
mannequin's body.
legend
A legend that corresponds to the colors on the mannequinMesh and shows the relative
W/m2.
legendBasePt
The input data normalized by the floor area of it corresponding zone.
meshFaceResult
If 'tempOrRad' is set to True, this will be the estimated solar adjusted radiant
temperature for each mesh face of the mannequin in degrees Celcius. This radiant
temperature is averaged over the the entire analysis period. if 'tempOrRad' is set to
False, this will be the total radiation on each mesh face over the analysis period.
meshFaceArea
The areas of each mesh face of the mannequin in square Rhino model units. This list
corresponds to the meshFaceRadTemp list above and can be used to help inform
statistical analysis of the radiant assymmetry over the mannequin.
Check Hydra Example Files for Outdoor Solar Temperature Adjustor
107
Ladybug Primer
Radiation Calla Lily
Use this component to draw Radiation Calla Lily or Dome, which shows you how radiation
would fall on an object from all directions for a given sky. It is useful for finding the best
direction with which to orient solar panels and gives a sense of the consequences of
deviating from such an orientation. The Calla Lily/Dome can be understood in three different
ways: _ 1) The Calla Lily/Dome a 3D representation of all possible radiation roses for a
given sky since it includes all vertical angles from 0 to 90. 2) The Calla Lily/Dome is the
reciprocal of the Tergenza Sky Dome since the Cala Dome essentially shows you how the
radiation from the sky will fall onto a hemispherical object. 3) The Calla Lily/Dome is a smart
radiation analysis of a hemisphere. Your results would effectively be the same if you made a
108
Ladybug Primer
hemisphere in Rhino and ran it through the "Radiation Analysis" component but, with this
component, you will get a smoother color gradient and the component will automatically
output the point (or vector) with the most radiation. -
Inputs
selectedSkyMtx [Required]
The output from the selectSkyMtx component.
horAngleStep [Default]
An angle in degrees between 0 and 360 that represents the step for horizontal rotation.
Smaller numbers will yeild a finer and smoother mesh with smoother colors. The
number input here should be smaller than 360 and divisible by 360. The default is set to
10 degrees.
verAngleStep [Default]
Angle in degrees step between 0 and 90 that represents the step for vertical rotation.
Smaller numbers will yeild a finer and smoother mesh with smoother colors. The
number input here should be smaller than 90 and divisible by 90. The default is set to
10 degrees.
centerPoint [Default]
Input a point to locate the center point of the Calla Lily Graph
horScale [Default]
Input a number here to change horizontal (XY) scale of the graph. The default value is
set to 1. Note that, for the dome representation, this input will change the scale of the
entire dome (both horizontal and vertical).
verScale [Default]
Input a number here to change vertical (Z) scale of the graph. The default value is set to
1. Note that, for the dome representation, this input will have no effect.
domeOrLily [Optional]
Set to "True" to have the component create a radiation dome and set to "False" to have
it generate a Lily. The default is set to "False" for a Lily. The difference between the
Dome and the Lily is that, for the Lily, the Z scale is essentially the same as the color
scale, which is redundant but also beautiful and potentially useful if you have to present
109
Ladybug Primer
data with a Black/White printer or to someone who is color blind. For the Dome, the
vertical angles of rotation serve to define the Z scale. In this sense, the normal to the
dome at any given point is the angle at which the radiation study is being run. This gives
a geometric intuitive sense of how you should orient panels to capture or avoid the most
sun.
runIt [Required]
Set to "True" to run the component and generate a radiation Calla Lily.
bakeIt [Optional]
Set to "True" to bake the Calla Lily into the Rhino scene.
Outputs
readMe!
...
radiationLilyMesh
A colored mesh representing radiation of the Calla Lily or Dome.
baseCrvs
A set of guide curves for the Calla Lily.
legend
A legend of the radiation on the Calla Lily. Connect this output to a grasshopper "Geo"
component in order to preview the legend in the Rhino scene.
testPts
The vertices of the Calla Lily mesh. These are hidden by default.
testPtsInfo
Information for each test point of the Calla Lily mesh. "HRA" stands for "Horizontal
Rotation Angle" while "VRA" stand for "Vertical Rotation Angle." HRA varies from 0 to
360 while VRA varies from 0 to 90.
110
Ladybug Primer
values
The radiation values for each test points (or mesh faces) of the Calla Lily in kWh/m2.
maxRadPt
The point on the Cala Lilly with the greatest amount of solar radiation. This is useful for
understanding the best direction to orient solar panels.
maxRadVector
The vector that should be used to orient solar panels such that they recieve the greatest
possible solar radiation.
maxRadInfo
Information about the test point with the greates amount of radiation in the Calla Lily.
"HRA" stands for "Horizontal Rotation Angle" while "VRA" stand for "Vertical Rotation
Angle." HRA varies from 0 to 360 while VRA varies from 0 to 90.
Check Hydra Example Files for Radiation Calla Lily
111
Ladybug Primer
Radiation Rose
Use this component to make a radiation rose in the Rhino scene. Radiation roses give a
sense of how much radiation comes from the different cardinal directions, which will give an
initial idea of where glazing should be minimized, shading applied, or solar collectors placed.
-
Inputs
north [Optional]
Radiation_Rose
112
Ladybug Primer
context [Optional]
Optional breps or meshes representing context surrounding the point at the center of
the radiation rose. This context geometry will block the radiation that shows up in the
rose.
numOfArrows [Default]
An interger that sets the number of arrows (or cardingal directions) in the radiation rose.
The default is set to 36.
surfaceTiltAngle [Default]
A number between 0 and 90 that sets the tilt angle in degrees of the analysis plane (0 =
roof, 90 = vertical wall). The defult is set to 90 for a radiation study of a wall (ie. radiation
on a curtain wall).
A point that sets the location of the radiation rose. The default is set to the Rhino origin
(0,0,0).
scale [Default]
Use this input to change the scale of the radiation rose. The default is set to 1 for any
selSkyMtx that is longer than a day and 1000 for any selSkyMtx that is less than a day.
arrowHeadScale [Default]
Use this input to change the scale of the arrow heads of the radiation rose. The default
is set to 1.
showTotalOnly [Optional]
Set to "True" to only show a radiation rose with the total radiation. The default is "False",
which will produce 3 radiation roses: one of diffuse radiation, one of direct radiation, and
Radiation_Rose
113
Ladybug Primer
one of the total radiation.

runIt [Required]
Set to "True" to run the component and generate a radiation rose.
bakeIt [Optional]
Set to "True" to bake the radiation rose into the Rhino scene.
Outputs
readMe!
...
radiationArrowsMesh
A colored mesh representing the intensity of radiation from different cardinal directions.
radRoseBaseCrvs
A set of guide curves that mark the directions of radiation analysis.
legend
A legend of the radiation rose. Connect this output to a grasshopper "Geo" component
in order to preview the legend separately in the Rhino scene.
legendBasePts
The legend base point(s), which can be used to move the legend(s) in relation to the
rose with the grasshopper "move" component.
radRoseEndPts
The end points of the rose arrows.
radRoseValues
The radiation values in kWh/m2 for each rose arrow.
Check Hydra Example Files for Radiation Rose
Radiation_Rose
114
Ladybug Primer
Sky Dome
This component allows you to visualize a selected sky matrix from the selectSkyMxt
component in order to see the patches of the sky dome where radiation is coming from. The
component will produce 3 sky domes by default: a dome showing just the diffuse radiation, a
dome showing just the direct radiation, and a dome showing the total radiation. -
Inputs
north [Optional]
Sky_Dome
115
Ladybug Primer
A point that sets the location of the sky domes. The default is set to the Rhino origin
(0,0,0).
scale [Default]
Use this input to change the scale of the sky dome. The default is set to 1.
showTotalOnly [Optional]
Set to "True" to only show a sky dome with the total radiation. The default is "False",
which will produce 3 sky domes: one of diffuse radiation, one of direct radiation, and
one of the total radiation.
runIt [Required]
Set to "True" to run the component and generate a sky dome.
bakeIt [Optional]
Set to "True" to bake the sky dome into the Rhino scene.
Outputs
readMe!
...
skyPatchesMesh
A colored mesh representing the intensity of radiation for each of the sky patches of the
sky dome.
baseCrvs
Sky_Dome
116
Ladybug Primer
A set of guide curves that mark information on the sky dome.

legend
A legend for the sky dome. Connect this output to a grasshopper "Geo" component in
order to preview the legend separately in the Rhino scene.
legendBasePts
sky domes with the grasshopper "move" component.
skyPatchesCenPts
The center points of sky patches, which can be used to shape Rhino geometry in
relation to radiation from different sky patches.
skyPatchesAreas
The area of sky patches in Rhino model units.
skyPatchesAsBrep
The geometry of sky patches as breps.
values
Radiation values for the sky patches in kWh/m2.
Check Hydra Example Files for Sky Dome
Sky_Dome
117
Ladybug Primer
SunPath
Use this component to make a 3D sun-path (aka. sun plot) in the Rhino scene. The
component also outputs sun vectors that can be used for sunlight hours analysis or shading
design with the other Ladybug components. The sun-path function used here is a Python
version of the RADIANCE sun-path script by Greg Ward. The RADIANCE source code can
be accessed at: http://www.radiance-online.org/download-install/CVS%20source%20code -
Inputs
north [Optional]
SunPath
118
Ladybug Primer
location [Required]
hour [Default]
A number between 1 and 24 (or a list of numbers) that represent hour(s) of the day to
position sun sphere(s) on the sun path. The default is 12, which signifies 12:00 PM.
day [Default]
A number between 1 and 31 (or a list of numbers) that represent days(s) of the month to
position sun sphere(s) on the sun path. The default is 21, which signifies the 21st of the
month (when solstices and equinoxes occur).
month [Default]
A number between 1 and 12 (or a list of numbers) that represent months(s) of the year
to position sun sphere(s) on the sun path. The default is 12, which signifies December.
timeStep [Default]
The number of timesteps per hour in the sun path. This number should be smaller than
60 and divisible by 60. The default is set to 1 such that one sun sphere and one sun
vector is generated for each hour. Note that a linear interpolation will be used to
generate curves and suns for timeSteps greater than 1.
An optional analysis period from the Analysis Period component. Inputs here will
override the hour, day, and month inputs above.
centerPt [Default]
Input a point here to change the location of the sun path in the Rhino scene. The default
is set to the Rhino model origin (0,0,0).
sunPathScale [Default]
Input a number here to change the scale of the sun path. The default is set to 1.
SunPath
119
Ladybug Primer
sunScale [Default]
Input a number here to change the scale of the sun spheres located along the sun path.
The default is set to 1.
An optional list of hourly data from the Import epw component, which will be used to
color the sun spheres of the sun path (e.g. dryBulbTemperature).
from the sun path. To use this input correctly, hourly data, such as temperature or
humidity, must be plugged into the annualHourlyData input. The conditional statement
input here should be a valid condition statement in Python, such as "a>25" or "b<80"
(without quotation marks). The current version of this component accepts "and" and "or"
operators. To visualize the hourly data, only lowercase English letters should be used
as variables, and each letter alphabetically corresponds to each of the lists (in their
respective order): "a" always represents the 1st list, "b" always represents the 2nd list,
etc. For example, if you have hourly dry bulb temperature connected as the first list, and
relative humidity connected as the second list (both to the annualHourlyData input), and
you want to plot the data for the time period when temperature is between 18C and
23C, and humidity is less than 80%, the conditional statement should be written as
18<a<23 and b<80 (without quotation marks).
dailyOrAnnualSunPath [Default]
By default, this value is set to "True" (or 1), which will produce a sun path for the whole
year. Set this input to "False" (or 0) to generate a sun path for just one day of the year
(or several days if multiple days are included in the analysis period).
solarOrStandardTime [Optional]
Set to 'True' to have the sunPath display in solar time and set to 'False' to have it
display in standard time. The default is set to 'False.' Note that this input only changes
the way in which the supath curves are drawn currently and does not yet change the
position of the sun based on the input hour.
bakeIt [Optional]
SunPath
120
Ladybug Primer
Set to True to bake the sunpath into the Rhino scene.
Outputs
readMe!
...
sunVectors
Vector(s) indicating the direction of sunlight for each sun position on the sun path.
sunAltitudes
Number(s) indicating the sun altitude(s) in degrees for each sun position on the sun
path.
sunAzimuths
Number(s) indicating the sun azimuths in degrees for each sun position on the sun path.
sunSpheresMesh
A colored mesh of spheres representing sun positions. Colors indicate
annualHourlyData and will be yellow if no data is hooked up to annualHourlyData.
sunPathCrvs
A set of guide curves that mark the path of the sun across the sky dome.
legend
A legend for the sun path. Connect this output to a grasshopper "Geo" component in
legendBasePts
sun path with the grasshopper "move" component.
title
The title text of the sun path. Hook this up to a native Grasshopper 'Geo' component to
preview it separately from the other outputs.
titleBasePt
SunPath
121
Ladybug Primer
Point for the placement of the title, which can be used to move the title in relation to the
sun path with the native Grasshopper "Move" component.
sunPathCenPts
The center point of the sun path (or sun paths if multiple annualHourlyData_ streams
are connected). Use this to move sun paths around in the Rhino scene with the
grasshopper "move" component.
sunPositions
Point(s) idicating the location on the sun path of each sun position.
sunPositionsInfo
Detailied information for each sun position on the sun path including date and time.
sunPositionsHOY
The hour of the year for each sun position on the sun path.
selHourlyData
The annualHourlyData for each sun position on the sun path. Note that this data has the
following removed from it: 1) Any parts of the annualHourlyData that happen when the
sun is down, 2) annualHourlyData that is not apart of the analysisPeriod and, 3)
annualHourlyData_ that does not fit the conditional statement.
Check Hydra Example Files for SunPath
SunPath
122
Ladybug Primer
Wind Boundary Profile
Use this component to visualize a wind profile curve for a given terrain type. Wind speed
increases as one leaves the ground and wind profiles are a means of visualizing this change
in wind speed with height. - More information on the power law of the wind profile can be
found here: http://en.wikipedia.org/wiki/Wind_profile_power_law -
Inputs
north [Optional]
123
Ladybug Primer
windSpeed_tenMeters [Required]
The wind speed from the import EPW component or a number representing the wind
speed at 10 meters off the ground. If this value is input without a corresponding wind
direction below, the profile will be drawn with the average of the speed input here. If
corresponding values are connected to the windDirection, the speed on the profile will
be the average speed of the prevailing wind direction.
windDirection [Optional]
An optional number representing the degrees from north of the wind direction. This can
also be the windDirection output from the import EPW component. This direction will be
used to orient the wind profile in 3 dimensions to the direction of the prevailing wind.
terrainType [Optional]
An interger from 0 to 3 that sets the terrain class associated with the output
windSpeedAtHeight. Interger values represent the following terrain classes: 0 = Urban:
large city centres, 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, unobstructed areas exposed to
wind flowing over a large water body (no more than 500m inland).
epwTerrain [Optional]
An optional interger from 0 to 3 that sets the terrain class associated with the output
windSpeedAtHeight. The default is set to 2 for flat clear land, which is typical for most
EPW files that are recorded at airports. Interger values represent the following terrain
classes: 0 = Urban: large city centres, 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, unobstructed areas
exposed to wind flowing over a large water body (no more than 500m inland).
HOY [Optional]
Use this input to select out specific indices of a list of values connected for wind speed
and wind direction. If you have connected hourly EPW data, this is the equivalent of a
"HOY" input and you can use the "LadybugDOY_HOY" component to select out a
specific hour and date. Note that this overrides the analysisPeriod input below.
124
Ladybug Primer
If you have connected data from an EPW component, plug in an analysis period from
the Ladybug_Analysis Period component to calculate data for just a portion of the year.
The default is Jan 1st 00:00 - Dec 31st 24:00, the entire year.
An optional list of hourly data from the Import epw component, which will be overlaid on
wind rose (e.g. dryBulbTemperature)
from the wind rose. To use this input correctly, hourly data, such as temperature or
etc. For the WindBoundaryProfile component, the variable "a" always represents
windSpeed. For example, if you have hourly dry bulb temperature connected as the
second list, and relative humidity connected as the third list (both to the
annualHourlyData input), and you want to plot the data for the time period when
temperature is between 18C and 23C, and humidity is less than 80%, the conditional
statement should be written as 18<b<23 and c<80 (without quotation marks).
originPt [Optional]
An optional point that can be used to change the base point at shich the wind profile
curves are generated. By default, the wond profile curves generate at the Rhino model
origin.
windVectorScale [Optional]
An optional number that can be used to change the scale of the wind vectors in relation
to the height of the wind profile curve. The default is set to 5 so that it is easier to see
how the wind speed is changing with height.
windProfileHeight [Optional]
An optional number in rc model units that can be used to change the height of the wind
profile curve. By default, the height of the curve is set to 30 meters (or the equivalent
distance in your Rhino model units). You may want to move this number higher or lower
depending on the wind effects that you are interested in.
125
Ladybug Primer
distBetweenVec [Optional]
An optional number in rhino model units that represents the distance between wind
vectors in the profile curve. The default is set to 2 meters (or the equivalent distance in
your rc model units).
windArrowStyle [Optional]
An optional integer to set the style of the wind vectors. The default is set to 1 for colored
arrows. Choose from the following options: 0 = No Wind Arrows - use this option if you
do not want to gerenate arrows. 1 = 3D Colored Wind Arrows - use this option to
generate arrows as a colored 3D mesh (arrows will be colored based on the magnitude
of their wind speed). 2 = High-Res 3D Colored Wind Arrows - use this option to create
color arrows just like Option 1 but with a circular cross section and smooth edges. 3 =
Colored Line Wind Arrows - use this option to generate arrows as lines with colored tips.
4 = Black Line Wind Arrows - use this option to generate arrows as lines with black tips.
bakeIt [Optional]
Set to "True" to bake the wind boundary profile into the Rhino scene.
Outputs
readMe!
...
windSpeeds
The wind speeds that correspond to the wind vectors in the wind profile visualization.
windVectors
The wind vectors that correspond to those in the wind profile visualization. Note that the
magnitude of these vectors will be scaled based on the windVectorScale_ input.
vectorAnchorPts
Anchor points for each of the vectors above, which correspond to the height above the
ground for each of the vectors. Connect this along with the output above to a
Grasshopper "Vector Display" component to see the vectors as a grasshopper vector
126
Ladybug Primer
display (as opposed to the vector mesh below).

windVectorMesh
A mesh displaying the wind vectors that were used to make the profile curve.
windProfileCurve
A curve outlining the wind speed as it changes with height. This may also be a list of
wind profile curves if multiple "HOY" inputs are connected or "averageData" is set to
False."
profileAxes
Script variable WindBoundaryProfile
axesText
The meshes of the axes text (labelling wind speeds and heights).
legend
A legend of the wind profile curves. Connect this output to a grasshopper "Geo"
component in order to preview the legend separately in the rc scene.
legendBasePt
The legend base point(s), which can be used to move the legend in relation to the wind
profile with the grasshopper "move" component.
Check Hydra Example Files for Wind Boundary Profile
127
Ladybug Primer
Wind Rose
Use this component to make a windRose in the Rhino scene. -
Inputs
north [Default]
Input a vector to be used as a true North direction for the wind rose or a number
between 0 and 360 that represents the degrees off from the y-axis to make North. The
default North direction is set to the Y-axis (0 degrees).
Wind_Rose
128
Ladybug Primer
hourlyWindDirection [Required]
The list of hourly wind direction data from the Import epw component.
hourlyWindSpeed [Required]
The list of hourly wind speed data from the Import epw component.
An optional list of hourly data from the Import epw component, which will be overlaid on
wind rose (e.g. dryBulbTemperature)
An optional analysis period from the Analysis Period component.
from the wind rose. To use this input correctly, hourly data, such as temperature or
etc. For the WindBoundaryProfile component, the variable "a" always represents
windSpeed. For example, if you have hourly dry bulb temperature connected as the
second list, and relative humidity connected as the third list (both to the
annualHourlyData input), and you want to plot the data for the time period when
temperature is between 18C and 23C, and humidity is less than 80%, the conditional
statement should be written as 18<b<23 and c<80 (without quotation marks).
numOfDirections [Default]
A number of cardinal directions with which to divide up the data in wind rose. Values
must be greater than 4 since you can have no fewer than 4 cardinal directions.
Input a point here to change the location of the wind rose in the Rhino scene. The
default is set to the Rhino model origin (0,0,0).
maxFrequency [Optional]
Wind_Rose
129
Ladybug Primer
An optional number between 1 and 100 that represents the maximum percentage of
hours that the outer-most ring of the wind rose represents. By default, this value is set
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.
scale [Default]
Input a number here to change the scale of the wind rose. The default is set to 1.
runIt [Required]
Set this value to "True" to run the component and generate a wind rose in the Rhino
scene.
bakeIt [Optional]
Set this value to "True" to bake the wind rose into the Rhino scene.
Outputs
readMe!
...
calmRoseMesh
A mesh in the center of the wind rose representing the relative number of hours where
the wind speed is around 0 m/s.
windRoseMesh
A mesh representing the wind speed from different directions for all hours analyzed.
windRoseCrvs
A set of guide curves that mark the number of hours corresponding to the
windRoseMesh.
windRoseCenPts
Wind_Rose
130
Ladybug Primer
The center point(s) of wind rose(s). Use this to move the wind roses in relation to one
another using the grasshopper "move" component.
legend
A legend of the wind rose. Connect this output to a grasshopper "Geo" component in
legendBasePts
The legend base point(s), which can be used to move the legend in relation to the rose
title
The title for the wind rose. Connect this output to a grasshopper "Geo" component in
Check Hydra Example Files for Wind Rose
Wind_Rose
131
Ladybug Primer
Import Ground Temp
Use this component to visualise ground temperatures throughout the year at specific depths.
Please note that epw files usually only provide ground temperature data at depths 0.5
meters, 2 meters and 4 meters thus data has been interpolated for all other depths. In
particular this interpolation assumes that ground temperatures do not vary over the seasons
once the depth has reach 9 meters below the ground surface. -
Inputs
epwFile [Required]
Import_Ground_Temp
132
Ladybug Primer
An .epw file path on your system as a string

visualisedata_Season []
Set to true to visualise the ground temperature data as an average for every season
visualisedata_Month []
Set to true to visualise the ground temperature data for every month
Outputs
readMe!
...
groundtemp1st
In every epw file there are monthly ground temperatures at 3 different depths this is the
1st
groundtemp2nd
2nd
groundtemp3rd
3rd
profileCrvs
This output draws the curves of the temperature curves connect it to G of the
Grasshopper component Custom Preview
crvColors
This output draws the colours of the temperature curves connect it to S of the
Grasshopper component Custom Preview
graphAxes
This output draws the axes of the graph it doesn't need to be connected to anything
graphtext
Import_Ground_Temp
133
Ladybug Primer
This output draws the text of the graph it doesn't need to be connected to anything
Legend
Script variable Importgroundtemp
Check Hydra Example Files for Import Ground Temp
Import_Ground_Temp
134
Ladybug Primer
Component list:
Radiation_Analysis
Bounce_from_Surface
View_Analysis
View_From_Sun
view_Rose
ShadingDesigner
SolarEnvelope
SolarFan
Sunpath_Shading
Forward_Raytracing
SolarEnvelopeBasic
SolarFanBasic
3 | EnvironmentalAnalysis
135
Ladybug Primer
Radiation Analysis
This component allows you to calculate the radiation fallin on input _geometry using a sky
matrix from the selectSkyMxt component. This type of radiation sutdy is useful for building
surfaces such as windows, where you might be interested in solar heat gain, or solar panels,
where you might be interested in the energy that can be collected. This component is also
good for surfaces representing outdoor spaces (such as parks or seating areas) where
radiation could affect thermal comfort or vegetation growth. No reflection of sunlight is
included in the radiation analysis with this component and it should therefore be used neither
for interior daylight studies nor for complex geometries nor for surfaces with high a
reflectivity. For these situations where the relfection of light is important, the Honeybee
daylight components should be used instead of this one. -
Radiation_Analysis
136
Ladybug Primer
Inputs
north [Optional]
geometry [Required]
Geometry for which radiation analysis will be conducted. Geometry must be either a
Brep, a Mesh or a list of Breps or Meshes.
context [Optional]
Context geometry that could block sunlight to the test _geometry. Conext geometry
must be either a Brep, a Mesh or a list of Breps or Meshes.
gridSize [Default]
A number in Rhino model units that represents the average size of a grid cell for
radiation analysis on the test surface(s). This value should be smaller than the smallest
dimension of the test geometry for meaningful results. Note that, the smaller the grid
size, the higher the resolution of the analysis and the longer the calculation will take.
disFromBase [Required]
A number in Rhino model units that represents the offset distance of the test point grid
from the input test _geometry. Usually, the test point grid is offset by a small amount
from the test _geometry in order to ensure that radiation analysis is done for the correct
side of the test _geometry. If the resulting radiation mesh of this component is offset to
the wrong side of test _geometry, you should use the "Flip" Rhino command on the test
_geometry before inputting it to this component.
orientationStudyP [Optional]
Optional output from the "Orientation Study Parameter" component. You can use an
Orientation Study input here to answer questions like "What orientation of my building
will give me the highest or lowest radiation gain for my analysis period?" An Orientation
Study will automatically rotate your input _geometry around several times and record
the radiation results each time in order to output a list of values for totalRadiation and a
grafted data stream for radiationResult.
Radiation_Analysis
137
Ladybug Primer

parallel [Optional]
Set to "True" to run the radiation analysis using multiple CPUs. This can dramatically
decrease calculation time but can interfere with other intense computational processes
that might be running on your machine.
runIt [Required]
Set to "True" to run the component and perform radiation analysis on the input
_geometry.
bakeIt [Optional]
Set to True to bake the analysis results into the Rhino scene.
Use this input to change the working directory of the radiation analysis on your system.
Input here must be a valid file path location on your computer. The default is set to
"C:\Ladybug" and it is from this file location that radiation results are loaded into
grasshopper after the analysis is done.
projectName [Optional]
Use this input to change the project name of the files generated in the working directory.
Input here must be a string without special characters. If "bakeIt_" is set to "True", the
result will be baked into a layer with this project name.
Outputs
readMe!
...
contextMesh
An uncolored mesh representing the context_ geometry that was input to this
component. Connect this output to a "Mesh" grasshopper component to preview this
output seperately from the others of this component. Note that this mesh is generated
before the analysis is run, allowing you to be sure that the right geometry will be run
Radiation_Analysis
138
Ladybug Primer
through the analysis before running this component.

analysisMesh
An uncolored mesh representing the test _geometry that will be analyzed. Connect this
output to a "Mesh" grasshopper component to preview this output seperately from the
others of this component. Note that this mesh is generated before the analysis is run,
allowing you to be sure that the right geometry will be run through the analysis before
running this component.
testPts
The grid of test points on the test _geometry that will be used to perform the radiation
analysis. Note that these points are generated before the analysis is run, allowing you to
preview the resolution of the result before you run the component.
testVec
Vectors for each of the test points on the test _geometry, which indicate the direction for
which radiation analysis is performed. Hook this and the test points up to a Grasshopper
"Vector Display" component to see how analysis is performed on the test _geometry.
radiationResult
The amount of radiation in kWh/m2 falling on the input test _geometry at each of the
test points.
radiationMesh
A colored mesh of the test _geometry representing the radiation in kWh/m2 falling on
this input _geometry for the selected sky.
radiationLegend
A legend for the radiation study showing radiation values that correspond to the colors
of the radiationMesh. Connect this output to a grasshopper "Geo" component in order to
preview the legend separately in the Rhino scene.
legendBasePt
The legend base point, which can be used to move the legend in relation to the
radiation mesh with the grasshopper "move" component.
totalRadiation
The total radiation in kWh falling on the input test _geometry. This is computed through
Radiation_Analysis
139
Ladybug Primer
a mass addition of results at each of the test points in kWh/m2 multiplied by the area of
the face that the test point is representing.
intersectionMtx
A python list that includes the relation between each test point and all the sky patchs on
the sky dome. After running a basic radiation study, you can connect this output to the
Ladybug "Real Time Radiation Analysis" component to scroll through the radiation
falling on your test geometry on an hour-by-hour, day-by-day, or month-by-month basis
in real time.
Check Hydra Example Files for Radiation Analysis
Radiation_Analysis
140
Ladybug Primer
Sunlight Hours Analysis
This component calculates the number of hours of direct sunlight received by input geometry
using sun vectors from the sunPath component. This component can be used to evaluate
the number of hours of sunlight received by vegetation in a park or the hours where direct
sunlight might make a certain outdoor space comfortable or uncomfortable. It can also be
used for coarsely-gridded shadow studies in the Rhino scene . For finer and more detailed
shadow studies with simple input geometry, the Ladybug ShadowStudy component can be
used. For detailed shadow studies with complex geometry, the Honeybee daylight tools are
recommended. -
Inputs
141
Ladybug Primer
north [Optional]
geometry [Required]
Geometry for which sunlight hours analysis will be conducted. Geometry must be either
a Brep, a Mesh or a list of Breps or Meshes.
context [Optional]
Context geometry that could block sunlight to the test _geometry. Conext geometry
must be either a Brep, a Mesh or a list of Breps or Meshes.
gridSize [Default]
sunlight hours analysis on the test _geometry. This value should be smaller than the
smallest dimension of the test _geometry for meaningful results. Note that, the smaller
the grid size, the higher the resolution of the analysis and the longer the calculation will
take.
from the test _geometry in order to ensure that sunlight hours analysis is done for the
correct side of the test _geometry. If the resulting mesh of this component is offset to
the wrong side of test _geometry, you should use the "Flip" Rhino command on the test
_geometry before inputting it to this component.
Optional output from the "Orientation Study Parameter" component.
sunVectors [Required]
Sun vectors from the sunPath component, which will be used to determine the number
of hours of direct sunlight received by the test _geometry.
timeStep [Default]
The number of timesteps per hour used by the sunPath component that generated the
sun vectors. This number should be smaller than 60 and divisible by 60. The default is
142
Ladybug Primer
set to 1 such that one ssun vector is generated for each hour.
Optional output from the "Orientation Study Parameter" component. You can use an
Orientation Study input here to answer questions like "What orientation of my building
will give me the highest or lowest hours of direct sunlight for my analysis period?" An
Orientation Study will automatically rotate your input _geometry around several times
and record the sunlight hours results each time in order to output a list of values for
totalSunlightHours and a grafted data stream for sunlightHoursResult.
parallel [Optional]
Set to "True" to run the sunlight hours analysis using multiple CPUs. This can
dramatically decrease calculation time but can interfere with other intense
computational processes that might be running on your machine.
runIt [Required]
Set to "True" to run the component and perform sunlight hours analysis on the input
_geometry.
bakeIt [Optional]
Set to "True" to bake the analysis results into the Rhino scene.
Use this input to change the working directory of the sunlight hours analysis on your
system. Input here must be a valid file path location on your computer. The default is set
to "C:\Ladybug" and it is from this file location that sunlight hours results are loaded into
grasshopper after the analysis is done.
projectName [Optional]
Use this input to change the project name of the files generated in the working directory.
Input here must be a string without special characters. If "bakeIt_" is set to "True", the
result will be baked into a layer with this project name.
Outputs
readMe!
...
143
Ladybug Primer
contextMesh
analysisMesh
testPts
The grid of test points on the test _geometry that will be used to perform the sunlight
hours analysis. Note that these points are generated before the analysis is run, allowing
you to preview the resolution of the result before you run the component.
testVec
which sunlight hours analysis is performed. Hook this and the test points up to a
Grasshopper "Vector Display" component to see how analysis is performed on the test
_geometry.
sunlightHoursResult
The number of hours of direct sunlight received by each of the test points of the input
test _geometry. Note that is is the number of hours out of the total number of connected
_sunVectors.
sunlightHoursMesh
A colored mesh of the test _geometry representing the hours of direct sunlight received
by this input _geometry for the input sunVectors.
sunlightHoursLegend
A legend for the sunlight hours study showing the number of hours that correspond to
the colors of the sunlightHoursMesh. Connect this output to a grasshopper "Geo"
component in order to preview the legend separately in the Rhino scene.
144
Ladybug Primer
legendBasePt
The legend base point, which can be used to move the legend in relation to the sunlight
hours mesh with the grasshopper "move" component.
totalSunlightHours
The average number of hours of direct sunlight received by the test _geometry.
sunIsVisible
A grafted data stream for each test point with a "1" for each hour of the sunVectors that
the sun is visible and a "0" for each hour of the sunVectors when the sun is blocked.
Check Hydra Example Files for Sunlight Hours Analysis
145
Ladybug Primer
Bounce from Surface
Use this component to get a sense of how direct sunlight is reflected off of an initial
sourceSrf and subsequently to a set of context geometries by tracing sun rays forwards
through this geometry. Examples where this component might be useful include the
evaluation of the diffusion of light by a light shelf, or testing to see whether a parabolic
building geometry (like a Ghery building) might focus sunlight to dangerous levels at certain
times of the year. Note that this component assumes that all sun light is reflected off of these
geometries specularly (as if they were a mirror) and, for more detailed raytrace analysis, the
Honeybee daylight components should be used. -
Inputs
Bounce_from_Surface
146
Ladybug Primer
sourceSrfs [Required]
A brep or mesh representing a surface that you are interested in seeing direct sunlight
bounce off of. You can also put in lists of breps or meshes. These surfaces will be used
to generate the initial sun rays in a grid-like pattern. Note that, for curved surfaces,
smooth meshes of the geometry will be more accurate than inputing a Brep.
gridSizeOrPoints [Required]
A number in Rhino model units that represents the average size of a grid cell to
generate the points, or list of points itself. Note that, if you put in meshes for the input
above, the _gridSize number option of this input will not work as this component will use
the vertices of the mesh to generate the sun rays.
A sun vector from the sunPath component or a list of sun vectors to be forward raytraced.
context [Optional]
Breps or meshes of conext geometry, which will reflect the sun rays after they bounce
off of the _sourceSrfs. Note that, for curved surfaces, smooth meshes of the geometry
will be more accurate than inputing a Brep.
numOfBounce [Default]
An interger representing the number of ray bounces to trace the sun rays forward.
lastBounceLen [Default]
A number representing the length of the sun ray after the last bounce. If left empty, this
length will be the diagonal of the bounding box surrounding all input geometries.
firstBounceLen [Optional]
A number representing the length of the sun ray before the first bounce. If left empty,
this length will be the diagonal of the bounding box surrounding all input geometries.
Outputs
rays
The sun rays traced forward through the geometry.
bouncePts
Bounce_from_Surface
147
Ladybug Primer
The generated base points on the _sourceSrfs to which the sun rays will be directed.
The preview of this output is set to be hidden by default. Connect to a Grasshopper
"Point" component to visualize.
Check Hydra Example Files for Bounce from Surface
Bounce_from_Surface
148
Ladybug Primer
View Analysis
Use this component to evaluate the visibility of input _geometry from a set of key viewing
points. For example, this component can be used to evaluate the visibility of an 3D
architectural feature from a set of key viewing points along a nearby street or park where
people congregate. Another example would be evaluating the visibility of park vegetation
geometry from a set of key sun position points from the sunPath component. Yet another
example would be evaluating the "visibility" of an outdoor overhead radiative heater from a
set of key "viewing" points located over a human body standing beneath it. This component
outputs a percentage of viewpoints seen by the input _geometry. In the three examples
here, this would be the percentage of the 3D architectural feature seen from the street, the
View_Analysis
149
Ladybug Primer
percentage of sunlit hours received by the vegetation, or the percentage of the human body
warmed by the heater. This component will evaluate view from the test points objectively in
all directions. -
Inputs
geometry [Required]
Geometry for which visibility analysis will be conducted. Geometry must be either a
Brep, a Mesh, or a list of Breps or Meshes.
context [Optional]
Context geometry that could block the view from the _viewTypeOrPoints to the test
_geometry. Conext geometry must be either a Brep, a Mesh, or a list of Breps or
Meshes.
gridSize [Default]
visibility analysis on the test _geometry. This value should be smaller than the smallest
dimension of the test _geometry for meaningful results. Note that, the smaller the grid
size, the higher the resolution of the analysis and the longer the calculation will take.
from the test _geometry in order to ensure that visibility analysis is done for the correct
side of the test _geometry. If the resulting mesh of this component is offset to the wrong
side of test _geometry, you should use the 'Flip' Rhino command on the test _geometry
before inputting it to this component.
Optional output from the 'Orientation Study Parameter' component. You can use an
Orientation Study input here to answer questions like 'What orientation of my building
will give me the highest or lowest visibility from the street?' An Orientation Study will
automatically rotate your input _geometry around several times and record the visibility
results each time in order to output a list of values for averageView and a grafted data
stream for viewStudyResult.
viewTypeOrPoints [Required]
View_Analysis
150
Ladybug Primer
An integer representing the type of view analysis that you would like to conduct or a list
of points to which you would like to test the view. For integer options, choose from the
following options: 0 - Horizontal Radial - The percentage of the 360 horizontal view
band visible from each test point. Use this to study horizontal views from interior spaces
to the outdoors. 1 - Horizontal 60 Degree Cone of Vision - The percentage of the 360
horizontal view band bounded on top and bottom by a 30 degree offset from the
horizontal (derived from the human cone of vision). Use this to study views from interior
spaces to the outdoors. Note that this will discount the _geometry from the calculation
and only look at _context that blocks the scene. 2 - Spherical - The percentage of the
sphere surrounding each of the test points that is not blocked by context geometry. Note
that this will discount the _geometry from the calculation and only look at _context that
blocks the scene. 3 - Skyview - The percentage of the sky that is visible from the input
_geometry.
viewPtsWeights [Optional]
A list of numbers that align with the test points to assign weights of importance to the
several _viewTypeOrPoints that have been connected. Weighted values should be
between 0 and 1 and should be closer to 1 if a certain point is more important. The
default value for all points is 0, which means they all have an equal importance. This
input could be useful in cases such as the radiative heater example where points on the
human body with exposed skin could be weighted at a higher value.
parallel [Optional]
Set to 'True' to run the visibility analysis using multiple CPUs. This can dramatically
decrease calculation time but can interfere with other intense computational processes
that might be running on your machine.
runIt [Required]
Set to 'True' to run the component and perform visibility analysis of the input _geometry.
bakeIt [Optional]
Set to 'True' to bake the analysis results into the Rhino scene.
Outputs
readMe!
View_Analysis
151
Ladybug Primer
...
contextMesh
analysisMesh
testPts
The grid of test points on the test _geometry that will be used to perform the visibility
analysis. Note that these points are generated before the analysis is run, allowing you to
preview the resolution of the result before you run the component.
testVec
which visibility analysis is performed. Hook this and the test points up to a Grasshopper
"Vector Display" component to see how analysis is performed on the test _geometry.
viewVec
Script variable viewAnalysis
viewStudyResult
The percentage of _viewTypeOrPoints visible from each of the test points of the input
test _geometry.
viewStudyMesh
A colored mesh of the test _geometry representing the percentage of
_viewTypeOrPoints visible by each part of the input _geometry.
viewStudyLegend
View_Analysis
152
Ladybug Primer
A legend for the visibility analysis showing the percentage of visible points that
correspond to the colors of the viewStudyMesh. Connect this output to a grasshopper
"Geo" component in order to preview the legend separately in the Rhino scene.
legendBasePt
The legend base point, which can be used to move the legend in relation to the view
study mesh with the grasshopper "move" component.
averageView
The average percentage of the _viewTypeOrPoints seen by all of the test _geometry.
ptIsVisible
A grafted data stream for each _geometry test point with a "1" for each _viewPoint that
is visible by the test point and a "0" for each _viewPoint that is blocked.
Check Hydra Example Files for View Analysis
View_Analysis
153
Ladybug Primer
View From Sun
Use this component to open a new viewport in Rhino that shows the view from the sun. This
is useful for understanding what parts of Rhino geometry are shaded at a particular hour of
the day. -
Inputs
sunVector [Required]
A sun vector from which the the Rhino view will be generated. Use the Ladybug
sunPath component to generate sunVectors.
View_From_Sun
154
Ladybug Primer
cenPt [Default]
The target point of the camera for the Rhino view that will be generated. This point
should be close to Rhino geometry that you are interested in viewing from the sun. If no
point is progived, the Rhino origin will be used (0,0,0).
sunViewPt [Optional]
An optional point for the camera position (or sun position). Use this to move the camera
closer to the geometry you would like to view if the initial view is too far away..
width [Optional]
An optional interger that represents the width (in pixels) of the Rhino viewport that will
be generated.
height [Optional]
An optional interger that represents the height (in pixels) of the Rhino viewport that will
be generated.
dispMode [Optional]
An optional text input for the display mode of the Rhino viewport that will be generated.
For example: Wireframe, Shaded, Rendered, etc.
Outputs
readMe!
...
Check Hydra Example Files for View From Sun
View_From_Sun
155
Ladybug Primer
view Rose
Use this component to see the area visible from a given viewpoint across a 2D plane of
vision. The component will create a circular surface in this plane of vision that is interrupted
by context geometry to show the places that can be seen through this context geometry. -
Inputs
context [Required]
Breps or Meshes representing context geometry that can block the view around a given
viewPoint.
view_Rose
156
Ladybug Primer
plane [Default]
Test Plane
radius [Required]
A radius to make the view rose in Rhino model units. Note that, if the view rose is not
extending past the _context geometry, you should increase this value.
Outputs
readMe!
...
viewRose
A surface representing the visible area from the viewpoint past the _context geometry.
blocked
A set of curves representing the views blocked by the _context geometry from the
viewpoint .
visibleAngle
The total angle of visibility from the viewpoint in the plane of visibility.
Check Hydra Example Files for view Rose
view_Rose
157
Ladybug Primer
Comfort Shade Benefit Evaluator
This is a component for visualizing the desirability of shade in terms of comfort temperature
by using solar vectors, a series of hourly temperatures (usually outdoor temperatures), and
an assumed balance temperature. The balance temperature represents the median
temperture that people find comfortable, which can vary from climate to climate but is usually
somewhere around 20C. Solar vectors for hours when the temperature is above the balance
point contribute positively to shade desirability while solar vectors for hours when the
temperature is below the balance point contribute negatively. The component outputs a
colored mesh of the shade illustrating the net effect of shading each mesh face. A higher
saturation of blue indicates that shading the cell is very desirable. A higher saturation of red
indicates that shading the cell is harmful (blocking more winter sun than summer sun).
158
Ladybug Primer
Desaturated cells indicate that shading the cell will have relatively little effect on outdoor
comfort or building performance. The units for shade desirability are net temperture degreedays helped per unit area of shade if the test cell is blue. If the test cell is red, the units are
net heating degree-days harmed per unit area of shade. The method used by this
component is based off of the Shaderade method developed by Christoph Reinhart, Jon
Sargent, Jeffrey Niemasz. This component uses Shaderade's method for evaluating shade
and window geometry in terms of solar vectors but substitutes Shaderade's energy
simulation for an evaluation of heating and temperture degree-days about a balance
temperature. A special thanks goes to them and their research. A paper detailing the
Shaderade method is available at:
http://www.gsd.harvard.edu/research/gsdsquare/Publications/Shaderade_BS2011.pdf The
heating/temperture degree-day calculation used here works by first getting the percentage of
sun blocked by the test cell for each hour of the year using the Shaderade method. Next,
this percentage for each hour is multiplied by the temperature above or below the balance
point for each hour to get a "degree-hour" for each hour of the year for a cell. Then, all the
temperture-degree hours (above the balance point) and heating degree-hours (below the
balance point) are summed to give the total heating or temperture degree-hours helped or
harmed respectively. This number is divided by 24 hours of a day to give degree-days.
These degree days are normalized by the area of the cell to make the metric consistent
across cells of different area. Lastly, the negative heating degree-days are added to the
positive temperture degree-days to give a net effect for the cell. -
Inputs
location [Required]
The location output from the importEPW or constructLocation component. This is
essentially a list of text summarizing a location on the earth.
temperatures [Required]
A stream of 8760 temperature values (including a header) representing the temperature
at each hour of the year that will be used to evaluate shade benefit. This can be the
dryBulbTemperature from the 'Import EPW' component, the
univeralThermalClimateIndex (UTCI) output from the 'Outdoor Comfort Calculator'
component, or the standardEffectiveTemperature (SET) output from the 'PMV Comfort
Calculator' component. If you are using this component to evaluate shade for a passive
building with no heating/cooling, this input can also be the indoor temperature of the
zone to be shaded.
balanceTemperature [Optional]
159
Ladybug Primer
An estimated balance temperature representing median temperture that people find

comfortable, which can vary from climate to climate. The default is set to 17.5C, which
is the median outdoor comfort temperature (UTCI) that defines the conditions of no
thermal stress (9 < UTCI <26).
temperatureOffest [Optional]
An number represeting the offset from the balanceTemperature_ in degrees Celcius at
which point the shade importance begins to have an effect. The default is set to 8.5 C,
which is the range of outdoor comfort temperature (UTCI) that defines the conditions of
no thermal stress (9 < UTCI <26).
testShades [Required]
A Brep representing the shade to be evaluated for its benefit.
testRegion [Required]
A brep representing an outdoor area for which shading is being considered or the
window of a building that would be affected by the shade. Note that only breps with a
single surface are supported now and volumetric breps will be included at a later point.
gridSize [Optional]
The length of each of the shade's test cells in model units. Please note that, as this
value gets lower, simulation times will increase exponentially even though this will give a
higher resolution of shade benefit.
context [Optional]
Script variable ShadeBenefit
north [Optional]
skyResolution [Optional]
An interger equal to 0 or above to set the number of times that the tergenza sky patches
are split. A higher number will ensure a greater accuracy but will take longer. At a sky
resolution of 4, each hour's temperature is essentially matched with an individual sun
vector for that hour. At a resolution of 5, a sun vector is produced for every half-hour, at
6, every quarter hour, and so on. The default is set to 4, which should be high enough of
160
Ladybug Primer
a resolution to produce a meaningful reault in all cases.

delNonIntersect [Optional]
Set to "True" to delete mesh cells with no intersection with sun vectors. Mesh cells
where shading will have little effect because an equal amount of warm and cool
temperature vectors will still be left in white.
Legend parameters that can be used to re-color the shade, change the high and low
boundary, or sync multiple evaluated shades with the same colors and legend
parameters.
parallel [Optional]
Set to "True" to run the simulation with multiple cores. This can increase the speed of
the calculation substantially and is recommended if you are not running other big or
important processes.
runIt [Required]
Set to 'True' to run the simulation.
Outputs
readMe!
...
sunVectors
The sun vectors that were used to evaluate the shade (note that these will increase as
the sky desnity increases).
regionTestPts
Points across the test region surface from which sun vectors will be projected
shadeMesh
A colored mesh of the _testShades showing where shading is helpful (in satuated blue),
harmful (in saturated red), or does not make much of a difference (white or desaturated
colors).
legend
161
Ladybug Primer
Legend showing the numeric values of degree-days that correspond to the colors in the
shade mesh.
legendBasePoint
Script variable Shade Benefit
shadeHelpfulness
The cumulative temperture degree-days/square Rhino model unit helped by shading the
given cell. (C-day/m2)*if your model units are meters.
shadeHarmfulness
The cumulative heating degree-days/square Rhino model unit harmed by shading the
given cell. (C-day/m2)*if your model units are meters. Note that these values are all
negative due to the fact that the shade is harmful.
shadeNetEffect
The sum of the helpfulness and harmfulness for each cell. This will be negative if
shading the cell has a net harmful effect and positive if the shade has a net helpful
effect.
Check Hydra Example Files for Comfort Shade Benefit Evaluator
162
Ladybug Primer
ShadingDesigner
Use this component to generate shading breps for any glazed surface or list of glazed
surfaces. The component supports two methods for shading generation. The first is a simple
depth method, which will generate an overhang of the speficied depth (or multiple overhangs
if the _numOfShds is increased). The second method is to input a set of solar vectors from
the Sunpath component that should be blocked by the shade. -
Inputs
glzSrf [Required]
ShadingDesigner
163
Ladybug Primer
A Surface or Brep representing a window to be used for shading design. This can also
be a list of Surfaces of Breps.
depthOrVector [Required]
A number representing the depth of the shade to be generated or a sun vector to be
shaded from the glzSrf. You can also input lists of depths, which will assign different
depths based on cardinal direction. For example, inputing 4 values for depths will assign
each value of the list as follows: item 0 = north depth, item 1 = west depth, item 2 =
south depth, item 3 = east depth. Lists of vectors to be shaded can also be input and
shades can be joined together with the mergeVectors input.
numOfShds [Required]
The number of shades to generated for each glazed surface.
distBetween [Required]
An alternate option to _numOfShds where the input here is the distance in Rhino units
between each shade.
runIt [Required]
Set to 'True' to run the component and generate shades.
optionalShdSrf [Optional]
An optional shade surface representing a 2D area under consideration for shading. This
input can only be used with the sun vector method.
optionalPlanes [Optional]
An optional plane (or list of planes) representing a 2D area under consideration for
shading. This input can only be used with the sun vector method.
mergeVectors [Optional]
Set to 'True' to merge all the shades generated from a list of sun vectors into a single
shade. This input can only be used with the sun vector method.
horOrVertical [Default]
Set to 'True' to generate horizontal shades or 'False' to generate vertical shades. You
can also input lists of horOrVertical input, which will assign different orientations based
on cardinal direction.
ShadingDesigner
164
Ladybug Primer
shdAngle [Default]
A number between -90 and 90 that represents an angle in degrees to rotate the shades.
The default is set to '0' for no rotation. If you have vertical shades, use this to rotate
them towards the South by a certain value in degrees. If applied to windows facing East
or West, tilting the shades like this will let in more winter sun than summer sun. If you
have horizontal shades, use this input to angle shades downward. You can also put in
lists of angles to assign different shade angles to different cardinal directions.
north [Optional]
Input a vector to be used as a true North direction or a number between 0 and 360 that
represents the degrees off from the y-axis to make North. The default North direction is
set to the Y-axis (0 degrees).
Outputs
readMe!
...
shadingSrfs
Shading surfaces that were generated based on the inputs.
Check Hydra Example Files for ShadingDesigner
ShadingDesigner
165
Ladybug Primer
SolarEnvelope
Use this component to generate a solar envelope for a given test surface, set of solar
vectors, and context geometry that you want to ensure solar access to. Solar envelopes are
typically used to illustrate the volume that can be built within in order to ensure that a new
development does not shade the surrounding properties for a given set of sun vectors. -
Inputs
baseSrf [Required]
A surface representing the area for which you want to create the solar envelope.
SolarEnvelope
166
Ladybug Primer
obstacleCrvs [Required]
List of curves indicating the top borders of our surroundings that are taken into account
in calculating the solar collection.
Sun vectors representing hours of the year when sun should be accessible to the
properties surrounding the baseSrf. sunVectors can be generated using the Ladybug
sunPath component.
gridSize [Optional]
A numeric value inidcating the gird size of the analysis in Rhino model units. The
smaller the grid size - the more test points( more accurate but slower). Default value is
automatically set based on the size of the input _baseSrf.
maxHeight [Optional]
If there are no obstrucsions this would be the lowest value for the solar collection points.
Default value set to 20 meters below the average baseSrf height.
envelopeToRun [Optional]
Set to 'True' if you would like the component to calculate a solar rights boundary and
'False' if you would like a solar collection boundary. The default is set to solar envelope.
numOfCPUs [Default]
Number of CPUs to be used for the simulation. Default value would be 1
runIt [Required]
Set to 'True' to run the component and generate solar collection points.
Outputs
readMe!
Log of the component.
envelopePts
A list of 3d points representing the heights to which the solar collection reaches. Plug
into a native GH 'Delunay Mesh' component to visualize the full solar collection
boundary.
SolarEnvelope
167
Ladybug Primer
envelopeBrep
The closed volume in which you can build above which the building will have direct solar
access to the input sunVectors.
Check Hydra Example Files for SolarEnvelope
SolarEnvelope
168
Ladybug Primer
SolarFan
Use this component to generate a solar fan for a given test surface and set of solar vectors.
Solar fans essentially illustrate the volume that should be clear of shading in order to provide
solar access to a test surface for a given set of sun vectors. Solar fans are typically used to
ensure solar access for park vegetation in the midst of large developments constructed
around it. It can be also used to ensure solar access for windows that might want to use the
sun for heating for ceratin hours of the year. -
Inputs
baseSrf [Required]
SolarFan
169
Ladybug Primer
A surface representing a piece of land (such as a park) or a window for which solar
access is desired.
Sun vectors representing hours of the year when sun should be accessible to the
baseSrf. sunVectors can be generated using the Ladybug sunPath component.
size [Default]
Input a number here to change how far the solar fan extends from the _baseSrf. The
default is set to 1, which will produce a solar fan that is half as tall as the longest side of
the _baseSrf. Note that increasing the height too high can cause the fan to break up into
multiple fans due to the resolution of the solar vectors.
runIt [Required]
Set to "True" to run the analysis and generate a solar fan. Note that, for more than 500
sunVectors, calculation times can take more than a half-minute.
Outputs
readMe!
...
solarFan
Brep representing a solar fan that should be clear of shading in order to ensure solar
access to the _baseSrf for the given _sunVectors.
Check Hydra Example Files for SolarFan
SolarFan
170
Ladybug Primer
DC to AC derate factor
Use this component to calculate overall DC to AC derate factor for Photovoltaics Surface's
"DCtoACderateFactor_" input. Overall DC to AC derate factor corresponds to various
locations and instances in a PV system where power is lost from DC system nameplate to
AC power. - Component first calculates PVWatts v5 Total losses, then converts them to
PVWatts v1 overall DC to AC derate factor. Based on PVWatts v5 Manual:
http://www.nrel.gov/docs/fy14osti/62641.pdf - If nothing supplied to the inputs, default value
of 0.85 will be used. -
Inputs
171
Ladybug Primer
annualShading [Optional]
Losses due to buildings, structures, trees, mountains or other objects that prevent solar
radiation from reaching the cells. Input range: 0 to 100(%), 0 being unshaded, and 100
being totally shaded PV module. - If not supplied default value of 0(%) will be used.
age [Optional]
Losses over time due to weathering of the PV modules. The loss in performance is
typically 1% per year. Example: for the 20th year of operation, an age loss of 19% would
be appropriate. Input range: 0 (new module) to 100%(theoretically: 101 year old
module) - If not supplied default value of 0(%) will be used.
snow [Optional]
Losses due to snow covering the array. The default value is zero, assuming either that
there is never snow on the array, or that the array is kept clear of snow. Input range: 0
(there is never snow on the array, or the array is kept clear of snow) to 100%(an array is
theoretically always covered with snow) - If not supplied default value of 0(%) will be
used.
wiring [Optional]
Resistive losses in the DC and AC wires connecting modules, inverters, and other parts
of the system. Input range: 0 to 100(%) - If not supplied default value of 2(%) will be
used.
soiling [Optional]
Losses due to dust, dirt, leaves, other wildlife droppings, snow, and other foreign matter
on the surface of the PV module that prevent solar radiation from reaching the cells.
Soiling is location- and weather-dependent. There are greater soiling losses in hightraffic, high-pollution areas with infrequent rain. Input range: 0 to 100(%) - If not supplied
default value of 2(%) will be used.
mismatch [Optional]
Electrical losses due to slight differences caused by manufacturing imperfections
between modules in the array that cause the modules to have slightly different currentvoltage characteristics. Input range: 0 to 100(%) - If not supplied default value of 2(%)
will be used.
availability [Optional]
Losses due to scheduled and unscheduled system shutdown for maintenance, grid
172
Ladybug Primer
outages, and other operational factors. Input range: 0 to 100% - If not supplied default
value of 3(%) will be used.
connections [Optional]
Resistive losses in electrical connectors in the system. Input range 0 to 100(%) - If not
supplied default value of 0.5(%) will be used.
nameplateRating [Optional]
Losses due to accuracy of the manufacturer's nameplate rating. Field measurements of
the electrical characteristics of photovoltaic modules in the array may show that they
differ from their nameplate rating. Example: a nameplate rating loss of 5% indicates that
testing yielded power measurements at STC that were 5% less than the manufacturer's
nameplate rating. Input range 0 to 100(%) - If not supplied default value of 1(%) will be
used.
lightInducedDegradation [Optional]
Effect of the reduction in the array's power during the first few months of its operation
caused by light-induced degradation of photovoltaic cells. Input range 0 to 100(%) - If
not supplied default value of 1.5(%) will be used.
Outputs
readMe!
...
totalLosses
PVWatts v5 representation of DCtoACderateFactor factor. In percent (%).
DCtoACderateFactor
Factor which accounts for various locations and instances in a PV system where power
is lost from DC system nameplate to AC power. Unitless.
Check Hydra Example Files for DC to AC derate factor
173
Ladybug Primer
Photovoltaics Performance Metrics
Use this component to calculate various Photovoltaics performance metrics -
Inputs
PVsurface [Required]
Input planar Grasshopper/Rhino Surface (not a polysurface) on which the PV modules
will be applied. If you have a polysurface, explode it (using "Deconstruct Brep"
component) and then feed its Faces(F) output to _PVsurface. Surface normal should be
faced towards the sun.
174
Ladybug Primer
Or create the Surface based on initial PV system size by using "PV SWH system
size" component.
PVsurfacePercent [Optional]
The percentage of surface which will be used for PV modules (range 0-100). - Some
countries and states, have local codes which limit the portion of the roof, which can be
covered by crystalline silicon modules. For example, this may include having
setbacks(distances) of approximatelly 90cm from side and top edges of a roof, as a fire
safety regulation. - If not supplied, default value of 100 (all surface area will be covered
in PV modules) is used.
PVmoduleSettings [Optional]
Script variable PhotovoltaicsPerformanceMetrics
ACenergyPerHour [Required]
Import "ACenergyPerYear" output data from "Photovoltaics surface" component. In
kWh.
totalRadiationPerHour [Required]
Import "totalRadiationPerHour" output data from "Photovoltaics surface" component. In
kWh/m2.
cellTemperaturePerHour [Required]
Import "cellTemperaturePerHour" output data from "Photovoltaics surface" component.
In C.
ACenergyDemandPerHour [Optional]
Required electrical energy used for any kind of load: heating, cooling, electric lights,
solar water heating circulation pump etc. For example, any of the Honeybee's "Read EP
Result" outputs can be inputted in here. Either separately or summed. - If nothing
inputted, this input will be neglected (there is no required electrical energy). In kWh.
energyCostPerKWh [Optional]
The cost of one kilowatt hour in any currency unit (dollar, euro, yuan...) - If not supplied,
0.15 $/kWh will be used as default value.
embodiedEnergyPerM2 [Optional]
Energy necessary for an entire product life-cycle of PV module per square meter. In
175
Ladybug Primer
MJ/m2 (megajoules per square meter). - If not supplied default value of 4410 (MJ/m2)
will be used.
embodiedCO2PerM2 [Optional]
Carbon emissions produced during PV module's life-cycle per square meter.. In kg
CO2/m2 (kilogram of CO2 per square meter). - If not supplied default value of 225 (kg
CO2/m2) will be used.
lifetime [Optional]
Life expectancy of a PV module. In years. - If not supplied default value of 30 (years)
will be used.
gridEfficiency [Optional]
An average primary energy to electricity conversion efficiency. - If not supplied default
value of 29 (%) will be used.
optimal [Optional]
Set to "True" to calculate optimal PVsurface area. An optimal PVsurface area will cover
100% of the of the annual electricity load ("ACenergyDemandPerHour_").
runIt [Required]
...
Outputs
readMe!
...
optimalSystemSize
Optimal PV system size (optimal total size of the PV array) for a given PVsurface's tilt,
array and "ACenergyDemandPerHour". Minimum system size is 0.01 kW. Input it to
"systemSize" input of "PV SWH system size" component to see how much area it would
require. - To calculate it, set the "optimal_" input to "True". - In thermal kiloWatts (kWt).
CUFperYear
Capacity Utilization Factor (or Capacity Factor or sometimes evan called Plant Load
Factor (PLF)) - ratio of the annual AC power output and maximum possible output under
ideal conditions if the sun shone throughout the day and throughout the year. It is
176
Ladybug Primer
sometimes used by investors or developers for Financial and Maintenance analysis of

the PV systems, instead of "basicPRperYear". - In percent (%).
basicPRperYear
Basic Performance Ratio - ratio of the actual and theoretically possible annual energy
output. It is worldwide accepted standard metric for measuring the performance of the
PV system, therefor it is used for Maintenance analysis of PV systems. Used for
Maintenance analysis of PV systems. - basicPR is more precise than upper "CUF" and
should be used instead of it, unless "CUF" is specifically required. - In percent(%).
temperatureCorrectedPRperMonth
Temperature corrected Performance Ratio - ratio of the actual and theoretically possible
energy output for each month during a year, corrected for PV module's Cell
temperature. Mid-day hours (solarRadiation > 0.6 kWh/m2) only taken into account.
Used for Maintenance analysis of PV systems. - In percent(%).
temperatureCorrectedPRperYear
Temperature corrected Performance Ratio - ratio of the actual and theoretically possible
annual energy output, corrected for PV module's Cell temperature. Mid-day hours
(solarRadiation > 0.6 kWh/m2) only taken into account. Used for Maintenance analysis
of PV systems. - It is more precise than upper "basicPR" and should be used instead of
it, unless "basicPR" is specifically required. - In percent(%).
energyOffsetPerMonth
Percentage of the electricity demand covered by Photovoltaics system for each month
during a year. - It is used for Financial and Maintenance analysis of the PV system. - In
percent(%).
energyOffsetPerYear
Percentage of the total annual electricity demand covered by Photovoltaics system for a
whole year. - It is used for Financial and Maintenance analysis of the PV system. - In
percent(%).
energyValue
Total Energy value for the whole year in currency unit (dollars, euros, yuans...) - It is
used for Financial analysis of the PV system.
Yield
177
Ladybug Primer
Ratio of annual AC power output and nameplate DC power rating. It is used for
Financial analysis of the PV systems. - In hours (h).
EROI
Energy Return On Investment - a comparison of the generated electricity to the amount
of primary energy used throughout the PV module's product life-cycle. - It is used for
Financial analysis of the PV system. - Unitless.
embodiedEnergy
Total energy necessary for an entire product life-cycle of PV modules. - It used for the
Life Cycle analysis of the PV system. - In GJ (gigajoules).
embodiedCO2
Total carbon emissions produced during PV module's life-cycle. - It used for the Life
Cycle analysis of the PV system. - In tCO2 (tons of CO2).
CO2emissionRate
An index which shows how effective a PV system is in terms of global warming. It is
used in comparison with other fuels and technologies (Hydroelectricity(15), Wind(21),
Nuclear(60), Geothermal power(91), Natural gas(577), Oil(893), Coal(955) ...) - It is part
of the Life Cycle analysis of the PV system. - In gCO2/kWh.
EPBT
Energy PayBack Time - time it takes for PV modules to produce all the energy used
through-out its product life-cycle. After that period, they start producing zero-emissions
energy. - It is used for Life Cycle analysis of the PV system. - In years.
Check Hydra Example Files for Photovoltaics Performance Metrics
178
Ladybug Primer
Photovoltaics Surface
Use this component to calculate amount of electrical energy that can be produced by a
surface if a certain percentage of it is covered with Photovoltaics. Component based on
NREL PVWatts v1 fixed tilt calculator for crystalline silicon (c-Si) photovoltaics. - Sources:
http://www.nrel.gov/docs/fy14osti/60272.pdf https://pvpmc.sandia.gov -
Inputs
epwFile [Required]
Input .epw file path by using the "File Path" parameter, or Ladybug's "Open EPW And
179
Ladybug Primer
STAT Weather Files" component.

PVsurface [Required]
Input planar Grasshopper/Rhino Surface (not a polysurface) on which the PV modules
will be applied. If you have a polysurface, explode it (using "Deconstruct Brep"
component) and then feed its Faces(F) output to _PVsurface. Surface normal should be
faced towards the sun.
Or create the Surface based on initial PV system size by using "PV SWH system
size" component.
PVsurfacePercent [Optional]
The percentage of surface which will be used for PV modules (range 0-100). - Some
countries and states, have local codes which limit the portion of the roof, which can be
covered by crystalline silicon modules. For example, this may include having
setbacks(distances) of approximatelly 90cm from side and top edges of a roof, as a fire
safety regulation. - If not supplied, default value of 100 (all surface area will be covered
in PV modules) is used. - In percent (%).
DCtoACderateFactor [Optional]
Factor which accounts for various locations and instances in a PV system where power
is lost from DC system nameplate to AC power. It ranges from 0 to 1. It can be
calculated with Ladybug's "DC to AC derate factor" component. - If not supplied, default
value of 0.85 will be used.
PVmoduleSettings [Optional]
A list of PV module settings. Use the "Photovoltaics module" component to generate
them. - If not supplied, the following PV module settings will be used by default:
moduleType: Close (flush) roof mount
moduleEfficiency: 15 %
temperatureCoefficient: -0.5 %/C
moduleActiveAreaPercent: 90 %
north [Optional]
Input a vector to be used as a true North direction, or a number between 0 and 360 that
represents the clockwise degrees off from the Y-axis. - If not supplied, default North
direction will be set to the Y-axis (0 degrees).
albedo [Optional]
180
Ladybug Primer
A list of 8767 (with header) or 8760 (without the header) albedo values for each hour
during a year. Albedo (or Reflection coefficient) is an average ratio of the global incident
solar radiation reflected from the area surrounding the PV surface. It ranges from 0 to 1.
- It depends on the time of the year/day, surface type, temperature, vegetation,
presence of water, ice and snow etc. - If no list supplied, default value of 0.20 will be
used, corrected(increased) for the presence of snow (if any). - Unitless.
An optional list of hourly data from Ladybug's "Import epw" component (e.g.
dryBulbTemperature), which will be used for "conditionalStatement_".
This input allows users to calculate the Photovoltaics surface component results only for
those annualHourlyData values which fit specific conditions or criteria. To use this input
correctly, hourly data, such as dryBulbTemperature or windSpeed, must be plugged into
the "annualHourlyData" input. The conditional statement input here should be a valid
condition statement in Python, such as "a>25" or "b<3" (without="" the="" quotation=""
marks).="" conditionalStatement_="" accepts="" "and"="" and="" "or"="" operators.=""
To="" visualize="" hourly="" data,="" English="" letters="" should="" be="" used="" as=""
variables,="" each="" letter="" alphabetically="" corresponds="" to="" of="" lists="" (in=""
their="" respective="" order):="" "a"="" always="" represents="" 1st="" list,="" "b"=""
2nd="" etc.="" -="" For="" example,="" if="" you="" have="" an=""
dryBulbTemperature="" connected="" first="" windSpeed="" second="" list="" (both=""
annualHourlyData_="" input),="" want="" plot="" data="" for="" time="" period=""
when="" temperature="" is="" between="" 18C="" 23C,="" larger="" than="" 3m=""
s,="" written="" "183" (without the quotation marks).
runIt [Required]
...
Outputs
readMe!
...
ACenergyPerHour
AC power output for each hour during a year. - In kWh.
ACenergyPerYear
181
Ladybug Primer
Total AC power output for a whole year. - In kWh.

averageDailyACenergyPerYear
An average AC power output per day for a whole year. - In kWh/day.
DCenergyPerHour
DC power output of the PV array for each hour during a year. - In kWh.
totalRadiationPerHour
Total Incident POA (Plane of array) irradiance for each hour during a year. - In kWh/m2.
moduleTemperaturePerHour
Module's back surface temperature for each hour during year. - In C.
cellTemperaturePerHour
Cell temperature for each hour during year. - In C.
PVsurfaceTiltAngle
The angle from horizontal of the inclination of the PVsurface. Example: 0 = horizontal,
90 = vertical. It ranges from 0-180. - In degrees.
PVsurfaceAzimuthAngle
The orientation angle (clockwise from the true north) of the PVsurface normal vector. It
ranges from 0-360. - In degrees.
systemSize
DC rating of the PV system. - In kW.
Check Hydra Example Files for Photovoltaics Surface
182
Ladybug Primer
Sunpath Shading
This component calculates the shading of:

Photovoltaic modules
Solar Water Heating collectors
any other purpose (shading of points) - Use "annualShading", "Sep21toMar21Shading"
and "Mar21toSep21Shading" outputs for Photovoltaic modules shading. Use
"beamIndexPerHour" and "skyViewFactor" outputs for Solar Water Heating collectors
shading, or any other purpose. - "annualShading" output is based on "Using sun path
charts to estimate the effects of shading on PV arrays", University of Oregon, Frank
Vignola:
Sunpath_Shading
183
Ladybug Primer
http://solardat.uoregon.edu/download/Papers/UsingSunPathChartstoEstimatetheEffecto
fShadingonPVArrays.pdf -
Inputs
epwFile [Required]
analysisGeometry [Required]
Input surface(a) or point(b) (a single one or more of them). - a) Input planar Surface (not
polysurface) on which the PV modules/Solar water heating collectors will be applied. If
you have a polysurface, explode it (using "Deconstruct Brep" component) and then feed
its Faces(F) output to analysisGeometry. Surface normal should be faced towards the
sun. - b) You can also supply point(s) and its shading will be calculated. - Geometry
inputted to "_analysisGeometry", will be accounted for self-shading, so there is no need
to input it to the "context" also.
context [Optional]
Buildings, structures, mountains and other permanent obstructions. - If you supplied
surface(s) to the "analysisGeometry", input them into the "context" too, to account for
self-shading. If you inputted point(s) into the "analysisGeometry", there's no need to
input them into the "context". - Input polysurfaces, surfaces, or meshes.
coniferousTrees [Optional]
This input allows for partial shading from coniferous(evergreen) context trees. - Input
polysurfaces, surfaces, or meshes.
deciduousTrees [Optional]
This input allows for partial shading during in-leaf and leaf-less periods from deciduous
context trees. In-leaf being a period from 21st March to 21st September in the northern
hemisphere, and from 21st September to 21st March in the southern hemisphere. Leafless being a period from 21st September to 21st March in the northern hemisphere, and
from 21st March to 21st September in the in the southern hemisphere. - Input
polysurfaces, surfaces, or meshes.
coniferousAllyearIndex [Optional]
All year round transmission index for coniferous(evergreen) context trees. It ranges from
Sunpath_Shading
184
Ladybug Primer
0 to 1.0. 0 represents deciduous trees which do not allow solar radiation to pass through
them (100% shading). 1 represents all solar radiation passing through deciduous trees,
like the trees do not exist (0% shading). - If not supplied default value of 0.30 (equals
70% shading) will be used. - Unitless.
deciduousInleafIndex [Optional]
Deciduous context trees transmission index for in-leaf period. In-leaf being a period
from 21st March to 21st September in the northern hemisphere, and from 21st
September to 21st March in the southern hemisphere. It ranges from 0 to 1.0. 0
represents deciduous trees which do not allow solar radiation to pass through them
(100% shading). 1 represents all solar radiation passing through deciduous trees, like
the trees do not exist (0% shading). - If not supplied default value of 0.23 (equals 77%
shading) will be used. - Unitless.
deciduousLeaflessIndex [Optional]
Deciduous context trees transmission index for leaf-less period. Leaf-less being a
period from 21st September to 21st March in the northern hemisphere, and from 21st
March to 21st September in the in the southern hemisphere. It ranges from 0 to 1.0. 0
represents deciduous trees which do not allow solar radiation to pass through them
(100% shading). 1 represents all solar radiation passing through deciduous trees, like
the trees do not exist (0% shading). - If not supplied default value of 0.64 (equals 36%
shading) will be used. - Unitless.
leaflessPeriod [Optional]
Define the leafless period for deciduous trees using Ladybug's "Analysis Period"
component. IMPORTANT! This input affects only the skyViewFactor,
beamIndexPerHour, shadedSolarRadiationPerHour output. Due to limitations of the
used sunpath diagram, it does not affect the Sep21toMar21Shading,
Mar21toSep21Shading, annualShading outputs, where default leafless periods (see the
line bellow) will always be used. - If not supplied the following default periods will be
used: from 21st September to 21st March in the northern hemisphere, and from 21st
March to 21st September in the in the southern hemisphere.
ACenergyPerHour [Optional]
This input is necessaty only if you are calculating the shading of the PV modules. If that
is so, input the "ACenergyPerHour" output data from "Photovoltaics surface"
component. - If you are calculating shading analysis for "Solar water heating surface"
component (instead of "Photovoltaics surface" component), leave this input empty. - If
you are calculating shading analysis for any other purpose (of point(s) for example)
Sunpath_Shading
185
Ladybug Primer
leave this input empty too.

north [Optional]
albedo [Optional]
solar radiation reflected from the area surrounding the _analysisGeometry. It ranges
from 0 to 1. - It depends on the time of the year/day, surface type, temperature,
vegetation, presence of water, ice and snow etc. - If no list supplied, default value of
0.20 will be used, corrected(increased) for the presence of snow (if any). - Unitless.
outputGeometryIndex [Optional]
An index of the surface inputted into "_analysisGeometry" if "_analysisGeometry" would
be flattened.. It determines the surface for which output geometry will be generated. - If
not supplied, geometry for the first surface (index: 0) will be generated as a default.
scale [Optional]
Scale of the overall geometry (sunPath curves, sunWindow mesh). Use the scale
number which enables encompassing all of your context, coniferousTrees,
deciduousTrees_ objects. - If not supplied, default value of 1 will be used.
hoursPositionScale [Optional]
Scale factor for positioning of solar time hour points (that's "hoursPositions" output). - If
not supplied, default value of 1 will be used.
precision [Optional]
Overall shading precision. Ranges from 1-100. It represents the square root number of
shading analysis points per sun window quadrant. Example - precision of 20 would be
400 shading analysis points per single sun window quadrant. CAUTION!!! Higher
precision numbers (50 >) require stronger performance PCs. If your "context" contains
only straight shape buildings/objects, and you have just a couple of trees supplied to the
"coniferousTrees" and "deciduousTrees_" inputs, the precision of < 50 will be just fine. If not supplied, default value of 2 will be used.
Sunpath_Shading
186
Ladybug Primer
Optional legend parameters from the Ladybug "Legend Parameters" component.

bakeIt [Optional]
Set to "True" to bake the Sunpath shading results into the Rhino scene. - If not supplied
default value "False" will be used.
runIt [Required]
...
Outputs
readMe!
...
skyViewFactor
Continuous Sky View Factor - portion of the visible sky (dome). It defines the shading of
the parts of diffuse irradiance. It ranges from 0 to 1. 0 means that the sky dome is
competely obstructed by obstacles and all incoming diffuse sky irradiance is blocked
(100% shading). 1 means that sky dome is competely free of obstacles (0% shading). This output is similar to "skyView" output of Ladybug's "Shading Mask" component.
Unlike "skyView" it takes into account transparency of trees. But it does not visually
present the shading, which is what "Shading Mask" component does. - Use it as an
input for Ladybug "Solar Water Heating System" or "Solar Water Heating System
Detailed" component's "skyViewFactor_" input to account for diffuse irradiance shading
of SWHsurface. - Unitless.
beamIndexPerHour
Transmission index of beam (direct) irradiance for each hour during a year. It ranges
from 0-1. Transmission index of 0 means 100% shading. Transmission index of 1
means 0% shading. It is calculated for each analysisGeometry vertex and then
averaged. - Use it as an input for Ladybug "Solar Water Heating System" or "Solar
Water Heating System Detailed" component's "beamIndexPerHour_" input to account
for diffuse direct beam shading of SWH surface. - Unitless.
shadedSolarRadiationPerHour
Total shaded incidence for each hour during a year. - In kW/m2.
Sep21toMar21Shading
Sunpath_Shading
187
Ladybug Primer
Weighted shading of the active sun window quadrants, for period between 21st
September to 21st March. Active sun window quadrants are only those which produce
AC energy. It is calculated for each analysisGeometry vertex and then averaged. It
ranges from 0-100(%). - In percent(%).
Mar21toSep21Shading
Weighted shading of the active sun window quadrants, for period between 21st March
to 21st September. Active sun window quadrants are only those which produce AC
energy. It is calculated for each analysisGeometry vertex and then averaged. It ranges
from 0-100(%). - In percent(%).
annualShading
Annual weighted shading of the active sun window quadrants. To calculate it, input the
hourly data to "ACenergyPerHour" input. Active sun window quadrants are only those
which produce AC energy. It is calculated for each analysisGeometry vertex and then
averaged. It ranges from 0-100(%). - Use it as an input for Ladybug "DC to AC derate
factor" component's "annualShading" input to account for shading of PVsurface. - In
percent(%).
annalysisPts
Each vertex of the inputted _analysisGeometry for which a separate shading analysis
was conducted. - Connect this output to a Grasshopper's "Point" parameter in order to
preview the "annalysisPts" geometry in the Rhino scene.
sunWindowCenPt
The center point of the "sunWindowCrvs" and "sunWindowMesh" geometry. It is
calculated for analysisGeometry area centroid. Use this point to move
"sunWindowCrvs" and "sunWindowMesh" geometry around in the Rhino scene with the
grasshopper's "Move" component. - Connect this output to a Grasshopper's "Point"
parameter in order to preview the "annalysisPts" geometry in the Rhino scene.
sunWindowCrvs
Geometry of the sun window based on 3D polar sun path diagram. Perpendical curves
represent solar time hours. Horizontal arc curves represent sun paths for: 21st
December, 21st November/January, 21st October/February, 21st September/March,
21st August/April, 21st July/May, 21st June. The whole sunWindowCrvs geometry
output is calculated for analysisGeometry area centroid.
sunWindowMesh
Sunpath_Shading
188
Ladybug Primer
Sun window mesh based on 3D polar sun path diagram. It is calculated for
analysisGeometry area centroid. Black areas represent 100% shaded portions of the
sun window (of both active and inactive quadrants). Darker green and green areas
represent partially shaded portions from the coniferous and deciduous trees,
respectively. - It is calculated ONLY if data is supplied to the "ACenergyPerHour_"
input".
legend
A legend of the sunWindowMesh. Connect this output to a Grasshopper's "Geo"
parameter in order to preview the legend separately in the Rhino scene.
legendBasePt
Legend base point, which can be used to move the "legend" geometry with
grasshopper's "Move" component. - Connect this output to a Grasshopper's "Point"
parameter in order to preview the "annalysisPts" geometry in the Rhino scene.
quadrantCentroids
Centroid for each sun window active quadrant above the horizon. - Use grasshopper's
"Text tag" component to visualize them.
quadrantShadingPercents
Shadinging percent per each sun window active quadrant above the horizon. Active
quadrants with less than 0.01% are neglected. - Use grasshopper's "Text tag"
component to visualize them.
quadrantACenergyPercents
AC energy percent per each sun window active quadrant above the horizon. - Use
grasshopper's "Text tag" component to visualize them.
hoursPositions
Solar time hour point positions. - Use grasshopper's "Text tag" component to visualize
them.
hours
Solar time hour strings. - Use grasshopper's "Text tag" component to visualize them.
Check Hydra Example Files for Sunpath Shading
Sunpath_Shading
189
Ladybug Primer
Tilt And Orientation Factor
This component calculates the Optimal Tilt, Optimal Orientation and TOF (Tilt and
Orientation Factor) for PV modules or Solar water heating collectors. TOF is a solar radiation
at the actual tilt and orientation divided by the solar radiation at the optimum tilt and
orientation. -
Inputs
epwFile [Required]
190
Ladybug Primer

PV_SWHsurface [Required]
Input planar Grasshopper/Rhino Surface (not a polysurface) on which the PV
modules/SWH collectors will be applied. If you have a polysurface, explode it (using
"Deconstruct Brep" component) and then feed its Faces(F) output to _PV_SWHsurface.
Surface normal should be faced towards the sun.
Or create the Surface based on initial PV/SWH system size by using "PV SWH
system size" component.
annualShading [Optional]
Losses due to buildings, structures, trees, mountains or other objects that prevent solar
radiation from reaching the PV module/Solar water heating collector. Input range: 0 to
100(%), 0 being unshaded, and 100 being totally shaded PV module/SWH collector. - If
not supplied default value of 0(%) will be used.
north [Optional]
albedo [Optional]
precision [Optional]
Represents the square root number of analysis field for the output "geometry" mesh.
Ranges from 1-100. Example - precision of 4, would mean that 4 fields in X direction
(Azimuth) and 4 fields in Y direction (Tilt) = 16 fields, will be used to calculate the final
"geometry" mesh. For lower precision numbers (say < 20) even precision numbers are
more accurate. - CAUTION!!! Precision numbers (10 >) require stronger performance
PCs. If your PC is somewhat "weaker", the precision of < 10 will be just fine. - If not
supplied, default value of 2 will be used.
scale [Optional]
191
Ladybug Primer
Scale of the overall geometry. - If not supplied, default value of 1 will be used.
origin [Optional]
Origin for the final "geometry" output. - If not supplied, default point of (-15,0,0) will be
used.
Optional legend parameters from the Ladybug "Legend Parameters" component.
bakeIt [Optional]
Set to "True" to bake the Tilt and orientation factor results into the Rhino scene. - If not
supplied default value "False" will be used.
runIt [Required]
...
Outputs
readMe!
...
TOF
Tilt and Orientation Factor - solar radiation at the actual tilt and azimuth divided by the
solar radiation at the optimum tilt and azimuth. In percent(%).
TSRF
Total Solar Resource Fraction - the ratio of solar radiation available accounting for both
annual shading and TOF, compared to the solar radiation available at a given location at
the optimum tilt and azimuth and with no shading. Calculated according to the following
equation: TSRF = TOF * (100-annualShading)/100 Some USA states, like Oregon and
Washington require TSRF to be minimum 75% in order for the PV system to be
applicable for incentive programs. - In percent(%).
PVsurfaceTilt
Tilt angle of the inputted PV_SWHsurface. In degrees ().
PVsurfaceAzimuth
192
Ladybug Primer
Orientation angle of the inputted PV_SWHsurface. In degrees ().

optimalTilt
Optimal tilt of the PV_SWHsurface for a given location. Optimal tilt being the one that
receives the most annual solar radiation. In degrees ().
optimalAzimuth
Optimal orientation of the PV_SWHsurface for a given location. Optimal azimuth being
the one that receives the most annual solar radiation. In degrees ().
optimalRoofPitch
Optimal steepness of the PV_SWHsurface for a given location. Optimal steepness
being the one that receives the most annual solar radiation. In inches/inches
optimalRadiation
Total solar radiation per square meter for a whole year received on a PV_SWHsurface
of optimal tilt and azimuth, at given location. In kWh/m2
geometry
Geometry of the whole TOF mesh chart. Connect this output to a Grasshopper's "Geo"
parameter in order to preview the "geometry" separately in the Rhino scene.
originPt
The origin point of the "geometry" output. Use this point to move "geometry" output
around in the Rhino scene with the grasshopper's "Move" component.
analysisPt
A point indicating inputted PV_SWHsurface's Tilt/Azimuth position on the solar radiation
table.
legend
A legend for the annual total solar radiation (in kWh/m2). Connect this output to a
Grasshopper's "Geo" parameter in order to preview the legend separately in the Rhino
scene.
legendBasePt
Legend base point, which can be used to move the "legend" geometry with
grasshopper's "Move" component.
193
Ladybug Primer
Check Hydra Example Files for Tilt And Orientation Factor
194
Ladybug Primer
Forward Raytracing
Use this component to get a sense of how sunlight is reflected by a set of context
geometries by tracing sun rays forwards through this geometry. Examples where this
component might be useful include the evaluation of the diffusion of light by a light shelf, or
testing to see whether a parabolic building geometry (like a Ghery building) might focus
sunlight to dangerous levels at certain times of the year. Note that this component assumes
that all sun light is reflected off of these geometries specularly (as if they were a mirror) and,
for more detailed raytrace analysis, the Honeybee daylight components should be used. -
Inputs
Forward_Raytracing
195
Ladybug Primer
startPts [Required]
Points from which the sun rays will be cast towards the _context geometry. You may
want to connect a grid of points here to mimic the fact that direct sun will be streaming
evenly from the sky.
startVectors [Required]
A sun vector from the sunPath component or a list of sun vectors to be forward raytraced.
context [Required]
Breps or meshes of conext geometry that will reflect the sun rays. Note that, for curved
surfaces, smooth meshes of the geometry will be more accurate than inputing a Brep.
numOfBounce [Default]
An interger representing the number of ray bounces to trace the sun rays forward.
lastBounceLen [Default]
A float number representing the length in Rhino model units of the light ray after the last
bounce.
Outputs
rays
A series of line curves representing light rays traced forward through the geometry.
Check Hydra Example Files for Forward Raytracing
Forward_Raytracing
196
Ladybug Primer
SolarEnvelopeBasic
Use this component to generate a solar envelope for a closed boundary curve with minimum
inputs. This component predefines monthly and hourly ranges in order to simplify the
creation of useful envelope geometry.
The solar envelope is used to ensure that its adjacent neighbors (defined as anything
outside of the chosen boundary curve) will receive a specified minimum hours of direct solar
access for each day in a specified month range of the year. Any geometry built within the
solar envelope boundaries will therefore not cast any shadow on adjacent property for the
given hour and month range. The start and end dates that determine the month range for
solar access can be chosen from the following options: 0) Mar 21 - Jun 21 1) Mar 21 - Sep
21 2) Mar 21 - Dec 21 3) Jun 21 - Sep 21 4) Jun 21 - Dec 21 5) Sep 21 - Dec 21 The default
SolarEnvelopeBasic
197
Ladybug Primer
set to 4) June 21 to December 21. Reference: Niemasz, J., Sargent, J., Reinhart D.F., "Solar
Zoning and Energy in Detached Residential Dwellings," Proceedings of SIMAUD 2011,
Boston, April 2011. -
Inputs
boundary [Required]
A closed boundary curve representing a piece of land (such as a property to be
developed) for which solar access of the surrounding land is desired.
location [Required]
requiredHours [Required]
The number of hours of direct solar access that the property surrounding the boundary
curve should receive during the _monthRange. For example an input of 4 will define the
hour range roughly between 10AM and 2PM. The component will compute the hour
range that will maximize the envelope volume.
north [Optional]
monthRange [Required]
An optional interger value to change the month range for which solar access is being
considered. The default month range is Jun 21 - Dec 21.
Integers input here must be between 0 - 5

and correspond to the following :
0 = Mar 21 - Jun 21 1 = Mar 21 - Sep 21 2 = Mar 21 - Dec 21 3 = Jun 21 - Sep 21 4 =
Jun 21 - Dec 21
5 = Sep 21 - Dec 21
SolarEnvelopeBasic
198
Ladybug Primer
Where, in the North/South Hemispheres, these dates repsectively signify: Mar 21 =

Vernal/Autumnal Equinox Jun 21 = Summer/Winter Solstice Sep 21 = Autumnal/Vernal
Equinox Dec 21 = Winter/Summer Solstice
Outputs
readMe!
...
solarEnvelope
A Brep representing a solar envelope. This volume should be built within in order to
ensure that the surrounding property is not shaded for the given number of hours.
Check Hydra Example Files for SolarEnvelopeBasic
SolarEnvelopeBasic
199
Ladybug Primer
SolarFanBasic
Use this component to generate a solar fan with minimumal input data. This component
predefines monthly and hourly ranges in order to simplify the creation of useful fan
geometry.
The solar fan is used to ensure that a given property within a boundary curve is guarenteed
a specified minimum hours of direct solar access for each day in a specified month range of
the year. Thus, context geometries surrounding this boundary curve that do not penetrate
the solar fan will not cast shadows onto the boundary area for the specified hour and month
range. The start and end dates that determine the month range for solar access can be
chosen from the following options: 0) Mar 21 - Jun 21 1) Mar 21 - Sep 21 2) Mar 21 - Dec 21
SolarFanBasic
200
Ladybug Primer
3) Jun 21 - Sep 21 4) Jun 21 - Dec 21 5) Sep 21 - Dec 21 The default set to 3) June 21 to
September 21. Note that extremely complicated concave shapes will take a long time to
calculate a solar fan for. -
Inputs
boundary [Required]
closed boundary curve representing a piece of land (such as a park) or a window for
which solar access is desired.
location [Required]
requiredHours [Required]
The number of hours of direct solar access that the property inside the boundary curve
should receive during the _monthRange. For example an input of 4 will define the hour
range roughly between 10AM and 2PM. The component will compute the hour range
that will maximize the fan volume.
height [Required]
The number of Rhino model units that the solar fan should be extended above the
boundary curve.
north [Optional]
monthRange [Required]
An optional interger value to change the month range for which solar access is being
considered. The default month range is Jun 21 - Sep 21.
Integers input here must be between 0 - 5

and correspond to the following :
0 = Mar 21 - Jun 21 1 = Mar 21 - Sep 21 2 = Mar 21 - Dec 21 3 = Jun 21 - Sep 21 4 =
SolarFanBasic
201
Ladybug Primer
Jun 21 - Dec 21
5 = Sep 21 - Dec 21
Where, in the North/South Hemispheres, these dates repsectively signify: Mar 21 =
Vernal/Autumnal Equinox Jun 21 = Summer/Winter Solstice Sep 21 = Autumnal/Vernal
Equinox Dec 21 = Winter/Summer Solstice
Outputs
out
...
solarFan
Brep representing a solar fan. This volume should be clear of shading in order to ensure
solar access to the area inside the boundary curve for the given number of hours.
Check Hydra Example Files for SolarFanBasic
SolarFanBasic
202
Ladybug Primer
Component list:
Mesh-To-Hatch
North
Recolor_Mesh
True_North
Gradient_Library
Legend_Parameters
Capture_View
Orient_to_Camera
Set_the_View
fly
C2F
DOY_HOY
Day_Month_Hour
F2C
Activities_Met_List
BTU2Wh
Comfort_Mannequin
Construct_Time
Create_Legend
L2G
Wh2BTU
4 | Extra
203
Ladybug Primer
Wh2kWh
kWh2Wh
ms2mph
rIP2rSI
uIP2uSI
4 | Extra
204
Ladybug Primer
Mesh-To-Hatch
Use this component to bake a clored mesh into the Rhino scene as a series of colored
hatches. This is particularly useful if you are trying to export ladybug graphics from Rhino to
vector-based programs like Inkscape or Illustrator. -
Inputs
mesh [Required]
A colored mesh (or list of colored meshes) that you would like to bake into the Rhino
scene as a series of colored hatches.
Mesh-To-Hatch
205
Ladybug Primer
runIt [Required]
Set to 'True' to run to run the component and bake the mesh into the scene as a series
of hatches.
Outputs
readMe!
...
Check Hydra Example Files for Mesh-To-Hatch
Mesh-To-Hatch
206
Ladybug Primer
North
Use this component to create a compass sign that indicates the direction of North in the
Rhino scene. -
Inputs
north [Default]
Input a vector to be used as a North direction or a number between 0 and 360 that
North
207
Ladybug Primer
centerPt [Default]
Input a point here to change the location of the North sign in the Rhino scene. The
default is set to the Rhino model origin (0,0,0).
scale [Default]
Input a number here to change the scale of the sun path. The default is set to 1.
Outputs
northSign
A set of surfaces and curves that indicate the direction of North in Rhino.
Check Hydra Example Files for North
North
208
Ladybug Primer
Recolor Mesh
Use this component to re-color a mesh with new a numerical data set whose length
corresponds to the number of faces in the _inputMesh. This component is useful if you have
post-processed any of the numerical data out of the Ladybug components using
Grasshopper math components. It is also necessary to view results from the Ladybug Real
Time Radiation Analysis. -
Inputs
analysisResult [Required]
Recolor_Mesh
209
Ladybug Primer
A numerical data set whose length corresponds to the number of faces in the
_inputMesh. This data will be used to re-color the _inputMesh.
inputMesh [Required]
An already-colored mesh from one of the Ladybug components which you would like to
re-color based on data in the _analysisResult.
heightDomain [Optional]
Optional height domain to create a 3D mesh result. Use Construct Domain component
to create a domain
Optional legend parameters from the Ladybug Legend Parameters component. Legend
Parameters can be used to change the colors, numerical range, and/or number of
divisions of any Ladybug legend along with the corresponding colored mesh.
analysisTitle [Optional]
Text representing a new title for the re-colored mesh. If no title is input here, the default
will read "unnamed."
legendTitle [Optional]
Text representing a new legend title for re-colored mesh. Legends are usually titled with
the units of the _analysisResult. If no text is provided here, the default title will read
"unkown units."
bakeIt [Optional]
Set to "True" to bake the resulting mesh and legend into the Rhino scene.
layerName [Optional]
If bakeIt_ is set to "True", input Text here corresponding to the Rhino layer onto which
the resulting mesh and legend should be baked.
Outputs
readMe!
...
newMesh
Recolor_Mesh
210
Ladybug Primer
A new mesh that has been re-colored based on the _analysisResult data.
newLegend
A new legend that that corresponds to the colors of the newMesh. Connect this output
to a grasshopper "Geo" component in order to preview this legend separately in the
Rhino scene.
legendBasePt
The legend base point, which can be used to move the legend in relation to the
newMesh with the grasshopper "move" component.
meshColors
Script variable reColorMesh
legendColors
Script variable reColorMesh
Check Hydra Example Files for Recolor Mesh
Recolor_Mesh
211
Ladybug Primer
True North
Use this component to calculate Earth's true north from magnetic north. - If you are working
with location plan generated by Google Maps or any other web mapping service, North will
always be positioned in direction of Rhino's Y axis. In case you imported a location plan to
Rhino, which has a North direction assigned in a form of magnetic North, then you need to
correct that North direction for the influence of Earth's magnetic variation. Which is what this
component does. - All credit goes to Christopher Weiss (cmweiss@gmail.com), the author of
the World Magnetic Model python code. source: https://pypi.python.org/pypi/geomag Based on World Magnetic Model of the NOAA:
http://www.ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml -
True_North
212
Ladybug Primer
Inputs
location [Required]
Input data from Ladybug's "Import epw" "location" output, or create your own location
data with Ladybug's "Construct Location" component.
magneticNorth [Optional]
Input a vector to be used as a magnetic North direction, or a number between 0 and
360 that represents the clockwise degrees off from the Y-axis. Magnetic north direction
is direction a compass-needle points to. - If not supplied, default North direction will be
date [Optional]
Date for which magnetic north should be calculated. Input a date in the following order:
month, day, year. Example "5,24,2016" (24nd May 2016). - If not supplied, present date
will be used.
COFfile [Optional]
By default "Magnetic north" component already has 2015-2020 integrated WMM
coefficients data. In case you would like to analysis periods of time before the year
2015, input an appropriate WMM.COF file path in here. - If not supplied, integrated
WMM.COF 2015-2020 coefficients data will be used.
Outputs
readMe!
...
trueNorth
Geographic north (direction towards the North Pole) - magnetic north corrected for the
value of magnetic declination. Ranges from 0-360. - In decimal degrees ().
trueNorthVec
Vector representation of the upper "trueNorth".
magneticDeclination
An angle between magnetic north and true north. It is positive east of true north and
negative west of true north. - In decimal degrees ().
True_North
213
Ladybug Primer
magneticFieldVec
Earth's magnetic field vector at chosen location. Vector's intensity represents the
strength in nanoTeslas (nT).
Check Hydra Example Files for True North
True_North
214
Ladybug Primer
Adaptive Comfort Parameters
Use this component to set Adaptive comfort parameters for the Adaptive Comfort Calculator
or the Adaptive Comfort Chart.
Parameters include the ability to use either US (ASHRAE) or European (EN) standards as
well as set the acceptability threshold for the percent of the occupants that are comfortable
(which varies for different building types between the two standards). This component also
includes the ability to set a custom correlation between outdoor temperature and indoor
desired temperature using a 'levelOfConditioning' variable and research that is not an official
part of the ASHRAE or EN standards but is endorsed by many of the scientists who helped
create these standards. Detailed information on all of these parameters is described in this
book: Fergus Nicol, Michael Humphreys, Susan Roaf. Adaptive Thermal Comfort: Principles
215
Ladybug Primer
and Practice. Routledge, 2012. (https://books.google.com/books?

id=vE7FBQAAQBAJ&dq=adaptive+thermal+comfort) Users are also encouraged to use the
'Ladybug_Adaptive Comfort Chart' component or the Center for the Built Environment's
(CBE) comfort tool to help visualize the differences between these parameters: Special
thanks goes to the authors of the online CBE Thermal Comfort Tool who first coded the
javascript: Hoyt Tyler, Schiavon Stefano, Piccioli Alberto, Moon Dustin, and Steinfeld Kyle.
http://cbe.berkeley.edu/comforttool/ -
Inputs
ASHRAEorEN [Optional]
Set to 'True' to have the Adpative components use the US (ASHRAE 55 2013) adaptive
standard and set to 'False' to have the Adaptive components use the European (EN15251) standard. The default is set to use the US (ASHRAE 55 2013) standard. Note
that changing the standard will also change some of the inputs below. The ASHRAE
standard will use the average monthly temperature by default and the European
standard will use a running mean temperature by default. Also, the European standard
uses building classes instead of 80 / 90 percent acceptability.
eightyOrNinetyComf [Optional]
Set to 'True' to have the comfort standard be 80 percent of occupants comfortable and
set to 'False' to have the comfort standard be 90 percent of all occupants comfortable.
The default is set to 'False' for 90 percent, which is what most members of the building
industry seem to aim for in today's world. However some projects will occasionally use
80% as this was originally the benchmark that engineers set around the dawn of air
conditioning.
avgMonthOrRunMean [Optional]
Set to 'True' to have the Adpative components compute the prevailing outdoor
temperature from the average monthly temperature (the official method used by the
US's ASHRAE 55 2013) and set to 'False' compute the prevailing outdoor temperature
from a weighted running mean of the last week (the official method used by Europe's
EN-15251). The default is set to align with the chosen comfort standard above (either
ASHRAE 55 2013 or EN-15251) but this option is included to allow users to explore
differences and variations between the two standards.
levelOfConditioning [Optional]
An optional number between 0 and 1 that represents how 'air conditioned' a space is.
By default, this value is always set to 0 because both the ASHRAE 55 2013 and EN-
216
Ladybug Primer
15251 standards are strictly meant to be used for buildings without any installed air
conditioning whatsoever. However, the researchers who developed the original Adaptive
models also surveyed many people in conditioned buildings to show that the adaptive
model did not contradict the PMV model when it was applied to buildings that resembled
the conditioned climate chamber used to validate the PMV model. From these surveys
of fully-conditioned buildings, researchers produced a correlation between prevailing
outdoor temperature and desired indoor temperature that had a much shallower slope
than that for fully naturally-ventilated buildings. This input allows you to use this fully
conditioned correlation (by setting this input to 1) or create any custom correlation in
between these two (arguably representative of mixed-mode or hybrid AC/naturally
ventilated buildings). The conditioned building correlation used in the Ladybug Adaptive
model can be found in the book refenced in the component description and specifically
comes from this study: CIBSE (2006) Environmental Criteria for Design, Chapter 1:
Environmental Design: CIBSE Guide A. London: Chartered Institution of Building
Services Engineers.
Outputs
comfortPar
Comfort parameters that you can plug into either the "Ladybug_Adaptive Comfort
Calculator" or the "Ladybug_Adaptive Comfort Chart."
Check Hydra Example Files for Adaptive Comfort Parameters
217
Ladybug Primer
Body Characteristics
Use this component to calculate the Basal Metabolic Rate, Body Mass Index indices and to
create the "bodyCharacterstics_" input for the "Thermal comfort indices" component. - Basal
Metabolic Rate formula by Mifflin-St. Jeor. Body Mass Index formula by Adolphe Quetelet. Formulas from: "Comparison of predictive equations for resting Metabolic rate in healthy
nonobese and obese adults: a systematic review", Frankenfield, Roth-Yousey, Compher,
American Dietetic Association, 2005.:
https://www.andeal.org/files/Docs/Frankenfield_et_al_2005%5B1%5D.pdf -
Inputs
218
Ladybug Primer
age [Optional]
An age of the person. - If not supplied, default value of 35 will be used. - In years.
sex [Optional]
Person's sex. - 1 or "male" 2 or "female". - If not supplied, "male" will be used as a
default value.
height [Optional]
Person's height. - If not supplied default value of 175 cm will be used. - In centimetres.
weight [Optional]
Person's weight. - If not supplied default value of 75 kg will be used. - In kilograms.
bodyPosition [Optional]
Position of person's body. - 1 or "sitting" for sitting position. 2 or "standing" for standing
position. 3 or "crouching" for crouching position. - If not supplied, 2 (standing) will be
used as a default value.
clothingInsulation [Optional]
Clothing insulation of a person in "clo" units. It ranges from 0 (nude person) to 4 (polar
outfit). Overall clo value can be determined by adding individual clo values for each type
of clothes, based on a clo values table ( http://www.engineeringtoolbox.com/cloclothing-thermal-insulation-d_732.html ) A more simplified approch would be: - 0.20 very light summer clothes (shorts/skirt, t-shirt, slippers, no socks) 0.55 - summer clothes
(light trousers, short sleeves or blouse) 1 - street-business suit or Typical indoor winter
clothing 1.5 - suit and cotton coat 2 - winter suit and coat 2.58 - firefighting clothes 4 heavy polar outfit (fur pants, coat, hood, gloves...) - If not supplied it will be caclulated
for each hour based on air temperature, with minimal 0.5 and maximal 4.1 clo values. In clo.
clothingAlbedo [Optional]
Average clothing and skin albedo of a person. Ranges from 0 to 100%. In theory
clothes-skin albedo of 0 would absorb, while 100% will reflect all solar radiation. Some
of the examples: - light colored (white and bright clothes) - 57 % dark colored (black and
gray clothes) - 21 % medium colored (any clothes colors between upper two) - 37 %
protective polyethylene/aluminium suits - 95 % - If not supplied 37% (medium colored)
will be used as a default. - In percent.
219
Ladybug Primer
acclimated [Optional]
Determine whether the test person had previously experienced heat/cold stress. "acclimated" or True if person in subject is acclimatized, "unacclimated" or False if it's
not. - If no value is supplied, True (acclimated) will be used by default.
Activity's metabolic rate in mets. If not supplied 2.32 will be used as default value Here
are some of the examples of metabolic rates mets based on activity:
Activity - met
Reclining - 0.8 Seating - 1.0 Car driving - 1.2 Sedentary activity (office, dwelling, school,
laboratory) - 1.2 Standing - 1.2 Standing (light activity: shopping, laboratory, light
industry) - 1.6 Standing (medium activity: shop assistant, domestic work) - 2.0 Walking
(4 km/h) - 2.32 Walking (5 km/h) - 3.4 ... Washing dishes standing - 2.5 Domestic work
(raking leaves on the lawn) - 2.9 Domestic work (washing by hand and ironing) - 2.9
Iron and steel (ramming the mould with a pneumatic hammer) - 3.0 Building industry
(brick laying) - 2.2 Building industry (forming the mould) - 3.1 Building industry (loading
a wheelbarrow with stones and mortar) - 4.7 Forestry (cutting with chainsaw) - 3.5
Forestry (working with an axe) - 8.5 Agriculture (digging with a spade) - 6.5 ... Volleyball
- 4.0 Golf - 5.0 Softball - 5.0 Gymnastics - 5.5 Aerobic Dancing - 6.0 Swimming - 6.0 Ice
skating - 6.2 Bicycling (15 km/h) - 4.0 Bicycling (20km/h) - 6.2 Skiing (9 km/h) - 7.0
Backpacking - 7.0 Basketball - 7.0 Handball - 8.0 Hockey - 8.0 Racquetball - 8.0 Soccer
- 8.0 Running (8 km/h) - 8.5 Running (15km/h) - 9.5 - If not supplied default value of
2.32 (walking 4 km/h or 1.1m/s) mets will be used. - In mets.
activityDuration [Optional]
Duration of the activity sequence. It should not be lower than 180 minutes (3 hours) and
it should be dividable with 60 (meaning only full hour values are accepted: 180, 240,
300, 360, 420, 480, 540 ...) - If not supplied, default value of 480 minutes (8 hours) will
be used. - In minutes.
Outputs
readMe!
...
BMR
220
Ladybug Primer
Basal Metabolic Rate - represents the minimum daily amount of energy needed to keep
your body functioning, including breathing and keeping your heart beating, without
lossing weight. It does not include the the calories you burn from normal daily activities
or exercise. To account for daily activities and exercises, this BMR value needs to be
multiplied with: - 1.2 - Light or no exercise and desk job 1.375 - Light exercise or sports
1-3 days a week 1.55 - Moderate exercise or sports 3-5 days a week 1.725 - Hard
exercise or sports 6-7 days a week 1.9 - Hard daily exercise or sports and physical job Once the person knows the number of daily calories needed to maintain its weight, it
can easily calculate the number of calories it needs to eat in order to gain or lose
weight. In calories/day.
BMI
Body Mass Index - is the ratio of the persons weight to square of height. It is generally
used as a method of screening for weight category. In kg/m2.
BMILevel
Level of BMI for adult (18 years and older)

males and females:
for males: BMI < 17.5 - Anorexia 17.5 < BMI < 20.7 - Underweight 20.7 < BMI <
26.4 - Normal weight 26.4 < BMI < 27.8 - Marginally overweight 27.8 < BMI < 31.1 Overweight 31.1 < BMI < 40 - Obese BMI > 40 - Extreme obesity for females: BMI < 17.5 - Anorexia 17.5 < BMI < 19.1 - Underweight 19.1 < BMI <
25.8 - Normal weight 25.8 < BMI < 27.3 - Marginally overweight 27.3 < BMI < 32.3 Overweight 32.3< BMI < 40 - Obese BMI > 40 - Extreme obesity - In calories/day.
bodyCharacteristics
A list of inputted values (age, sex, height, weight, bodyPosition, clothingInsulation,
acclimated, metabolicRate, activityDuration). - Use it for the "Thermal comfort indices"
component's "bodyCharacteristics_" input.
Check Hydra Example Files for Body Characteristics
221
Ladybug Primer
Gradient Library
Use this component to access a library of typical gradients useful throughout Ladybug. The
output from this component should be plugged into the customColors input of the
"Ladybug_Legend Parameters" component. For an image of each of the gardients in the
library, check here:
https://github.com/mostaphaRoudsari/ladybug/blob/master/resources/gradients.jpg -
Inputs
gradIndex [Required]
Gradient_Library
222
Ladybug Primer
An index refering to one of the following possible gradients: 0 - Orignal Ladybug 1 Nuanced Ladybug 2 - Multi-colored Ladybug 3 - View Analysis 1 4 - View Analysis 2
(Red,Green,Blue) 5 - Sunlight Hours 6 - Ecotect 7 - Thermal Comfort Percentage 8 Thermal Comfort Colors 9 - Thermal Comfort Colors (UTCI) 10 - Hot Hours 11 - Cold
Hours 12 - Shade Benefit/Harm 13 - Thermal Comfort Colors v2 (UTCI) 14 - Shade
Harm 15 - Shade Benefit 16 - Black to White 17 - CFD Colors 1 18 - CFD Colors 2 19 Energy Balance 20 - THERM 21 - Cloud Cover
Outputs
customColors
A series of colors to be plugged into the "Ladybug_Legend Parameters" component.
Check Hydra Example Files for Gradient Library
Gradient_Library
223
Ladybug Primer
Legend Parameters
Use this component to change the colors, numerical range, and/or number of divisions of
any Ladybug legend along with the corresponding colored mesh that the legend refers to.
This component can also move a legend and change its scale. Any Ladybug component that
outputs a colored mesh and a legend will have an input that can accept Legend Parameters
from this component. This component particularly helpful in making the colors of Ladybug
graphics consistent for a presentation or for synchonizing the numerical range and colors
between Ladybug graphics. -
Inputs
Legend_Parameters
224
Ladybug Primer
lowBound [Optional]
A number representing the lower boundary of the legend's numerical range. The default
is set to the lowest value of the data stream that the legend refers to.
highBound [Optional]
A number representing the higher boundary of the legend's numerical range. The
default is set to the highest value of the data stream that the legend refers to.
numSegments [Optional]
An interger representing the number of steps between the high and low boundary of the
legend. The default is set to 11 and any custom values put in here should always be
greater than or equal to 2.
customColors [Optional]
A list of colors that will be used to re-color the legend and the corresponding colored
mesh(es). The number of colors input here should match the numSegments_ value
input above. An easy way to generate a list of colors to input here is with the
Grasshopper "Gradient" component and a Grasshopper "Series" component connected
to the Gradient component's "t" input. A bunch of Grasshopper "Swatch" components is
another way to generate a list of custom colors. The default colors are a gradient
spectrum from blue to yellow to red.
legendLocation [Optional]
Input a point here to change the location of the legend in the Rhino scene. The default
is usually set to the right of the legend's corresponding Ladybug graphic.
legendScale [Optional]
Input a number here to change the scale of the legend in relation to its corresponding
Ladybug graphic. The default is set to 1.
font [Optional]
An optional text string that sets the font of the text. Examples include "Arial", "Times
New Roman" or "Courier" (all without quotations). The text input here can be any font
that is on your computer but the font must be of an Editable file type (as seen in the font
folder off of your control panel). Font files that are Print and Preview will not work. If you
wish to use a Bolded version of the font, include a ", Bold" at the end of the font name
(example: "Arial, Bold").
Legend_Parameters
225
Ladybug Primer
fontSize [Optional]
An optional number to set the size of the text in Rhino model units.
decimalPlaces [Optional]
An interger representing the number of decimal places to make the legend values. The
default is set to 2 decimal places.
removeLessThan [Optional]
Set to 'True' to have the "<=" and ">=" symbols removed from the legend. The default is
set to 'False' to have these symbols included.
Outputs
legendPar
A list of legend parameters to be plugged into any of the Ladybug components with a
legend.
Check Hydra Example Files for Legend Parameters
Legend_Parameters
226
Ladybug Primer
PMV Comfort Parameters
Use this component to set PMV comfort parameters for the PMV comfort calculator or the
Psychrometric Chart.
Parameters include whether comfort is defined by 80 or 90 percent of the occupants
comfortable as well as maximum and minimum acceptable humidity ratios. Note that the
applied science and engineering community differs widely on its inderstanding of these
parameters. The air conditioning industy set out with the goal of satisfying 80% of the
occupants (assuming they all had similar clothing and metabolic rates) but many today set
90% as their benchmark. Also note that, if you try to restrict everyone's clothing and
227
Ladybug Primer
metabolic rate as the PMV model assumed, you can never make 100% of the people
comfortable. _ Further note that cultures differ widely in terms of their treatment of humidity
at cooler temperatures and lack of humidity. -
Inputs
PPDComfortThreshold [Optional]
A number between 5 and 100 that represents the percent of people dissatisfied (PPD)
at which point a given set of conditions are outside of a comfortable range. The default
is set to 10 percent, which is the typical criteria for both US and European (ISO)
standards. However, both of these standards allow an expanded range for infrequenltyoccupied buildings (20% in the US and 15% in Europe) and the European standard
requires 6% for 'Class I' buildings. Note that, if you try to restrict everyone's clothing and
metabolic rate as the PMV model assumes, you can never make 100% of the people
comfortable. This is why the smallest acceptable input here is 5%.
humidRatioUpBound [Optional]
An optional number between 0.012 and 0.030 that limits the maximum humidity ratio
acceptable for comfort. In many cultures and to many people, humidity in conditions of
no thermal stress is not considered a source of discomfort and, accordingly, this
component does not set an upper limit on humidity by default. However, for some
people, stickyness from humidity in cool conditons is considered uncomfortable and, if
you want to account for such a situation, you may want to set an upper limit on the
acceptable humidity ratio here. The ASHRAE 55 PMV comfort standard recommends a
maximum humidity of 0.012 kg water/kg air.
humidRatioLowBound [Optional]
An optional number between 0.000 and 0.005 that limits the minimum humidity ratio
acceptable for comfort. In many cultures, a lack of humidity is not considred
uncomfortable since people compensate for its effects by using chap stick and lotions.
Accordingly, this component does not set a lower limit on humidity by default. However,
in some more tropical where people are not accustomed to very dry environments,
chaping of lips and drying of skin can occur more easily and, if you want to account for
such a situation, you may want to set a lower limit on the acceptable humidity ratio here.
The ASHRAE 55 PMV comfort recommends no lower limit on humidity.
Outputs
comfortPar
228
Ladybug Primer
Comfort parameters that you can plug into either the "Ladybug_PMV Comfort
Calculator" or the "Ladybug_Psychrometric Chart."
Check Hydra Example Files for PMV Comfort Parameters
229
Ladybug Primer
Passive Strategy List
Provides a list of passive thermal strategies to be plugged into the Ladybug_Psychrometric

Chart
Inputs
Check Hydra Example Files for Passive Strategy List
230
Ladybug Primer
Real Time Radiation Analysis
Use this component to scroll through the results of a Ladybug Radiation Analysis on an
hour-by-hour, day-by-day, or month-by-month basis in real time! The component uses a sky
matrix (SkyMxt) from the selectSkyMxt component and the intersection matrix
(intersectionMxt) from the Radiation Analysis component to calculate real time radiation
results. Once the correct inputs have been hooked up to this component, you should use the
inputs of the connected selectSkyMxt component to scroll through results. -
Inputs
selectedSkyMatrix [Required]
231
Ladybug Primer
The output from a Ladybug selectedSkyMtx component. This matrix basically carries all
of the radiation values that define a sky and includes a radiation value for each sky
patch on the sky dome. You should use the selectSkyMxt component connected here to
scroll through radiation results.
intersectionMatrix [Required]
The intersectionMxt output from a Ladybug Radiation Analysis component that has
been run for test geometry. This matrix is basically a python list that includes the relation
between each test point in the Radiation Analysis and all the sky patchs on the sky
dome.
Outputs
radiationResult
New radiation values for each test point in the original Radiation Analysis. Values
indicate radiation for the the connected sky matrix. To visualize these new radiation
values in the Rhino scene, connect these values to the Ladybug Re-Color Mesh
component to re-color the mesh from the original Radiation Analysis with these new
values.
Check Hydra Example Files for Real Time Radiation Analysis
232
Ladybug Primer
Capture View
Use this component to capture Rhino views and save them to your hard drive as as a .png
files. This is particularly useful if you are trying to create animations of Grasshopper
geometry and want to automate the capturing of views. Note that your images will have a
Rhino world axes icon in the lower left of the image unless you go to Options > Grid > and
uncheck "Show world axes icon" in Rhino. -
Inputs
fileName [Required]
Capture_View
233
Ladybug Primer
The file name that you would like the image to be saved as. Note that, for animations,
you want to make sure that each saved images has a different filename otherwise the
previous image will be overwritten by each successive image.
folder [Optional]
The folder into which you would like to write the image file. This should be a complete
file path to the folder. If no folder is provided, the images will be written to
C:/Ladybug/Capturedviews/.
viewNames [Optional]
The Rhino viewport name which you would like to take a snapshot of. Acceptable inputs
include "Perspective", "Top", "Bottom", "Left", "Right", "Front", "Back" or any view name
that you have already saved within the Rhino file (note that you do not need to input
quotations). If no text is input here, the default will be an image of the active viewport (or
the last viewport in which you navigated).
imageWidth [Optional]
The width of the image that you would like to take in pixels. If no value is provided here,
the component will set the width to that of the active Rhino viewport on your screen.
imageHeight [Optional]
The height of the image that you would like to take in pixels. If no value is provided
here, the component will set the height to that of the active Rhino viewport on your
screen.
displayMode [Optional]
The display mode of the viewport that you would like to take an image of. Acceptable
inputs include "Wireframe", "Shaded", "Rendered", "Ghosted", "X-Ray", "Technical",
"Atristic", and "Pen". If no text is input here, the default will be the displaymode of the
active viewport (or the last viewport in which you navigated).
keepAspectR [Optional]
Set to "True" to keep the aspect ratio of the viewport in the images that you save. By
default, this is set to "False" if you have connected an imageHeight_ but will override
this input to ensure correct aspect ratio if set to "True".
capture [Required]
Set to "True" to capture the image of the Rhino viewport and save it to your hard drive.
Capture_View
234
Ladybug Primer
Outputs
imagePath
The filepath of the image taken with this component.
Check Hydra Example Files for Capture View
Capture_View
235
Ladybug Primer
Orient to Camera
Use this component to generate a plane that is oriented perpendicular to the active Rhino
viewport camera direction and centered at an input initPosition point. This is useful for
orienting geometry Grasshopper to the Rhino viewport camera, which may help in
presenting certain Ladybug visualizations in Rhino. Connect a Grasshopper "Timer"
component to the refresh input of this component in order to get a real time update of the
oriented plane based on the Rhino viewport camera direction. -
Inputs
initPosition [Required]
Orient_to_Camera
236
Ladybug Primer
A point or list of points that will act as the origin9s0 of the plane(s) that will be
generated.
refresh [Optional]
Connect either a Grasshopper "button" component that will allow you to refresh the
plane orientation upon hitting the button or a Grasshopper "Timer" component to see
the plane update in real time as you navigate through the Rhino viewport.
Outputs
orientedToCam
A plane (or list of planes) for each _initPosition connected. All planes are oriented
perpendicular to the active Rhino viewport camera direction and are centered at
initPosition points.
Check Hydra Example Files for Orient to Camera
Orient_to_Camera
237
Ladybug Primer
Set the View
Use this component to set the camera location and direction for the Rhino "Perspective"
viewport. Here is the video that shows how it works: http://www.youtube.com/watch?
v=7Mmhz867zY8 -
Inputs
cameraLocation [Required]
A point representing the location of the viewport camera.
Set_the_View
238
Ladybug Primer
cameraDirection [Required]
A vector that represents the direction that the viewport camera should face.
uvLookAround [Optional]
Optional UV coordinates to tilt the viewport camera off from from the input
_cameraDirection. Values for UV coordinates must be between -1 and 1 and these
correspond to a tilt of 180 degrees in either direction. It is recommended that you use a
Grasshopper sliderMD comonent for input.
lensLength [Optional]
An optional float number that sets the lens length of the viewport camera.
Outputs
Check Hydra Example Files for Set the View
Set_the_View
239
Ladybug Primer
fly
Use Fly to cycle through all connected sliders. If no slider is connects it will cycle through all
the sliders in the document! Fly is originally posted as a code snippet by David Rutten. The
code has been modified by James Ramsedn and Mostapha Sadeghipour Roudsari.
-
Inputs
inputSliders [Required]
fly
240
Ladybug Primer
Script Variable _inputSliders

fly [Required]
Script Variable _fly
Outputs
Vviiiiiiiiiizzz
Output parameter Vviiiiiiiiiizzz
Check Hydra Example Files for fly
fly
241
Ladybug Primer
C2F
Use this component to convert temperatures from Celcius to Fahrenheit. -
Inputs
C [Required]
A temperature or list of temperatures in Celcius.
Outputs
C2F
242
Ladybug Primer
F
The input temperatures converted to Fahrenheit.
Check Hydra Example Files for C2F
C2F
243
Ladybug Primer
DOY_HOY
Use this component to calculate the day of the year and hour of the year from an input date
with a day of the month, month of the year and hour of the day. -
Inputs
days [Default]
A number (or list of numbers) between 1 and 31 that represents the day(s) of the month.
months [Default]
DOY_HOY
244
Ladybug Primer
A number (or list of numbers) between 1 and 12 that represents the month(s) of the
year.
hours [Default]
A number (or list of numbers) between 1 and 24 that represents the hour(s) of the day.
Outputs
HOY
The hour of the year on which the input date and time fall.
DOY
The day of the year on which the input date falls.
date
The input information written out as a full date and time text string.
Check Hydra Example Files for DOY_HOY
DOY_HOY
245
Ladybug Primer
Day_Month_Hour
Use this component to calculate date information from an hour of the year. Date information
includes the day of the month, the month of the year and the hour of the day. -
Inputs
HOY [Required]
Hour of the year
Outputs
Day_Month_Hour
246
Ladybug Primer
day
The day of the month on which the input HOY falls.
month
The month of the year on which the input HOY falls.
hour
The hour of the day on which the input HOY falls.
date
The input information written out as a full date and time text string.
Check Hydra Example Files for Day_Month_Hour
Day_Month_Hour
247
Ladybug Primer
F2C
Use this component to convert temperatures from Fahrenheit to Celcius. -
Inputs
F [Required]
A temperature or list of temperatures in Fahrenheit.
Outputs
F2C
248
Ladybug Primer
C
The input temperatures converted to Celcius.
Check Hydra Example Files for F2C
F2C
249
Ladybug Primer
Activities Met List
Provides a list of available activites and outputs the metabolic rate of that activity for use in
the Ladybug PMV comfort calculator.
Inputs
Check Hydra Example Files for Activities Met List
Activities_Met_List
250
Ladybug Primer
BTU2Wh
Use this component to convert energy values in BTU to Wh, kBTU to kWh, BTU/ft2 to
Wh/m2, or kBTU/ft2 to kWh/m2. -
Inputs
BTU [Required]
An energy value or list of energy values in BTU, kBTU, BTU/ft2, or kBTU/ft2. Note that,
for the component to recognize flux (division by ft2), the input must have a Ladybug
header.
BTU2Wh
251
Ladybug Primer
Outputs
Wh
The input enervy values converted to Wh, kWh, Wh/m2, or kWh/m2 (depeding on
input).
Check Hydra Example Files for BTU2Wh
BTU2Wh
252
Ladybug Primer
Use this component to combine two or more solar envelopes from Ladybug_SolarEnvelope
component -
Inputs
baseSrf [Required]
A surface representing the area for which you want to create the solar envelope (could
also be a closed planer curve). Must be the same as the _BaseSrf connected to the
solar Envelope component.
253
Ladybug Primer
envelopePts [Required]
A list of 3d points representing the heights to which the solar envelope reaches. Use the
envelopePts output from the solar envelope component.
HighestEnv [Optional]
if HighestEnv_ is True we'll take the highest points and if it's False we'll take the lowest
ones. Default value is True
gridSize [Required]
A numeric value inidcating the gird size of the analysis in Rhino model units. Muse be
the same as the gridSize_ value connected to the solar Envelope component.
Outputs
newEnvPoints
A list of 3d points representing the heights to which the solar envelope reaches. Plug
into a native GH 'Delunay Mesh' component to visualize the full solar envelope.
envelopeBrep
Brep representing the envelope.
Check Hydra Example Files for CombineSolarEnvelopes
254
Ladybug Primer
Comfort Mannequin
Use this component to color a mannequin based on their relation to a comfort temperature. -
Inputs
ambientTemperature [Required]
The temperture around the mannequin, which can be either UTCI (outdoor comfort),
Standard Effective Temperature (PMV comfort), or Operative Temperature (Adaptive
Comfort).
Comfort_Mannequin
255
Ladybug Primer
targetTemperature [Optional]
The target comfort temperature that the mannequin wants to be at. The default is set to
20C
comfortRange [Optional]
The number of degrees above and below the target temperture that the subject will still
find comfortable. The default is set to 3C, which is pretty common for many comfort
metrics.
bodyPosture [Optional]
An interger to set the posture of the comfort mannequin, which can have a large effect
on the radiation striking the mannequin. 0 = Standing, 1 = Sitting, and 2 = Lying Down.
The default is set to 1 for sitting.
rotationAngle [Optional]
An optional rotation angle in degrees. Use this number to adjust the angle of the comfort
mannequin in space. The angle of the mannequin in relation to the sun can have a large
effect on the amount of radiation that falls on it and thus largely affect the resulting
mean radiant temperature.
bodyLocation [Optional]
An optional point that sets the position of the comfort mannequin in space. Use this to
move the comfort mannequin around in relation to contextShading_ connected below.
The default is set to the Rhino origin.
Outputs
mannequinMesh
A colored mesh of a comfort mannequin showing the amount of radiation falling over the
mannequin's body.
legend
A legend that corresponds to the colors on the mannequinMesh and shows the relative
W/m2.
Comfort_Mannequin
256
Ladybug Primer
legendBasePt
Check Hydra Example Files for Comfort Mannequin
Comfort_Mannequin
257
Ladybug Primer
Construct Time
Use this component to construct a specific hour from corresponding time in hours, minutes
and seconds. The output can be plugged into the analysisPeriod or sunPath components. -
Inputs
hour [Default]
A number between 1 and 23 representing the hour of the day.
minutes [Default]
Construct_Time
258
Ladybug Primer
A number between 1 and 60 representing the minute of the hour.

seconds [Default]
A number between 1 and 60 representing the second of the minute.
Outputs
hour
An output hour that an be plugged into the analysisPeriod or sunPath components.
Check Hydra Example Files for Construct Time
Construct_Time
259
Ladybug Primer
Create Legend
Use this component to create a custom legend for any set of data or to create a more
flexible legend for any ladybug component with a legend. Specifically, this component
outputs data that can be plugged into the grasshopper "Text Tag 3D" component so that the
legend text can be baked into the Rhino scene as actual text instead of surfaces
representing text. -
Inputs
valuesOrRange [Required]
Create_Legend
260
Ladybug Primer
The list of numerical data that the legend refers to (or just the minimum and maximum
numerical values of this data). If the original numerical data is hooked up, the legend's
maximum and minimum values will be set by the max and min of the data set.
legendBasePt [Optional]
An optional point to set the location of the legend. This can be the output legendBasePt
of any of the Ladybug components that have a legend. If a point is hooked up here and
another point is hooked up at a legendPar component that is connected to this one, the
point on the legendPar component will override the input point here.
legendTitle [Optional]
A text string representing a legend title. Legends are usually titled with the units of the
data. If no text is provided here, the default title will read "unkown units."
legendSize [Optional]
The initial size of a single colored cell of the legend mesh, which determines the size of
the whole legend. This should be a numerical value corresponding to the length of a
legend cell in Rhino model units. The default is set to 10 Rhino units.
Outputs
legendMesh
A colored mesh that corresponds to the input _valuesOrRange. Connect this output to a
grasshopper "Mesh" component in order to preview this separately in the Rhino scene.
legendTextSrf
A list of surfaces representing the text labels of the legend. These surfaces will reflect
the font and size input to the legendPar.
legendBasePt
The legend base point, which can be used to move the legend with the grasshopper
"move" component.
textValuesBasePts
The base points that correspond to the title text and numerical value text of the legend.
Create_Legend
261
Ladybug Primer
Plug this into the "Location" input of the grasshopper "Text Tag 3D" component in order
to display as text in Rhino.
legendTextValues
The text strings that correspond to the title and numerical values of the legend. Plug this
into the "Text" input of the grasshopper "Text Tag 3D" component in order to display as
text in Rhino.
recommendedTextSize
Values representing recommended text sizes that correspond to the title and numerical
values of the legend. These values are generated based on the legend size and scale.
Plug this into the "Size" input of the grasshopper "Text Tag 3D" component in order to
display as text in Rhino.
Check Hydra Example Files for Create Legend
Create_Legend
262
Ladybug Primer
L2G
Use this component to convert the liquid volume from Liters to U.S. Gallons (not Imperial
Gallons). -
Inputs
L [Required]
A value or list of values in Liters.
Outputs
L2G
263
Ladybug Primer
G
Input volume converted to U.S. Gallons.
Check Hydra Example Files for L2G
L2G
264
Ladybug Primer
Orientation Study Parameters
Use this component with the Ladybug "Radiation Analysis", "Sunlight Hours Analysis", or
"View Analysis" component to set up the parameters for an Orientation Study. You can use
an Orientation Study to answer questions like "What orientation of my building will give me
the highest or lowest radiation gain for my analysis period?" Another question might be
"What direction should I orient my static solar panel to get the maximum radiation during my
analysis period?" An Orientation Study will automatically rotate your geometry around
several times based on the inputs made to this component and the results will be recorded
in the corresponding Analysis component that this one is hooked up to. -
Inputs
265
Ladybug Primer
divisionAngle [Required]
A number between 0 and 180 that represents the degrees to rotate the geometry for
each step of the Orientation Study.
totalAngle [Required]
A number between 0 and 360 that represents the degrees of the total rotation that the
geometry will undergo over the course of the Orientation Study. This _totalAngle should
be larger than the _divisionAngle and divisible by the _divisionAngle.
Input a point here to change the center about which the Orientation Study will rotate the
geometry. If no point is connected, the default point of rotation will be the center of the
test geometry.
rotateContext [Optional]
Input either a Boolean value or a set of context Breps that should be rotated along with
the test geometry. If set this input to "True", all context Breps will be rotated with the test
geometry. The default is set to "False" to only rotate the test geometry.
runTheStudy [Required]
[Boolean or GeometryBase] Since orientation study may take a long time, this is an
extra confirmation request to make sure that you really want to run the oriantation study!
[courtesy of Windows Vista...;)] If you want part of the context to roatate with the test
geometry the connect it here!
Outputs
orientationStudyPar
A list of Orientation Study parameters that can be plugged into the Ladybug "Radiation
Analysis", "Sunlight Hours Analysis", or "View Analysis" component.
Check Hydra Example Files for Orientation Study Parameters
266
Ladybug Primer
Passive Strategy Parameters
Use this component to adjust the assumptions of the passive strategies that can be overalid
on the Ladybug the Psychrometric Chart. The default assumptions of each of the strategies
are as follows: Evaporative Cooling - This polygon represents the conditions under which
direct evaporative cooling would be helpful. As such, it takes as its upper limit the line of
constant enthalpy from the edge of the comfort polygon and includes all warm temperatures
below it. If the user has set a minimum humidity tolerance, the polygon will also include the
points beneath the comfort polygon as it is assumed that the evaporation of water will both
humidify and cool the air. Nothe that this direct evaporative cooling polygon is slightly
different than 2-stage evaporative cooling. Thermal Mass + Night Flush - The polygon
represents the conditions under which shaded, night-flushed thermal mass can keep
267
Ladybug Primer
occupants cool. By default, this polygon assumes that temperatures can get as high as 16.7
C above the max temperature of the comfort polygon as long temperatures 12 hours before
the hot period are 2.8 C lower than the max temperture of the comfort polygon. This
parameter component can be used to adjust these two numbers. The thermal mass polygon
is limited in terms of humidity in that it obeys any limits on absolute humidity that the comfort
polygon dies. Occupant Use of Fans - This polygon is made by assuming that a wind speed
of 1.5 m/s is the maximum speed tolerable before it starts blowing papers and becomes
annoying to occupants. This strategy parameters component can be used to adjust this
maximum acceptable wind speed. As such, the polygon is determined by running a PMV
model with this wind speed and the input rad temp, met rate and clo level of the psych chart.
This component obeys any limits on humidity that the comfort polygon does. Note that this
polygon assumes that you are already naturally ventilating and that your natural ventilation
period is defined by your comfort polygon. Internal Heat Gain - The component assumes a
minimum building balance point of 12.8 C and any conditions that are warmer than that (up
to the comfort polygon) will keep occupants comfortable. It is assumed that, above this
outdoor temperature, the building is free-running and occupants are able to open windows
as they wish. Note that this balance temperature of 12.8 is fairly low and assumes a large
number of inside heat sources or people as well as in insulated envelope. This balance
temperature can be adjusted with this strategyPar component. _ Dessicant Dehumidification
- This polygon represents the conditions under which dessicant dehumidification would be
helpful. As such, it takes as its upper limit the line of constant enthalpy from the edge of the
comfort polygon and includes all humid conditions below it. Note that this polygon does not
appear if there is no upper humidity limit on the comfort polygon. -
Inputs
maxTempAboveComf [Optional]
An optional number in degrees C representing the maximum daily temperature above
the comfort range which can still be counted in the Thermal Mass + Night Flush
polygon. The default is set to 16.7 C above the highest comfort temperature.
minNightDiffBelowComf [Optional]
An optional number in degrees C representing the minimum temperature below the
maximum comfort temperature that the outdoor temperature must drop at night in order
to count towards the Thermal Mass + Night Flush polygon. The default is set to 2.8 C.
maxComfortableAirSpeed [Optional]
An optional number in m/s that represents the maximum winds speed tolerable before it
starts blowing papers and becomes annoying to occupants. This is used to shape the
268
Ladybug Primer
"Occupant Use of Fans" Polygon and the default is set ot 1.5 m/s.
lowestBldgBalancePt [Optional]
An optional number representing the building balance point, which will be used to shape
the "Internal Heat Gain" strategy polygon. The default is set to 12.8 C and it is assumed
that, above this outdoor temperature, the building is free-running and occupants are
able to open windows as they wish. Note that this default balance temperature of 12.8 is
fairly low and assumes a large number of inside heat sources or people as well as in
insulated envelope.
Outputs
strategyPar
Passive strategy parameters that can be plugged into the "Ladybug_Psychrometric
Chart" to adjust the assumptions of the passive strategy polygons.
Check Hydra Example Files for Passive Strategy Parameters
269
Ladybug Primer
Shading Parameters List
Use this component to generate shading depths, numbers of shades, horizontal or vertical
boolean values, and shade angles for different cardinal directions to be plugged into the
"Ladybug_Shading Designer" component or the "Honeybee_EnergyPlus Window Shade
Generator". -
Inputs
northShdParam [Default]
Shading parameter for north-facing glazing.
270
Ladybug Primer
westShdParam [Default]
Shading parameter for west-facing glazing.
southShdParam [Default]
Shading parameter for south-facing glazing.
eastShdParam [Default]
Shading parameter for east-facing glazing.
Outputs
shdParamList
A list of shading parameters for different cardinal directions to be plugged into either the
input of the "ShadingDesigner" component or the "HoneybeeEnergyPlus Window Shade
Generator". Depending on the type of values that you input, these can go into either of
these inputs: _depth, _numOfShds, _distBetween, _horOrVertical, shdAngle.
Check Hydra Example Files for Shading Parameters List
271
Ladybug Primer
Wh2BTU
Use this component to convert energy values in Wh to BTU, kWh to kBTU, Wh/m2 to
BTU/ft2, or kWh/m2 to kBTU/ft2. -
Inputs
Wh [Required]
An energy value or list of energy values in Wh, kWh, Wh/m2, kWh/m2. Note that, for the
component to recognize flux (division by m2), the input must have a Ladybug header.
Wh2BTU
272
Ladybug Primer
Outputs
BTU
The input enervy values converted to BTU, kBTU, BTU/ft2, or kBTU/ft2 (depeding on
input).
Check Hydra Example Files for Wh2BTU
Wh2BTU
273
Ladybug Primer
Wh2kWh
Use this component to convert energy values in W to kW, W/m2 to kW/m2, Wh to kWh,
Wh/m2 to kWh/m2, BTU to kBTU, or BTU/ft2 to kBTU/ft2. -
Inputs
Wh [Required]
An energy value or list of energy values in W, W/m2, Wh, Wh/m2, BTU, or BTU/ft2.
Outputs
Wh2kWh
274
Ladybug Primer
kWh
input).
Check Hydra Example Files for Wh2kWh
Wh2kWh
275
Ladybug Primer
kWh2Wh
Use this component to convert energy values in kW to W, kW/m2 to W/m2, kWh to Wh,
kWh/m2 to Wh/m2, kBTU to BTU, or kBTU/ft2 to BTU/ft2. -
Inputs
kWh [Required]
An energy value or list of energy values in Wh, kWh, Wh/m2, kWh/m2. Note that, for the
component to recognize flux (division by m2), the input must have a Ladybug header.
kWh2Wh
276
Ladybug Primer
Outputs
Wh
input).
Check Hydra Example Files for kWh2Wh
kWh2Wh
277
Ladybug Primer
ms2mph
Convert from m/s to mile/h -
Inputs
ms []
Input wind speed in meters per second
Outputs
ms2mph
278
Ladybug Primer
mph
Output wind speed in miles per hour
Check Hydra Example Files for ms2mph
ms2mph
279
Ladybug Primer
rIP2rSI
Use this component to convert R-Values in IP (hft2F/BTU) to R-Values in SI (Km2/W) to

plug into any of the Honeybee material components. -
Inputs
R_IP [Required]
A R-Value in IP (hft2F/BTU).
Outputs
rIP2rSI
280
Ladybug Primer
R_SI
The R-Value in SI (Km2/W).
Check Hydra Example Files for rIP2rSI
rIP2rSI
281
Ladybug Primer
uIP2uSI
Use this component to convert U-Values in IP (BTU/hft2F) to U-Values in SI (W/Km2) to

plug into any of the Honeybee material components. -
Inputs
U_IP [Required]
An R-Values in IP (hft2F/BTU).
Outputs
uIP2uSI
282
Ladybug Primer
U_SI
The R-Value in SI (Km2/W).
Check Hydra Example Files for uIP2uSI
uIP2uSI
283
Ladybug Primer
Component list:
Export_Ladybug
Update_Ladybug
5 | Developers
284
Ladybug Primer
Export Ladybug
Code Developers of Ladybug and Honeybee can use this component to export
Ladybug/Honeybee user objects and source code that they create to the Github folder on
their computer. This eases and automates the steps before commiting new components to
the Github. This component was written thanks to Giulio Piacentino a really helpful example.
-
Inputs
components [Required]
Export_Ladybug
285
Ladybug Primer
Any output from a new Ladybug (or Honeybee) component that you wish to export.
Right now, only one component can be connected at a time but you can input a "*"
(without quotation marsk) to search all changed Ladybug components on a grasshopper
canvas.
targetFolder [Required]
A file path on your system which you would like to export the user object and source
code to. For most code developers, this file path will lead to their Github folder for
Ladybug (or Honeybee), which is usually installed in "My Documents" by default.
Exported source code will be saved at .\src and exported userObjects will be saved at
.\userObjects in this _targetFolder.
export [Required]
Set to "True" to export Ladybug (or Honeybee) components to the _targerFolder.
Outputs
readMe!
...
Check Hydra Example Files for Export Ladybug
Export_Ladybug
286
Ladybug Primer
Update Ladybug
Code Developers and Beta Testers of new Ladybug components can use this component to
remove old Ladybug components, add new Ladybug components, and update existing
Ladybug components from a synced Github folder on their computer. This component can
also update outdated Ladybug components in an old Grasshopper file so long as the
updates to the components do not involve new inputs or outputs. -
Inputs
sourceDirectory [Optional]
Update_Ladybug
287
Ladybug Primer
An optional address to a folder on your computer that contains the updated Ladybug
userObjects. If no input is provided here, the component will download the latest version
from GitHUB.
updateThisFile [Required]
Set to "True" if you want this component to search through the current Grasshopper file
and update Ladybug components that have changed.
updateAllUObjects [Required]
Set to "True" to sync all the Ladybug and Honeybee userObjects in your Grasshopper
folder with the GitHUB.
Outputs
readMe!
...
Check Hydra Example Files for Update Ladybug
Update_Ladybug
288
Ladybug Primer
Component list:
Bioclimatic_Chart
Shadow_Study
PV_SWH_System_Size
Shading_Mask
Shading_Mask_II
6 | WIP
289
Ladybug Primer
Bioclimatic Chart
This is the Bioclimactic Chart. It is based in the originally proposed chart by V. Olgyay and
then in the chart presented in the book "Sun, Climate and Architecture" by Brown. Use this
component to draw a Bioclimatic chart in the Rhino scene and evaluate a set of
temperatures and humidity ratios in terms of indoor comfort. Connected data can include
either outdoor temperature and humidty ratios from imported EPW weather data, indoor
temperature and humidity ratios from an energy simulation, or indivdual numerical inputs of
temperature and humidity. The input data will be plotted alongside polygons on the chart
representing comfort as well as polygons representing the efects of passive building
strategies on comfort. References:
Bioclimatic_Chart
290
Ladybug Primer
1. Olgyay, V., 1963. Design with Climate. Bioclimatic Approach to Architectural Regionalism. Van Nos
2. Givoni B., 1976. Man, Climate and Architecture. Applied Science Publishers, Ltd., London.
3. Murray M. and Givoni B., 1979. Architectural Design Based on Climate in Watson D. (ed), 1979. Ene
4. Yezioro, A. & E. Shaviv. 1996. A Knowledge Based CAD System for Determining Thermal Comfort Desig
5. Brown G.Z. and DeKay M., 2001. Sun, WInd & Light. Architectural Design Strategies (2nd edition).
Inputs
direct output of dryBulbTemperature from the Import EPW component. Indoor
temperatures from Honeybee energy simulations are also possible inputs.
component.
as 2 to 4 clo.
passiveStrategy [Optional]
Bioclimatic_Chart
291
Ladybug Primer
An optional text input of passive strategies to be laid over the Bioclimatic chart as
polygons. Text inputs include "Passive Solar Heating", "Evaporative Cooling", "Thermal
Mass + Night Vent" and "Natural Ventilation". NOT WORKING RIGHT NOW!!
cullMesh [Optional]
Set to "True" to cull the colored mesh to where they have climatic data on them. See
chartMesh output. Deafult "False"
calculateCharts [Optional]
Set to "True" to calculate and show a column type graph showing the percentage of
time each strategy is capable of providing comfort conditions. See resultsChart output.
Deafult "False"
analysisPeriodWinter [Optional]
will be run for the enitre year. ONLY WORKS FOR THE WHOLE YEAR RIGHT NOW!!
analysisPeriodSummer [Optional]
will be run for the enitre year. ONLY WORKS FOR THE WHOLE YEAR RIGHT NOW!!
An optional base point that will be used to place the Bioclimatic Chart in the Rhino
scene. If no base point is provided, the base point will be the Rhino model origin.
scale [Optional]
An optional number to change the scale of the Bioclimatic chart in the Rhino scene. By
default, this value is set to 1.
runIt [Required]
Set to "True" to run the component and calculate the adaptive comfort metrics.
Outputs
Bioclimatic_Chart
292
Ladybug Primer
readMe!
...
comfortResults
The number of hours and percent of the input data that are inside all comfort and
passive strategy polygons.
totalComfortOrNot
A list of 0's and 1's indicating, for each hour of the input data, if the hour is inside a
comfort and/or strategy polygon (1) or not(0).
strategyOrNot
A list of 0's and 1's indicating, for each hour of the input temperature and humidity ratio,
if the hour is inside (1) or not(0), for each passive strategy and comfort polygons. If
there are multiple comfort polyogns or passive strategies connected to the
passiveStrategy_ input, this output will be a grafted list for each polygon.
chartGridAndTxt
The grid and text labels of the Bioclimatic chart.
chartMesh
A colored mesh showing the number of input hours happen in each part of the
Bioclimatic chart.
legendChartMesh
Script variable BioclimacticChart
chartHourPoints
Points representing each of the hours of input temperature and humidity ratio. By
preview component.
hourPointColorsByComfort
Color the chartHourPoints above according to Comfort results. They can be hooked up
to the "Swatch" input of a Grasshopper Preview component that has the hour points
above connected as geometry. By default, points are colored red if they lie inside
comfort or strategy polygons and are colored blue if they do not meet such comfort
Bioclimatic_Chart
293
Ladybug Primer
criteria.
hourPointColorsByMonth
Colors that the chartHourPoints above according to each month. They can be hooked
up to the "Swatch" input of a Grasshopper Preview component that has the hour points
above connected as geometry. By default, points are colored red if they lie inside
comfort or strategy polygons and are colored blue if they do not meet such comfort
criteria.
min_maxPoints
Plot each month's Minimal/Maximal values for Temperature and Relative Humidity. By
preview component.
comfort_strategyPolygons
A tree of polygons representing the comfort and passive strategies areas of the chart
made comfortable.
legendComfortStrategies
A colored legend showing the number of hours that correspond to each color for the
chartMesh output.
legendBasePt
resultsChart
A column type graph showing the percentage of time each strategy is capable of
providing comfort conditions. These results are summarizing the whole year and each
month. Each column shows three areas: Comfort Zone (black), Passive Solar Heating
(yellow), as the only heating strategy for winter time Evaporative Cooling or High Termal
Mass with Night Ventilation or Natural Ventilation (green, red, blue) as the possible
cooling strategies for summer time.
Check Hydra Example Files for Bioclimatic Chart
Bioclimatic_Chart
294
Ladybug Primer
Shadow Study
Use this component to generate outline curves representing shadows cast by input
_geometry for a given _sunVector. Note that, to see shadows cast onto a ground, a surface
representing the ground plane must be included in the input _geometry. Also, please note
that, for a list of input _geometry that is larger than 4 or 5 breps, the calculation time of this
component can be very long. Please keep the input geometry to small lists or be prepared to
wait a long time. WARNING: This component is a proof of concept that will not work in every
situation. It is not ideal for analyzing curved surfaces and it is not able to calculate shadows
for geometries that are intersecting each other. -
Inputs
Shadow_Study
295
Ladybug Primer
geometry [Required]
Breps representig test geometries that will cast shadows on each other.
sunVector [Required]
A sun vector from the Ladybug sunPath component.
Outputs
readMe!
...
shadow
Outline curves representing the shadows cast by the individual input Breps on other
input Breps. Note that, if all input _geometry is planar, this output can be hooked up to a
Grasshopper "Brep" component to give Breps representing shadows cast.
shade
Outline curves representing the the parts of individual input Breps that are not in the
sun. In other words, this is the self-shaded part of the Breps. Note that, if all input
_geometry is planar, this output can be hooked up to a Grasshopper "Brep" component
to give Breps representing self-shaded areas.
Check Hydra Example Files for Shadow Study
Shadow_Study
296
Ladybug Primer
PV SWH System Size
Use this component to generate the PVsurface or SWHsurface for "Photovoltaics surface" or
"Solar Water Heating surface" components, based on initial PV or SWH system sizes. -
Inputs
location [Required]
The output from the "importEPW" or "constructLocation" component. This is essentially
a list of text summarizing a location on the earth.
PV_SWH_System_Size
297
Ladybug Primer
PVmoduleSettings [Required]
A list of PV module settings. Use the "Photovoltaics Module" component to generate
them.
SWHsystemSettings [Required]
A list of all SWH system settings. Use the "Solar Water Heating System" or "Solar Water
Heating System Detailed" components to generate them.
systemSize [Optional]
1) In case of PV array: DC (Direct current) power rating of the photovoltaic array in
kilowatts (kW) at standard test conditions (STC). 2) In case of SWH array: Capacity of
the collectors array in thermal kilowatts (kw) at global or local testing conditions (ISO
9806, EN 12975, ASHRAE 93 ...) - If not supplied, 4 kW will be used as a default. - In
kiloWatts (kW) or thermal kiloWatts (kWt).
arrayTiltAngle [Optional]
An angle from horizontal of the inclination of the PV/SWH array plane. Example: 0 =
horizontal, 90 = vertical. (range 0-180) - To get the maximal amount of energy, input the
"optimalTilt" output from "Tilt And Orientation Factor"'s component. - If not supplied,
location's latitude will be used as default value. - In degrees ().
arrayAzimuthAngle [Optional]
The orientation angle (clockwise from the true north) of the PV/SWH array plane's
normal vector. (range 0-360) - To get the maximal amount of energy, input the
"optimalAzimuth" output from "Tilt And Orientation Factor"'s component. - If not
supplied, the following values will be used as default: 180 (due south) for northern
hemisphere, 0 (due north) for southern hemisphere. - In degrees().
tiltedArrayHeight [Optional]
The height of the array, measured in the tilted plane. It is depends on the height/width of
the PV module/SWH collector. It also depends on the way modules/collectors are
positioned in PV/SWH array (vertically or horizontally). It can vary from 1 to 2.3 meters x
number of modules/collectors in a single PV/SWH column. - If not supplied, default
value of 1.6 meters (with a single PV module/SWH collector per row) will be used. - In
meters.
numberOfRows [Optional]
Number of rows to which PV or SWH array will be divided to. - If not supplied, 1 will be
PV_SWH_System_Size
298
Ladybug Primer
used as a default value (PV/SWH array will have only 1 row).

skewRowsDistance [Optional]
Distance in meters by which PV/SWH rows will be skewed. Use positive distance to
skew the rows to the left. And negative distance to skew the rows to the right. - It
requires the "numberOfRows_" to be larger than 1 in order to be able to skew the rows.
- If not supplied, 0 will be used as a default (no rows skewing).
minimalSpacingPeriod [Optional]
Analysis period for which the minimal spacing distance between PV modules/SWH
collector rows will derived of. In general this analysis period is taken from 9 to 15 hour
on a day at which sun is at its lowest position during a year. That is 21th December in
Northern and 21th June in Southern hemisphere (winter and summer solstice).
However, this may not be economical for locations with higher latitudes due to low
electricity generation during December/June. - So the following
"minimalSpacingPeriod_" should be used based on location's latitude:
latitude <= 44: 21. December (northern hemisphere) / 21. June (southern
hemisphere). 9-15hours
latitude 44 - 53: 15. November or 15. January (northern hemisphere) / 15. May or
15. July (southern hemisphere). 9-15hours
latitude 53 - 57: 15. October or 15. February (northern hemisphere) / 15. April or
15. August (southern hemisphere). 9-15hours
latitude > 57: 15. September or 15. March (for both northern and southern
hemisphere). 9-15hours - It requires the "numberOfRows_" to be larger than 1 in
order visualize the minimal spacing between rows. - If not supplied, it will be
calculated based on upper mentioned criteria.
baseSurface [Optional]
Surface on which PV/SWH array will be laid onto. This can be a surface of an angled or
flat roof. Or an angled or flat terrain. A facade of a building etc. - If not supplied, a
regular horizontal surface in Rhino's XY plane will be used, as a default.
arrayOriginPt [Optional]
UV coordinate of baseSurface_ at which PV_SWH array will start. It ranges from 0 to
1.0 for both U and V coordinate. Use grasshopper's "Construct Point" or "MD slider"
components to input it. - If not supplied, (0.5,0,0) will be used as a default value.
arrayOriginCorner [Optional]
Corner at which the PV/SWH array begins: - 0 - center bottom 1 - left bottom 2 - right
PV_SWH_System_Size
299
Ladybug Primer
bottom - If not supplied, 0 will be used as a default (bottom center).

north [Optional]
energyLoadPerHour [Optional]
A list of energy load values for each hour, during a year. 1) In case of PV array:
Electrical energy used for any kind of load: heating, cooling, electric lights, solar water
heating circulation pump etc. Use Honeybee "Read EP Result" component or any other
one to generate it. - 2) In case of SWH array: Thermal heating energy (or electrical
energy) required to heat domestic hot water and/or space heating load and/or space
cooling load. Use Ladybug "Domestic hot water" or "Hot water" components to calculate
it. - The purpose of this input is to divide the energy loads to each PV/SWH array rows. If not inputted, "energyLoadPerRowPerHour" output will not be calculated.
Outputs
readMe!
...
PV_SWHsurface
Surfaces on which PV modules/SWH collectors will be laid on.
PV_SWHsurfacesArea
Total area of the PV_SWHsurfaces. - In Rhino documents units (meters, centimeters,
feets...).
minimalSpacingDate
Exact date taken from "minimalSpacingPeriod_" input for which minimal spacing
between rows has been calculated.
arrayOriginPt
Origin point of the PV / SWH array.
energyLoadPerRowPerHour
"energyLoadPerHour_" input's data divided to rows.
PV_SWH_System_Size
300
Ladybug Primer
Check Hydra Example Files for PV SWH System Size
PV_SWH_System_Size
301
Ladybug Primer
Photovoltaics Module
Use this component to define the Photovoltaics module settings. - If nothing inputed, the
following PV module settings will be used by default:
moduleType: Close (flush) roof mount
moduleEfficiency: 15%
temperatureCoefficient: -0.5 %/C
moduleActiveAreaPercent: 90% -
Inputs
302
Ladybug Primer
moduleType [Optional]
Module type and mounting configuration: - 0 = Glass/cell/polymer sheet, Insulated back
(pv curtain wall, pv skylights) 1 = Glass/cell/glass, Close (flush) roof mount (pv array
mounted parallel and relatively close to the plane of the roof (between 5 and 15
centimenters)) 2 = Glass/cell/polymer sheet, Open rack (ground mount array, flat/sloped
roof array that is tilted, pole-mount solar panels, solar carports, solar canopies) 3 =
Glass/cell/glass, Open rack (the same as upper "2" type, just with a glass on the back
part of the module). - If not supplied, default type: "Glass/cell/glass, Close (flush) roof
mount" (1) is used.
moduleEfficiency [Optional]
The ratio of electrical energy output from the PV module to input solar energy from the
sun. Current typical module efficiencies for crystalline silicon modules range from 1420% - If not defined, default value of 15(%) will be used. - In percent (%).
temperatureCoefficient [Optional]
A coefficient which accounts for the percentage the solar module's DC output power
decrease/increase for every degree Celsius the solar cells temperature rises
above/below 25C. - In general it ranges from -0.44 to -0.5 for crystaline silicon
modules. - If not supplied, -0.5 will be used as a default. - In %/C.
moduleActiveAreaPercent [Optional]
Percentage of the module's area excluding module framing and gaps between cells. - If
not supplied, default value of 90(%) will be used. - In percent (%).
Outputs
readMe!
...
PVmoduleSettings
A list of PV module settings. Plug it to "Photovoltaics surface" component's
"PVmoduleSettings_" input.
Check Hydra Example Files for Photovoltaics Module
303
Ladybug Primer
Cold Water Temperature
Use this component to calculate the cold (inlet, mains) water temperature, if water pipes are
burried undeground. Sources: http://www.energy.ca.gov/2013publications/CEC-400-2013003/CEC-400-2013-003-CMF-REV.pdf http://www.nrel.gov/docs/fy04osti/35917.pdf
http://www.retscreen.net/download.php/ang/120/0/Textbook_SWH.pdf -
Inputs
method [Optional]
A method by which the cold water temperature will be calculated: - 0 - Carslaw and
304
Ladybug Primer
Jaeger (used by DOE-2) 1 - Christensen and Burch (used by EnergyPlus) 2 - used by

RETScreen - If not supplied, method "1" (Christensen and Burch) will be used by
default.
Hourly Dry Bulb Temperature (air temperature). Import it from Ladybug "Import EPW"
component. - In C.
minimalTemperature [Optional]
The minimum cold temperature value. For example this input can be used to prevent
the water in your pipes from freezing, by limiting it to 1C (33.8F). - If not supplied,
default value 1 (C) will be used. - In C.
soilThermalDiffusivity [Optional]
The ability of a soil to conduct thermal energy relative to its ability to store thermal
energy. - This input is only important for method "0" !!! Soil type for method "1" is
unknown, and can not be changed. The "1" formula is derived from various field and soil
data accross USA. Soil type for method "2" is fixed to: wet clay soil, and can not be
changed. - Soil thermal diffusivity for particular types of soil (m2/s 10^(-7)): 2.4 - dry
sand 7.4 - wet sand 2.5 - dry clay 5.1 - wet clay 1.0 - dry peat 1.2 - wet peat 12.9 dense rock - If not supplied, default value 2.5 (dry clay) will be used. - In m2/s 10^(-7).
pipesDepth [Optional]
The soil depth at which cold water pipes are burried at. - This input is only important for
method "0" !!! Pipes depth range for method "1" is fixed from 0.3 to 1 meters (1 to 3.5
feet), and can not be changed. Pipes depth for method "2" is fixed to 2 meters, and can
not be changed. - If not supplied, default value of 1(m) will be used. - In meters.
Outputs
readMe!
...
coldWaterTemperaturePerHour
Cold water temperature for picked pipesDepth and soilThermalDiffusivity, for each hour
during a year. - In C.
avrJanuaryColdWaterTemperature
305
Ladybug Primer
Average January cold water temperature for picked pipesDepth and

soilThermalDiffusivity. Use it for "SWHsystem" component's
"avrJanuaryColdWaterTemperature_" input. - In C.
avrColdWaterTemperaturePerYear
Average annual cold water temperature for picked pipesDepth and
soilThermalDiffusivity. - In C.
Check Hydra Example Files for Cold Water Temperature
306
Ladybug Primer
Commercial Public Apartment Hot Water
Use this component to calculate domestic hot water consumption for each hour during a
year, for Commercial, Public and Apartment buildings. The following types of buildings are
supported: office
apartment house or multifamily building
hotel/motel
restaurants, cafeterias
drive-ins, grilles, luncheonettes, sandwich, snack shops
primary school
307
Ladybug Primer
junior and senior high school

men's dormitory
women's dormitory
hospital
nursing home
factory - Component based on paper: ASHRAE 2003 Applications Handbook (SI),
Chapter 49, Service water heating:
https://cours.etsmtl.ca/mec735/Documents/Notes_de_cours/2012/Hiver_2012/Service_
Water_heating_ASHRAE.pdf -
Inputs
epwFile [Required]
Input .epw file path by using grasshopper's "File Path" component.
buildingType [Required]
Choose the building type for which hot water consumption will be calculated: - 0 - office
1 - apartment house, with 20 or less apartments 2 - apartment house, from 21 to 49
apartments 3 - apartment house, from 50 to 74 apartments 4 - apartment house, from
75 to 99 apartments 5 - apartment house, from 100 to 199 apartments 6 - apartment
house, more than 200 apartments 7 - hotel/motel with 20 or less rooms 8 - hotel/motel
from 21 to 60 rooms 9 - hotel/motel from 61 to 99 rooms 10 - hotel/motel more than 100
rooms 11 - (full meal) restaurants, cafeterias 12 - drive-ins, grilles, luncheonettes,
sandwich, snack shops 13 - primary school 14 - junior and senior high school 15 men's dormitory 16 - women's dormitory 17 - hospital 18 - nursing home 19 - factory
numberOfUnits [Required]
Number of units for upper chosen "_buildingType". Represents the number of: apartment units: apartment houses
occupants: offices, elementary, junior, senior high schools, dormitories , hospitals,
factories
meals per day: (full meal) restaurants, cafeterias; drive-ins, grilles, luncheonettes,
sandwich, snack shops
beds: nursing homes
litersPerUnitPerDay [Optional]
Number of liters for a single unit and day, based on _buidlingType - office - 3.8
l/day/occupant apartment house, with 20 or less apartments - 170 l/day/apartment
apartment house, from 21 to 49 apartments - 159.2 l/day/apartment apartment house,
308
Ladybug Primer
from 50 to 74 apartments - 151.6 l/day/apartment apartment house, from 75 to 99

apartments - 144 l/day/apartment apartment house, from 100 to 199 apartments - 140.2
l/day/apartment apartment house, more than 200 apartments - 132.7 l/day/apartment
hotel/motel with 20 or less rooms - 98 l/day/room hotel/motel from 21 to 59 rooms - 75.8
l/day/room hotel/motel from 60 to 99 rooms - 53.1 l/day/room hotel/motel more than 100
rooms - 37.9 l/day/room (full meal) restaurants, cafeterias - 9.1 l/day/meal drive-in,
grille, luncheonette, sandwich, snack shop - 2.6 l/day/meal primary school - 2.3
l/day/pupil junior and senior high school - 6.8 l/day/pupil men's dormitory - 49.7
l/day/student women's dormitory - 46.6 l/day/student hospital - 160 l/day/patient nursing
home - 69.7 l/day/bed factory - 45 l/day/worker - If not supplied, it will be picked based
on chosen "_buildingType" and "_numberOfUnits" inputs.
occupancyStartingHour [Optional]
An hour (from 1 to 24) during a day at which the occupancy of the chosen _buildingType
starts: - office - 9 apartment house 7 hotel/motel 7 (full meal) restaurant, cafeteria - 7
drive-in, grill, luncheonette, sandwich, snack shop - 7 primary school - 9 junior and
senior high school - 9 men's dormitory - 8 women's dormitory - 8 hospital - 1 nursing
home - 1 factory - 1 - If not supplied, it will be picked based on chosen "_buildingType"
input.
occupancyDuration [Optional]
Number of adults (14 years and older) in household. - office - 9 apartment house - 15
hotel/motel - 8 (full meal) restaurant, cafeteria - 12 drive-in, grill, luncheonette,
sandwich, snack shop - 17 primary school - 7 junior and senior high school - 7 men's
dormitory - 15 women's dormitory - 15 hospital - 24 nursing home - 24 factory - 24 - If
not supplied, it will be picked based on chosen "_buildingType" input.
firstWeekStartDay [Optional]
Week day on which a year starts (1 - Monday, 2 - Tuesday, 3 - Wednesday...) - If not
supplied, default value: 1 will be used (year starts on Monday, 1st January).
weekendDays [Optional]
Define a list of two weekend (nonworking) days. Through out the World, countries have
different days as their weekend days: - Thursday and Friday (4,5) Friday and Saturday
(5,6) Saturday and Sunday (6,7) - If not supplied, Saturday and Sunday (6,7) will be
taken as a default weekend days.
holidayDays [Optional]
List of days (1 to 365) which are holiday (nonworking) days. - If not supplied, no holiday
309
Ladybug Primer
days will be used, with exception of "school" (_buildingType: 13 and 14) where summer,
winter and spring/autumn holidays will be applied. For northern hemisphere, USA
school holidays schedules have been taken as a default. For southern hemisphere,
Australian school holidays schedule have been taken as a default.
deliveryWaterTemperature [Optional]
Required water temperature. In Celsius It is recommended for delivery water
temperature to not be lower than 60C (140F) to avoid the risk of Legionella
pneumophila bacteria appearance. - If not supplied, default value: 60C (140F) will be
used. - In Celsius degrees.
coldWaterTemperaturePerHour [Optional]
Cold (inlet) water temperature supplied from public water system, for each hour during a
year. In Celsius. To calculate it, use the "coldWaterTemperaturePerHour" output of the
Ladybug "Cold Water Temperature" component. - If not supplied, it will be calculated
based on Christensen and Burch method (method 1 from "Cold Water Temperature"
component), with pipes depth from 0.3 to 1 meters, and unknown soil type. - In Celsius
degrees.
runIt [Required]
...
Outputs
readMe!
...
heatingLoadPerHour
Thermal energy (or electrical energy) required to heat the domestic hot water
consumption for each hour during a year. - In kWh.
hotWaterPerHour
Domestic hot water consumption for each hour during a year. - In L/h (Liters/hour).
hotWaterPerYear
Domestic hot water consumption for a whole year. - In L (Liters).
averageDailyHotWaterPerYear
310
Ladybug Primer
Average daily hot water consumption for a whole year. - In L/day (Liters/day).
maximumDailyConsumption
Maximal hot water consumption per day during a year. - In (L/day) Liters/day.
maximumConsumptionDay
Day with maximal hot water consumption.
minimumDailyConsumption
Minimal hot water consumption per day during a year. - In (L/day) Liters/day.
minimumConsumptionDay
Day with minimal hot water consumption.
Check Hydra Example Files for Commercial Public Apartment Hot Water
311
Ladybug Primer
Residential Hot Water
Use this component to calculate domestic hot water consumption for each hour during a
year, for a single family household (house). - Component based on paper: "Modeling
patterns of hot water use in households", Ernest Orlando Lawrence Berkeley National
Laboratory; Lutz, Liu, McMahon, Dunham, Shown, McGrue; Nov 1996:
http://ees.lbl.gov/sites/all/files/modeling_patterns_of_hot_water_use_in_households_lbl37805_rev.pdf -
Inputs
epwFile [Required]
312
Ladybug Primer
totalNumberOfPersons [Required]
Total number of persons in a household.
numberOfPreSchoolChildren [Optional]
Number of preschool children(0-5) in household. - If not supplied, default value: 0 (no
preschool children) will be used.
numberOfSchoolChildren [Optional]
Number of school age(6-13) children in household. - If not supplied, default value: 0 (no
school children) will be used.
numberOfAdults [Optional]
Number of adults (14 years and older) in household. - If not supplied, it will be equal to
_totalNumberOfPersons.
numberOfAdultsAtHome [Optional]
Number of adults that stay at home during a day. - If not supplied, default value: 0 (no
adults at home) will be used.
seniorOnly [Optional]
Senior only household. - If not supplied, default value: False (not senior only household)
will be used.
dishWasher [Optional]
A household owns a dish washer. - If not supplied, default value: True (a household
owns a dish washer) will be used.
clothsWasher [Optional]
A household owns a cloths washer. - If not supplied, default value: True (a household
owns a cloths washer) will be used.
payUtilityBill [Optional]
Household occupants pay a utility bill. Tenants who pay their own utility bills in general,
tend to spend less, then those who do not. - If not supplied, default value: True
(household occupants pay their utility bill) will be used.
313
Ladybug Primer
firstWeekStartDay [Optional]
A day of week on which a year starts (1 - Monday, 2 - Tuesday, 3 - Wednesday...) - If not
supplied, default value: 1 will be used (year starts on Monday, 1st January).
weekendDays [Optional]
Define a list of two weekend (nonworking) days. Through out the World, countries have
different days as their weekend days: - Thursday and Friday (4,5) Friday and Saturday
(5,6) Saturday and Sunday (6,7) - If not supplied, Saturday and Sunday (6,7) will be
taken as a default weekend days.
holidayDays [Optional]
List of days (1 to 365) which are holiday (nonworking) days. - Here is an example
holiday days list for August: 213, 214, 215, 216, 217, 218, 219, 220, 221, 222, 223, 224,
225, 226, 227, 228, 229, 230, 231, 232, 233, 234, 235, 236, 237, 238, 239, 240, 241,
242, 243 - If not supplied, no holiday days will be used.
Required (set) water temperature. It is recommended for delivery water temperature to
not be lower than 60C (140F) to avoid the risk of propagation of Legionella
pneumophila bacteria. - Electric water heater used as a default. - If not supplied, default
value: 60C (140F) will be used. - In Celsius degrees.
coldWaterTemperaturePerHour [Optional]
Cold (inlet) water temperature supplied from public water system, for each hour during a
year. In Celsius. To calculate it, use the "coldWaterTemperaturePerHour" output of the
Ladybug "Cold Water Temperature" component. - If not supplied, it will be calculated
based on Christensen and Burch method (method 1 from "Cold Water Temperature"
component), with pipes depth from 0.3 to 1 meters, and unknown soil type. - In Celsius
degrees.
runIt [Required]
...
Outputs
readMe!
...
314
Ladybug Primer
heatingLoadPerHour
Thermal energy (or electrical energy) required to heat the domestic hot water
consumption for each hour during a year. - In kWh.
hotWaterPerHour
Domestic hot water consumption for each hour during a year. - In L/h (Liters/hour).
hotWaterPerYear
Domestic hot water consumption for a whole year. - In L (Liters).
averageDailyHotWaterPerYear
Average daily hot water consumption for a whole year. - In L/day (Liters/day).
maximumDailyConsumption
Maximal hot water consumption per day during a year. - In (L/day) Liters/day.
maximumConsumptionDay
Day with maximal hot water consumption.
minimumDailyConsumption
Minimal hot water consumption per day during a year. - In (L/day) Liters/day.
minimumConsumptionDay
Day with minimal hot water consumption.
Check Hydra Example Files for Residential Hot Water
315
Ladybug Primer
Solar Water Heating Performance Metrics
Use this component to calculate various Solar water heating performance metrics. Also use
it to calculate the optimal SWH system size and tank storage volume. -
Inputs
SWHsurface [Required]
Use the same "_SWHsurface" you supplied to the "Solar Water Heating Surface"
component.
316
Ladybug Primer
SWHsurfacePercent [Optional]
The percentage of surface which will be used for SWH collectors (range 0-100). - There
are no general rules or codes which would limit the percentage of the roof(surface)
covered with SWH collectors. - If not supplied, default value of 100 (all surface area will
be covered in SWH collectors) is used. - In percent (%).
SWHsystemSettings [Optional]
A list of all Solar water heating system settings. Use the same "SWHsystemSettings_"
you supplied to the "Solar Water Heating Surface" component. - If not supplied, the
following swh system settings will be used by default:
glazed flat plate collectors
active
closed loop
pipe length: 20 meters
unshaded
heatingLoadPerHour [Required]
Use the same "_heatingLoadHour" you supplied to the "Solar Water Heating Surface"
component. - In kWh.
heatFromTankPerHour [Required]
Import "heatFromTankPerHour" output data from "Solar water heating surface"
heatFromAuxiliaryHeaterPerHour [Required]
Import "heatFromAuxiliaryHeaterPerHour" output data from "Solar water heating
surface" component. - In kWh.
pumpEnergyPerHour [Required]
Import "pumpEnergyPerHour" output data from "Solar water heating surface"
energyCostPerKWh [Optional]
The cost of one kilowatt hour in any currency unit (dollar, euro, yuan...) - If not supplied,
0.15 $/kWh will be used as default value. - In currency/kWh.
collectorEmbodiedEnergyPerM2 [Optional]
Energy necessary for product life-cycle of SWH collector per square meter. - If not
317
Ladybug Primer
supplied default value of 1135 (MJ/m2) for unglazed or glazed flat plate collector will be
used. - In MJ/m2 (megajoules per square meter).
tankEmbodiedEnergyPerL [Optional]
Energy necessary for product life-cycle of storage tank per liter. - If not supplied default
value of 20 (MJ/l) will be used. - In MJ/l (megajoules per liter).
collectorEmbodiedCO2PerM2 [Optional]
Carbon emissions produced during SWH collector's life-cycle per square meter.. - If not
supplied default value of 65.5 (kg CO2/m2) for unglazed or glazed flat plate collector will
be used. - In kg CO2/m2 (kilogram of CO2 per square meter).
tankEmbodiedCO2PerL [Optional]
Carbon emissions produced during storage tank's life-cycle per liter. - If not supplied
default value of 0.14 (kg CO2/l) for unglazed or glazed flat plate collector will be used. In kg CO2/l (kilogram of CO2 per liter).
collectorLifetime [Optional]
Life expectancy of a SWH collector. - If not supplied default value of 15 (years) will be
used. - In years.
tankLifetime [Optional]
Life expectancy of a storage tank. - If not supplied default value of 10 (years) will be
used. - In years.
optimal [Optional]
Set to "True" to calculate optimal system size and tank storage volume. - Larger system
sizes and tank volumes produce more energy, therefor cover more initial heating load,
which results in less usage of auxiliary energy. However, the larger the system size and
tank volume, more embodied energy is spent. In order to find an optimal system size
(total size of all collectors) and storage tank volume, life-cycle energy analysis is used to
acheive the maximal net energy saving of the swh system. The net energy saving of
swh system is the energy saving in kWh remained after an annualized embodied energy
(of collectors or storage tank) has been deducted from the operating energy saving of
swh system. This method of optimization is superior in comparison with other
simulation-based methods due to consideration of all energy performance stages
(production, operation, maintenance...). - This optimization method can be used to
account for capital costs, instead of embodied energy. This would account only for
318
Ladybug Primer
operation performance stage. In this case capital costs of collector/per square meter,
and tank/per liter would need to be inputted into: "collectorEmbodiedEnergyPerM2" and
"tankEmbodiedEnergyPerL" inputs. - Optimization analysis based on the law of
diminishing marginal utility: "A simplified method for optimal design of solar water
heating systems based on life-cycle energy analysis", Renewable Energy journal, Yan,
Wang, Ma, Shi, Vol 74, Feb 2015
www.sciencedirect.com/science/article/pii/S0960148114004807
runIt [Required]
...
Outputs
readMe!
...
optimalSystemSize
Optimal SWH system size (optimal total size of SWH collector's array) for a given
SWHsurface's tilt, array and "heatingLoadHour". Minimum SWH system size is 0.15
kWt. Input it to "systemSize" input of "PV SWH system size" component to see how
much area it would require. - To calculate it, set the "optimal_" input to "True". - In
thermal kiloWatts (kWt).
optimalTankSize
Solar water heating storage tank optimal size (volume). Minimum size is 100 liters. To
calculate it, set the "optimal_" input to "True". - In liters.
SEF
Solar Energy Factor - ratio of total energy provided by the swh system to auxiliary plus
parasitic (circulation pump) energy for a whole year. - Unitless.
SolarFractionPerMonth
Solar Fraction (or Solar Savings Fraction) - percentage of the heating load requirement
that is provided by a swh system for each month during a year. It ranges from 0 to
100%. - In percent (%).
SolarFractionPerYear
Solar Fraction (or Solar Savings Fraction) - percentage of the total heating load
319
Ladybug Primer
requirement that is provided by a swh system for a whole year. It ranges from 0 to
100%. - In percent (%).
energyValue
Total Energy value generated by SWH system for a whole year in currency unit (dollars,
euros, yuans...)
EROI
Energy Return On Investment - a comparison of the generated electricity to the amount
of primary energy used throughout the SWH collector's product life-cycle. - Unitless.
embodiedEnergy
Total energy necessary for an entire product life-cycle of SWH collectors and storage
tank. - In GJ (gigajoules).
embodiedCO2
Total carbon emissions produced during SWH collector and storage tank life-cycle. - In
tCO2 (tons of CO2).
CO2emissionRate
Also called Embodied GHG emissions or GHGEmissions. An index which shows how
effective a SWH system is in terms of global warming. It is used in comparison with
other fuels and technologies (Hydroelectricity(15), Wind(21), Nuclear(60), Geothermal
power(91), Natural gas(577), Oil(893), Coal(955) ...) - In gCO2/kWh.
EPBT
Energy PayBack Time - time it takes for SWH system to produce all the energy used
through-out its collector's product life-cycle. - In years.
Check Hydra Example Files for Solar Water Heating Performance Metrics
320
Ladybug Primer
Solar Water Heating Surface
Use this component to calculate amount of thermal energy that can be produced by a
surface if a certain percentage of it is covered with Solar water heating liquid collectors. The
thermal energy can then be used for domestic hot water, space heating or space cooling. Component based on: "Solar Engineering of Thermal Processes", John Wiley and Sons, J.
Duffie, W. Beckman, 4th ed., 2013. "Technical Manual for the SAM Solar Water Heating
Model", NREL, N. DiOrio, C. Christensen, J. Burch, A. Dobos, 2014. "A simplified method for
optimal design of solar water heating systems based on life-cycle energy analysis",
Renewable Energy journal, Yan, Wang, Ma, Shi, Vol 74, Feb 2015 http://www.wiley.com/WileyCDA/WileyTitle/productCd-0470873663.html
321
Ladybug Primer
https://sam.nrel.gov/system/tdf/SimpleSolarWaterHeatingModel_SAM_0.pdf?
file=1&type=node&id=69521
http://www.sciencedirect.com/science/article/pii/S0960148114004807 -
Inputs
epwFile [Required]
heatingLoadPerHour [Required]
Heating load in electrical energy for each hour during a year. In kWh. It represents
domestic hot water heating load. With added space heating and/or space cooling
heating loads. - To calculate domestic hot water heating load, use Ladybug "Residential
Hot Water" or "Commercial Public Apartment Hot Water" components. - Space heating
and space cooling loads can be inputted from Honeybee's "Read EP Result"
component. Divide each value of space heating load with 0.7, to account for
COP(coefficient of performance) of the heating system. Space cooling values do not
need to be divided with anything (COP = 1.0).
SWHsurface [Required]
Input planar Surface (not polysurface) on which the SWH collectors will be applied. If
you have a polysurface, explode it (using "Deconstruct Brep" component) and then feed
its Faces(F) output to _SWHsurface. Surface normal should be faced towards the sun.
Or create the Surface based on initial SWH system size by using "PV SWH system
size" component.
SWHsurfacePercent [Optional]
The percentage of surface which will be used for SWH collectors (range 0-100). - There
are no general rules or codes which would limit the percentage of the roof(surface)
covered with SWH collectors. - If not supplied, default value of 100 (all surface area will
be covered with SWH collectors) is used.
SWHsystemSettings [Optional]
A list of all Solar water heating system settings. Use the "Solar Water Heating System"
or "Solar Water Heating System Detailed" components to generate them. - If not
supplied, the following swh system settings will be used by default:
active
322
Ladybug Primer
closed loop
unshaded
north [Optional]
Input a vector to be used as a true North direction for the sun path, or a number
between 0 and 360 that represents the clockwise degrees off from the Y-axis to make
North. - If not supplied, default North direction will be set to the Y-axis (0 degrees).
albedo [Optional]
An optional list of hourly data from Ladybug's "Import epw" component (e.g.
dryBulbTemperature), which will be used for "conditionalStatement_".
This input allows users to calculate the Solar water heating surface component results
only for those annualHourlyData values which fit specific conditions or criteria. To use
this input correctly, hourly data, such as dryBulbTemperature or windSpeed, must be
plugged into the "annualHourlyData" input. The conditional statement input here should
be a valid condition statement in Python, such as "a>25" or "b<3" (without="" the=""
quotation="" marks).="" conditionalStatement_="" accepts="" "and"="" and="" "or"=""
operators.="" To="" visualize="" hourly="" data,="" English="" letters="" should="" be=""
used="" as="" variables,="" each="" letter="" alphabetically="" corresponds="" to=""
of="" lists="" (in="" their="" respective="" order):="" "a"="" always="" represents="" 1st=""
list,="" "b"="" 2nd="" etc.="" -="" For="" example,="" if="" you="" have="" an=""
dryBulbTemperature="" connected="" first="" windSpeed="" second="" list="" (both=""
annualHourlyData_="" input),="" want="" plot="" data="" for="" time="" period=""
when="" temperature="" is="" between="" 18C="" 23C,="" larger="" than="" 3m=""
s,="" written="" "183" (without the quotation marks). - This input can also be used for
analysis of drainback systems. Input a "dryBulbTemperature" data from "Import epw"
component into upper "annualHourlyData" input. Then input "a>5" to this
("conditionalStatement") input.
323
Ladybug Primer
runIt [Required]
...
Outputs
readMe!
...
heatFromTankPerHour
Thermal energy provided by the storage tank per each hour during a year. - In kWh.
heatFromTankPerYear
Total thermal energy provided by the storage tank for a whole year. - In kWh.
avrDailyheatFromTankPerYear
An average thermal energy provided by the storage tank per day for a whole year. - In
kWh/day.
heatFromAuxiliaryHeaterPerHour
Thermal energy provided and Electrical energy spent by an auxiliary heater per each
hour during a year. Electric auxiliary heater used. - In kWh.
dischargedHeatPerHour
Discharged surplus energy ("heat dump") per each hour during a year. It can be used to
heat a pool, hot tub, greenhouse or as snow-melt system (by using radiant floor tubing
bellow sidewalks, or radiatior beneath the entrance stairs). - In kWh.
pumpEnergyPerHour
Electrical energy spent by the circulation pump(s) per hour during a year. - In kWh.
tankWaterTemperaturePerHour
Tank water temperature per each hour during a year. - In C.
SWHsurfaceTiltAngle
The angle from horizontal of the inclination of the SWHsurface. Example: 0 = horizontal,
90 = vertical. It ranges from 0-180. - In degrees.
324
Ladybug Primer
SWHsurfaceAzimuthAngle
The orientation angle (clockwise from the true north) of the SWHsurface normal vector.
It ranges from 0-360. - In degrees.
systemSize
Rated SWH system size. - In kWt.
Check Hydra Example Files for Solar Water Heating Surface
325
Ladybug Primer
Solar Water Heating System
Use this component to define Solar water heating system settings. - If nothing inputed, the
following swh system will be used by default:
active
closed loop
1 story
unshaded -
Inputs
326
Ladybug Primer
collectorType [Optional]
Type of the collector. The following ones can be used: - 0 - unglazed flat plate Least
expensive. Mostly used for single home domestic how water heating and for heating
swimming pools. More cost efficient in tropical and subtropical environments. They can
also be used in moderate climates for seasonal usage. Can output water temperatures
up to 30C (86F). - 1 - glazed flat plate Less expensive. More cost efficient in warm and
mild-warm climates. But also used in temperate climates. Mostly used for single home
domestic how water heating, space heating and space cooling. And for heating
swimming pools. Can output water temperatures up to 60C (140F). - 2 - evacuated
tube The most expensive. More cost efficient in cold temperate and cold climates (with
low ambient temperature, for example: during winter) and during overcast skies.
Evacuated tube collectors (or concentrating collectors) are typically used for industrial
applications, or multi residential or commercial buildings for space heating and space
cooling. Can output water temperatures higher than 90C (194F) degrees, up to 177C
(350F). - - If not supplied, glazed flat plate collectors (1) will be used.
activeSWHsystem [Optional]
Define whether the swh system is active (pumped) or passive (not pumped). - 0 passive (not pumped) swh system Less expensive. More efficient in warm and mildwarm climates. Does not require electricity to operate. Is used for domestic hot water
heating and space heating of a single home. If positioned on a roof require putting a
storage tank above the collector, and therefor impose the roof construction to be able to
carry the weight of the storage tank. SWHsurface component supports passive swh
systems with auxiliary heater. - 1 - active (pumped) swh system More expensive. More
efficient in temperate and cold climates. Require electricity to operate and battery backup in case of power outage. Can be used for domestic hot water heating, space heating
and space cooling of a single home, building or several buildings (central heating). More
efficient in warm and mild-warm climates, where it rarely freezes - - If not supplied,
active (pumped) loop will be used.
openLoop [Optional]
Define whether the swh system has an open (indirect) or closed (indirect) solar loop. - 0
- closed (indirect) loop Usage of heatexchanger. Antifreeze is a working fluid. More
expensive. More efficient in temperate and cold climates where freezing may occur.
Also suitable for locations with hard water hardness (mineral content). - 1 - open (direct)
loop No usage of heatexchangers. Water is the working fluid. Less expensive. More
efficient in warm and mild-warm climates, where it rarely freezes (air temperature never
drops below 5C(41F) degrees). Only suitable for locations with low water hardness
(mineral content) otherwise limescale will form in solar collectors. - - If not supplied,
327
Ladybug Primer
closed (indirect) loop will be used.

numberOfStories [Optional]
Total number of stories plus basement (if there is a basement). This input is used to
calculate the total piping length in the solar loop, based on an assumption that the
storage tank will be located at the lowest story (basement or ground floor), and solar
collectors are located at the roof. - Example 1: a house with a ground floor, first floor
and a basement - has 3 stories total. Example 2: a house with a ground floor, first floor,
second floor and without a basement - has 3 stories total. - If sollar collectors are used
on a ground instead of roof, use the "Solar Water Heating System Detailed" component
instead of this one to enter the exact pipe length of the solar loop. - - If not supplied, "1"
story will be used as a default value (a house with only a ground floor, without a
basement).
skyViewFactor [Optional]
the parts of diffuse irradiance. It ranges from 0 to 1. Import it from "Sunpath shading"
component's "skyViewFactor" output. - If not supplied, 1 will be used as a default value
(SWHsurface is unshaded). - Unitless.
beamIndexPerHour [Optional]
from 0-1. Import it from "Sunpath shading" component's "beamIndexPerHour" output. If not supplied, a value of 1 for each hour during a year, will be used (SWHsurface is
unshaded). - Unitless.
Outputs
readMe!
...
SWHsystemSettings
A list of all Solar water heating system settings. Plug it to SWHsurface component's
"SWHsystemSettings_" input.
Check Hydra Example Files for Solar Water Heating System
328
Ladybug Primer
Solar Water Heating System Detailed
Use this component to define a detailed Solar water heating system settings. - If nothing
inputed, the following swh system will be used by default:
active
closed loop
unshaded -
Inputs
329
Ladybug Primer
collectorOpticalEfficiency [Optional]
Fr(tau alpha) Collector's optical efficiency coefficient. Also called Collector heat removal
factor. Varies based on collector's type. Some default values by type: - 0.87 - unglazed
flat plate 0.70 - glazed flat plate 0.50 - evacuated tube - If not supplied, default value
0.70 (glazed flat plate) will be used. - Unitless.
collectorThermalLoss [Optional]
(FrUL) Collector's thermal loss coefficient. Varies based on collector's type. Some
default values by type: - 21 - unglazed flat plate 4 - glazed flat plate 1.5 - evacuated
tube - If not supplied, default value 4 (glazed flat plate) will be used. - In W/m2/C.
collectorActiveAreaPercent [Optional]
Percentage of the collector's area excluding collector framing, lateral insulation, or gaps
between evacuated tubes... Also called aperture area. It ranges from 70 to 95%
depending on the type of collector. - If not supplied, default value of 90(%) will be used.
- In percent.
workingFluidHeatCapacity [Optional]
Specific heat of the working fluid. - If swh system is intended to be used in a nonfreezing or light freezing climate (tropical and subtropical regions), then water should be
used as a working fluid. The specific heat of water is: 4180 J/kg/C. - If swh system is
used in freezing climates (temperate, polar...), an antifreeze needs to be added to the
water. In most cases this is Propylen glycol, Ethylen glycol or Bio glycol added in certain
percentages to the water. Depending on the freezing temperatures of the climates, there
are the following specific heats of water-glycol mixtures: up to -10C: waterpropylenglycol 25%: 4080 J/kg/C. up to -10C: water-ethylenglycol 20%: 4020 J/kg/C.
up to -20C: water-propylenglycol 38%: 4000 J/kg/C. up to -20C: water-ethylenglycol
34%: 3840 J/kg/C. up to -30C: water-propylenglycol 47%: 3890 J/kg/C. up to -40C:
water-ethylenglycol 52%: 3560 J/kg/C. - If not supplied 3840 (water-ethylenglycol 34%)
J/kg/C will be used. - In J/kg/C.
flowRatePerM2 [Optional]
Test flow rate of working fluid through the collector per square meter of collector's area.
The higher the flow rate, the higher the collector efficiency is. On the other hand higher
flow rates require more pump power, larger pipe diameters and can cause erosion
corrosion. - If not supplied, a value of 0.012 kg/s/m2 will be used. - In kg/s/m2.
IAMcoefficient [Optional]
330
Ladybug Primer
Incidence angle modifier coefficient (bo) - Use this input to account for collector
efficiency losses due to different angles of incidence. Depends on the type of collector,
tilt angle... Some default values depending on the type of collector: - 0.1 - glazed flat
plate 0.1 - unglazed flat plate -0.05 - evacuated tube - If not supplied, 0.1 (glazed flat
plate) will be used. - Unitless.
skyViewFactor [Optional]
the parts of diffuse irradiance. It ranges from 0 to 1. Import it from "Sunpath shading"
component's "skyViewFactor" output. - If not supplied, 1 will be used as a default value
(SWHsurface is unshaded). - Unitless.
beamIndexPerHour [Optional]
from 0-1. Import it from "Sunpath shading" component's "beamIndexPerHour" output. If not supplied, a value of 1 for each hour during a year, will be used (SWHsurface is
unshaded). - Unitless.
maxWorkingTemperature [Optional]
Maximal working temperature of the tank storage. It is used to prevent the overheating
problems and damage of the swh system due to exceedance of allowable temperature
(and pressure) and appearance of fluid boiling. Depends on the quality of pipes, valves,
tank, working fluid type... Generally ranges from 93-99C. - If not supplied 95C (203F)
will be used. - In C.
dischargeTemperature [Optional]
Storage tank temperature at which the discharge of the excess heat and cold water
makeup stops. It is generally 2-3C degrees less than maximal working temperature. - If
not supplied maxWorkingTemperature-3C will be used. - In C.
Water heater lower thermostat setting. Depends on the type of usage of solar hot water
system. In Celsius For domestic hot water, it is recommended not be lower than 60C
(140F). For space heating, it varies from 33 to 82C (90 to 180F) depending on the
type (in-floor tubes, radiators/baseboards, heat exchanger inside a forced-air heater).
For space cooling it varies from 60 to 80C (140 to 176F) depending on the cooling
system used. - If not supplied, default value: 60C (140F) will be used. - In C.
avrJanuaryColdWaterTemperature [Optional]
331
Ladybug Primer
Average January cold water inlet temperature. This is the temperature of the water from
the local pipe grid. Input it from first item of "Cold Water Temperature" component's
"avrColdWaterTemperaturePerMonth" output. - If not supplied it will be calculated for the
following input data: method "1" (Christensen and Burch), pipes depth from 0.3 to 1
meters. - In C.
mechanicalRoomTemperature [Optional]
Temperature of the room where the storage tank will be located. This input accepts list
of values (8760 values or 8767 with heading included) or a single value. If you input a
single value, this means that for each 8760 hours during a year, the
mechanicalRoomTemperature will correspond to that inputted value. - In case your
storage tank is located outside, not inside the building (thermosyphon, ics-batch swh
systems or active swh systems), supply the "dryBulbTemperature" data from Ladybug's
"Import epw" component to "mechanicalRoomTemperature_" input. - If not supplied, a
value of 20C degrees will be used for each hour during a year (meaning: storage tank
is located inside the building). - In C.
pipeLength [Optional]
Total pipes length run in the solar loop. - If collectors are located on the roof: a rule of a
thumb is to add 10 meters for each story (basement is calculated as a story too) and
additionally 10 meters for the roof. For example: for a 3 story building with a basement
(basement, ground floor, first floor, second floor, roof), if storage tank is located in the
basement and collectors are on the roof, the piping length would be: 4 stories * 10m +
10m (on the roof) = 50m. - If collectors are located on the ground, one would have to
estimate the distance from the house to collectors and multiply it by 2 (supply pipes go
to collectors and return ones from them). - If nothing inputted, a default value of 20
meters will be used (Ground story house without a basement. Collectors are located on
a roof, the storage tank is at the ground story). - In meters.
pipeDiameter [Optional]
Average pipes inner diameter, in milimeters. Depends on overall collector area, working
fluid type, piping length... - If not supplied, for active swh systems, it will be calculated
as: (4 flowRatePerM2 collectorActiveArea / flowSpeed / pi), with flowSpeed assumed
to be 0.7 liters/sec. - For passive swh systems as: 1.5 times the value of upper formula.
- In millimetres.
pipeInsulationThickness [Optional]
Thickness of the pipes insulation, in milimeters. For pipes with insulation thermal
conductivity lower than 0.04 W/(m*K), based on pipeDiameter, the following insulation
332
Ladybug Primer
thicknesses can be used: - 20 mm - pipeDiameter < 22mm 25mm - pipeDiameter 22 to

28mm 30mm - pipeDiameter 28 to 42mm equal to pipeDiameter - pipeDiameter 42 to
100mm 100mm - pipeDiameter > 100mm - If not supplied, it will be calculate based on
pipeDiameter and upper criteria. - In millimetres.
pipeInsulationConductivity [Optional]
Pipe's insulation thermal conductivity (k value). Depends on the type of insulation
material used. Some common solar piping insulation materials are: - 0.33 - Polyethylene
(PEL) 0.04 - Glass wool 0.027 - Polyurethane (PUR) = 0.027 0.0245 - Ethylene
Propylene Diene Rubber (EPDM, EPT) 0.023 - Plyisocyanurate (PIR) = 0.023 - If not
supplied, 0.027 (Polyurethane) will be used as a default value. - In W/(m*C).
pumpPower [Optional]
Overall circulation pumps power. In SWH systems, there are typically two pumps: solar
and storage tank ones. - Circulation pumps power depends on SWH active area, flow
rate, working fluid, pipe length and its disposition... Generally they range from 30 W for
small swh system, up to a couple of hundreds for large ones (SWH active area > 30m2)
- In case of passive circulation (thermosyphon, ICS or batch systems), set the
pumpPower to 0. - If not supplied, it will be calculated based on SWHsurface active
area (that's "Surface active area" from SWHsurface component's "readMe!" output) and
pipeLength. - In Watts.
pumpEfficiency [Optional]
Circulation pumps efficiency (ni) - ratio between hydraulic and supplied, electrical
power. Ranges from 0.5 to 0.95 depending on the type, and size of the circulation
pump. - If not supplied, 0.85 will be used. - Unitless.
tankSize [Optional]
Storage tank volume in liters. It varies depending on heating load and SWHsurface
area. - If not supplied, a default value equal to 1.5 * daily average hot water
consumption per year (with 100 liters minimum), will be used. - In Liters.
tankLoss [Optional]
Storage tank's heat loss coefficient (U). Varies from 0.30 to 0.50 depending on the tank
volume, insulation type, thickness ... - If not supplied, default value 0.30 will be used. In W/m2/C.
heightDiameterTankRatio [Optional]
333
Ladybug Primer
Storage tank height and diameter ratio. It mostly ranges from 1 to 3. This input is
important for calculation of tank's area. - If not supplied 2.6 will be used. - Unitless.
heatExchangerEffectiveness [Optional]
Depends on the type of heat exchanger: its transfer coefficient, surface, flow rates,
working fluid... It mostly ranges from 0.6 to 0.9 for closed (indirect) loop swh systems.
Accepted default value can be 0.8. - Set it to 1.0 in case of open (direct) loop swh
system (no heat exchanger is used). - If not supplied it will be set to 0.8. - Unitless.
Outputs
readMe!
...
SWHsystemSettings
A list of all Solar water heating system settings. Plug it to SWHsurface component's
"SWHsystemSettings_" input.
Check Hydra Example Files for Solar Water Heating System Detailed
334
Ladybug Primer
Shading Mask
Use this component to see the portion of the sky dome that is masked by context geometry
around a given viewpoint. The component will generate separate meshs for the portions of
the sky dome that are masked and visible. The component will also calculate the percentage
of the sky that is masked by the context geometry and the percentage that is visible (the sky
view factor). -
Inputs
testPt [Required]
Shading_Mask
335
Ladybug Primer
A view point for which one wants to see the portion of the sky masked by the context
geometry surrounding this point.
context [Required]
Context geometry surrounding the _testPt that could block the view to the sky.
Geometry must be a Brep or list of Breps.
skyDensity [Default]
An integer that is greater than or equal to 0, which to sets the number of times that the
Tergenza sky patches are split. Set to 0 to view a sky mask with the typical Tregenza
sky, which will divide up the sky with a coarse density of 145 sky patches. Set to 1 to
view a sky mask of a Reinhart sky, which will divide up each of these Tergenza patches
into 4 patches to make a sky with a total of 580 sky patches. Higher numbers input here
will ensure a greater accuracy but will also take longer. The default is set to 3 to give
you a high accuracy.
scale [Optional]
Scale of the sky dome
Outputs
masked
A mesh of the portion of the sky dome masked by the _context geometry.
visible
A mesh of the portion of the sky dome visible by the _testPt through the _context
geometry.
percMasked
The percentage of the sky masked by the _context geometry at the _testPt.
skyView
The percentage of the sky visible by the _testPt through the _context geometry.
Check Hydra Example Files for Shading Mask
Shading_Mask
336
Ladybug Primer
Shading Mask_II
Use this component to see the portion of the sky dome that is masked by context geometry
around a given viewpoint. The component will generate separate meshs for the portions of
the sky dome that are masked and visible. The component will also calculate the percentage
of the sky that is masked by the context geometry and the percentage that is visible (the sky
view factor). -
Inputs
testPt [Required]
Shading_Mask_II
337
Ladybug Primer
A view point for which one wants to see the portion of the sky masked by the context
geometry surrounding this point.
context [Required]
Context geometry surrounding the _testPt that could block the view to the sky.
Geometry must be a Brep or list of Breps.
radius [Optional]
Scale of the sky dome
merge [Optional]
Script variable shadingMask
Outputs
maskedSrfOnGound
Script variable Python
maskedCrvsOnSky
Script variable shadingMask
maskedSkyDome
Script variable shadingMaskII
unmaskedSkyDome
Script variable shadingMaskII
Check Hydra Example Files for Shading Mask_II
Shading_Mask_II
338

Ladybug Primer

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Ladybug Primer

Uploaded by

Copyright:

Available Formats

Ladybug

Ladybug for Grasshopper

What is this premier?

What is this premier?

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

Open EPW And STAT Weather Files

Open EPW Weather File

download EPW Weather File

Open STAT File

The total cooling degree-days for the entire year.

Wind Speed Calculator

Adaptive Comfort Calculator

Outdoor Comfort Calculator

PMV Comfort Calculator

Thermal Comfort Indices

Use this component to calculate various

WBGT (Wet-Bulb Globe Temperature) indoors

same data you inputted to "_dryBulbTemperature". - If nothing supplied, it will be

If not supplied, the following default values

Humidity Ratio Calculator

Adaptive Comfort Chart

Monthly Bar Chart

A list of curves representing the axes of the chart.

cities at higher elevations.

comfort or strategy polygon (1) or not(0).

Colored Sky Visualizer

default North direction is set to the Y-axis (0 degrees).

Outdoor Solar Temperature Adjustor

Radiation Calla Lily

one of the total radiation.

A set of guide curves that mark information on the sky dome.

Set to True to bake the sunpath into the Rhino scene.

Wind Boundary Profile

display (as opposed to the vector mesh below).

Use this component to make a windRose in the Rhino scene. -

Import Ground Temp

An .epw file path on your system as a string

The output from the selectSkyMtx component.

through the analysis before running this component.

Sunlight Hours Analysis

Bounce from Surface

View From Sun

Comfort Shade Benefit Evaluator

An estimated balance temperature representing median temperture that people find

a resolution to produce a meaningful reault in all cases.

Photovoltaics Performance Metrics

Use this component to calculate various Photovoltaics performance metrics -

sometimes used by investors or developers for Financial and Maintenance analysis of

STAT Weather Files" component.

Total AC power output for a whole year. - In kWh.

This component calculates the shading of:

leave this input empty too.

Optional legend parameters from the Ladybug "Legend Parameters" component.

Tilt And Orientation Factor

STAT Weather Files" component.

Orientation angle of the inputted PV_SWHsurface. In degrees ().

Check Hydra Example Files for Tilt And Orientation Factor

Integers input here must be between 0 - 5

Where, in the North/South Hemispheres, these dates repsectively signify: Mar 21 =

Integers input here must be between 0 - 5

Adaptive Comfort Parameters

and Practice. Routledge, 2012. (https://books.google.com/books?

Level of BMI for adult (18 years and older)

PMV Comfort Parameters