Table

of Contents
What is this primer? 1.1
Components 1.2
0 | Ladybug 1.2.1
Ladybug 1.2.1.1
Update_File 1.2.1.2
Import_epw 1.2.1.3
Open_EPW_And_STAT_Weather_Files 1.2.1.4
Open_EPW_Weather_File 1.2.1.5
download_EPW_Weather_File 1.2.1.6
Construct_Location 1.2.1.7
Import_Location 1.2.1.8
Import_stat 1.2.1.9
Open_STAT_File 1.2.1.10
Create_LB_Header 1.2.1.11
Decompose_Location 1.2.1.12
1 | AnalyzeWeatherData 1.2.2
Analysis_Period 1.2.2.1
Average_Data 1.2.2.2
Branch_Data 1.2.2.3
Separate_data 1.2.2.4
CDD_HDD 1.2.2.5
Wind_Speed_Calculator 1.2.2.6
Adaptive_Comfort_Calculator 1.2.2.7
Outdoor_Comfort_Calculator 1.2.2.8
PMV_Comfort_Calculator 1.2.2.9
Thermal_Comfort_Indices 1.2.2.10
Ankle_Draft_Discomfort 1.2.2.11
CDH_HDH 1.2.2.12
Clothing_Function 1.2.2.13
Draft_Discomfort 1.2.2.14

1
 Humidity_Ratio_Calculator 1.2.2.15
Radiant_Asymmetry_Discomfort 1.2.2.16
SunriseSunset 1.2.2.17
WetBulbTemp 1.2.2.18
2 | VisualizeWeatherData 1.2.3
3D_Chart 1.2.3.1
Adaptive_Comfort_Chart 1.2.3.2
Line_Chart 1.2.3.3
Monthly_Bar_Chart 1.2.3.4
Psychrometric_Chart 1.2.3.5
Design_Day_Sky_Model 1.2.3.6
GenCumulativeSkyMtx 1.2.3.7
Surface_Hourly_Solar 1.2.3.8
selectSkyMtx 1.2.3.9
Colored_Sky_Visualizer 1.2.3.10
Outdoor_Solar_Temperature_Adjustor 1.2.3.11
Radiation_Calla_Dome 1.2.3.12
Radiation_Rose 1.2.3.13
Sky_Dome 1.2.3.14
SunPath 1.2.3.15
Wind_Boundary_Profile 1.2.3.16
Wind_Rose 1.2.3.17
Bioclimatic_Chart 1.2.3.18
Import_Ground_Temp 1.2.3.19
3 | EnvironmentalAnalysis 1.2.4
Radiation_Analysis 1.2.4.1
Sunlight_Hours_Analysis 1.2.4.2
Set_Rhino_Sun 1.2.4.3
View_Analysis 1.2.4.4
View_From_Sun 1.2.4.5
view_Rose 1.2.4.6
Bounce_from_Surface 1.2.4.7
Comfort_Shade_Benefit_Evaluator 1.2.4.8
Shading_Mask 1.2.4.9

2
 SolarEnvelope 1.2.4.10
SolarFan 1.2.4.11
Sun_Shades_Calculator 1.2.4.12
Cone_Of_Vision 1.2.4.13
Forward_Raytracing 1.2.4.14
ShadingDesigner 1.2.4.15
SolarEnvelopeBasic 1.2.4.16
SolarFanBasic 1.2.4.17
Steady_State_Surface_Temperature 1.2.4.18
Surface_View_Analysis 1.2.4.19
Window_Downdraft 1.2.4.20
4 | Renewables 1.2.5
Photovoltaics_Surface 1.2.5.1
Solar_Water_Heating_Surface 1.2.5.2
PV_SWH_System_Size 1.2.5.3
Photovoltaics_Performance_Metrics 1.2.5.4
Sunpath_Shading 1.2.5.5
Tilt_And_Orientation_Factor 1.2.5.6
Cold_Water_Temperature 1.2.5.7
Commercial_Public_Apartment_Hot_Water 1.2.5.8
Residential_Hot_Water 1.2.5.9
Solar_Water_Heating_Performance_Metrics 1.2.5.10
Solar_Water_Heating_System 1.2.5.11
Solar_Water_Heating_System_Detailed 1.2.5.12
DC_to_AC_derate_factor 1.2.5.13
Import_CEC_Photovoltaics_Module 1.2.5.14
Import_Sandia_Photovoltaics_Module 1.2.5.15
Simplified_Photovoltaics_Module 1.2.5.16
5 | Extra 1.2.6
Gradient_Library 1.2.6.1
ImageViewer 1.2.6.2
ImageViewer 1.2.6.3
Legend_Parameters 1.2.6.4

3
Recolor_Mesh 1.2.6.5
SortByLayers 1.2.6.6
Adaptive_Comfort_Parameters 1.2.6.7
Body_Characteristics 1.2.6.8
PMV_Comfort_Parameters 1.2.6.9
Real_Time_Radiation_Analysis 1.2.6.10
Capture_View 1.2.6.11
Render_View 1.2.6.12
C2F 1.2.6.13
DOY_HOY 1.2.6.14
Day_Month_Hour 1.2.6.15
F2C 1.2.6.16
Generate_Mesh 1.2.6.17
Mesh-To-Hatch 1.2.6.18
Mesh_Threshold_Selector 1.2.6.19
Texture_Maker 1.2.6.20
North 1.2.6.21
True_North 1.2.6.22
False_Start_Toggle 1.2.6.23
Activities_Met_List 1.2.6.24
BTU2Wh 1.2.6.25
BTUft2Whm 1.2.6.26
Beaufort_Ranges 1.2.6.27
Cfm2M3s 1.2.6.28
CombineSolarEnvelopes 1.2.6.29
Comfort_Mannequin 1.2.6.30
Construct_Time 1.2.6.31
Create_Legend 1.2.6.32
L2G 1.2.6.33
M3s2Cfm 1.2.6.34
MRT_Calculator 1.2.6.35
Orient_to_Camera 1.2.6.36
Orientation_Study_Parameters 1.2.6.37
Passive_Strategy_List 1.2.6.38

4
 Passive_Strategy_Parameters 1.2.6.39
Separate_By_Normal 1.2.6.40
Set_the_View 1.2.6.41
Shading_Parameters_List 1.2.6.42
Wh2BTU 1.2.6.43
Whm2BTUft 1.2.6.44
fly 1.2.6.45
lux2ft-cd 1.2.6.46
ms2mph 1.2.6.47
rIP2rSI 1.2.6.48
uIP2uSI 1.2.6.49
uSI2uIP 1.2.6.50
6 | Developers 1.2.7
Export_Ladybug 1.2.7.1
Update_Ladybug 1.2.7.2
7 | WIP 1.2.8
Location_Finder 1.2.8.1
Search 1.2.8.2
Countour_Mesh 1.2.8.3
ENVI-Met_Building_Terrain 1.2.8.4
ENVI-Met_Display 1.2.8.5
ENVI-Met_Find_Output_Folder 1.2.8.6
ENVI-Met_Grid 1.2.8.7
ENVI-Met_Manage_Workspace 1.2.8.8
ENVI-Met_Read_Library 1.2.8.9
ENVI-Met_Results_Reader 1.2.8.10
ENVI-Met_Soil_Plant_Source 1.2.8.11
ENVI-Met_Spaces 1.2.8.12
Kmz_Generator 1.2.8.13
Pedestrian_Wind_Comfort 1.2.8.14
Shading_Mask_II 1.2.8.15
Shadow_Study 1.2.8.16
Terrain_Generator 1.2.8.17

5
6
What is this primer?

ladybug-primer

This primer is auto-generated from the Grasshopper components. Feel free to edit the pages
and send us your pull requests. Here is the source for this primer.

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.

7
What is this primer?

Useful links
Ladybug Tools

Ladybug on Github

Ladybug discussion forum

Facebook page

Ladybug on Twitter

8
0 | Ladybug

Component list:

Ladybug
Update_File
Import_epw
Open_EPW_And_STAT_Weather_Files
Open_EPW_Weather_File
download_EPW_Weather_File
Construct_Location
Import_Location
Import_stat
Open_STAT_File
Create_LB_Header
Decompose_Location

9
Ladybug

Ladybug - [source code]

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

10
Ladybug

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

11
Update_File

Update File - [source code]

Use this component to update ladybug tools components in an old file. This component
doesn't update the installation. It will only update the file to your current installation. The
components that can't be updated automatically will be marked and should be replaced
manually. -

Inputs
update [Required]

Set to "True" if you want this component to search through the current Grasshopper file

12
Update_File

and update ladybug tools components.

Outputs
readMe

...

Check Hydra Example Files for Update File

13
Import_epw

Import epw - [source code]

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://bigladdersoftware.com/epx/docs/8-3/auxiliary-
programs/energyplus-weather-file-epw-data-dictionary.html -

Inputs
epwFile [Required]

14
Import_epw

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

15
Import_epw

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

horizontalInfraredRadiation

Script variable importEPW

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

16
Import_epw

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

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

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

17
Open_EPW_And_STAT_Weather_Files

Open EPW And STAT Weather Files - [source

code]

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

18
Open_EPW_And_STAT_Weather_Files

Inputs
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

19
Open_EPW_Weather_File

Open EPW Weather File - [source code]

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

20
Open_EPW_Weather_File

epwFile

The file path of the selected epw file.

Check Hydra Example Files for Open EPW Weather File

21
download_EPW_Weather_File

download EPW Weather File - [source code]

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

22
download_EPW_Weather_File

readMe!

Will read 'Happy downloading...' in the case of successfully opening your browser

Check Hydra Example Files for download EPW Weather File

23
Construct_Location

Construct Location - [source code]

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)

24
Construct_Location

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

A list of text summarizing the location data in the weather file (use this to construct the
sun path).

Check Hydra Example Files for Construct Location

25
Import_Location

Import Location - [source code]

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

26
Import_Location

location

A list of text summarizing the location data in the weather file (use this to construct the
sun path).

Check Hydra Example Files for Import Location

27
Import_stat

Import stat - [source code]

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]

28
Import_stat

A .stat file path on your system from the Open STAT file component (or typed out as a
string).

Outputs
readMe!

The description of ASHRAE anf koppen climate zones. For more information on
ASHRAE climate names, please see the PDF at
https://www.ashrae.org/File%20Library/docLib/Public/20081111_CZTables.pdf. To know
more about koppen climate zones and their definitions, please visit,
http://bigladdersoftware.com/epx/docs/8-3/auxiliary-programs/koppen-climate-
classification.html and
https://en.wikipedia.org/wiki/K%C3%B6ppen_climate_classification

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.

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.

heatingDesignTemps

The temperatures in celcius that ASHRAE recommends using to size a heating system
to meet a building's sensible heating demand. The two values output here represent
some of the coldest temperatures of the year for which only 0.4% and 1.0% of the hours
are below (respectively).

coolingDesignTemps

The temperatures in celcius that ASHRAE recommends using to size a cooling system
to meet a building's sensible cooling demand. The two values output here represent
some of the hottest temperatures of the year for which only 0.4% and 1.0% of the hours
are above (respectively).

29
Import_stat

heatingDesignDay

An analysis period that represents the day of the year that should be used to size the
heating system.

coolingDesignDay

An analysis period that represents the day of the year that should be used to size the
cooling system.

monthlyTauBeam

Values representing the monthly optical sky depth for beam (direct) solar radiation.
These can be used with the "Ladybug_Design Day Sky" component to create ASHRAE
Tau design day solar radiation values. These values can then be used for sizing HVAC
cooling systems.

monthlyTauDiffuse

Values representing the monthly optical sky depth for diffuse solar radiation. These can
be used with the "Ladybug_Design Day Sky" component to create ASHRAE Tau design
day solar radiation values. These values can then be used for sizing HVAC cooling
systems.

extremeHotWeek

An analysis period representing the hottest week of the typical meteorological year. If
the stat file does not specify an extreme hot week, it is the most extreme week of the
hottest season.

typicalSummerWeek

An analysis period representing a typical week of the hottest season in the typical
meteorological year. Not all stat files specify such a week and, in this case, the output
here will be "Null."

typicalAutumnWeek

An analysis period representing a typical autumn week of the typical meteorological

year.

typicalSpringWeek

An analysis period representing a typical Spring week of the typical meteorological year.
Not all stat files specify such a week and, in this case, the output here will be 'Null.'

30
Import_stat

typicalWinterWeek

An analysis period representing a typical week of the coldest season in the typical
meteorological 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 meteorological 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

31
Open_STAT_File

Open STAT File - [source code]

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.

32
Open_STAT_File

Outputs
statFile

The file path of the selected .stat file.

Check Hydra Example Files for Open STAT File

33
Create_LB_Header

Create LB Header - [source code]

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]

34
Create_LB_Header

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

rawData [Optional]

A list of data that you want to add/modify Ladybug Header

Outputs
LBHeader

Script variable Python

dataWithHeader

A list of data with added/modified Ladybug header

Check Hydra Example Files for Create LB Header

35
Decompose_Location

Decompose Location - [source code]

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.

36
Decompose_Location

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

37
1 | AnalyzeWeatherData

Component list:

Analysis_Period
Average_Data
Branch_Data
Separate_data
CDD_HDD
Wind_Speed_Calculator
Adaptive_Comfort_Calculator
Outdoor_Comfort_Calculator
PMV_Comfort_Calculator
Thermal_Comfort_Indices
Ankle_Draft_Discomfort
CDH_HDH
Clothing_Function
Draft_Discomfort
Humidity_Ratio_Calculator
Radiant_Asymmetry_Discomfort
SunriseSunset
WetBulbTemp

38
Analysis_Period

Analysis Period - [source code]

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

39
Analysis_Period

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

40
Average_Data

Average Data - [source code]

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.

41
Average_Data

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.

avrMonthlyMinPerHour

The data for the max average hour of each month during the analysis period.

avrMonthlyMaxPerHour

The data for the min average hour of each month during the analysis period.

Check Hydra Example Files for Average Data

42
Branch_Data

Branch Data - [source code]

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"

43
Branch_Data

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

44
Separate_data

Separate data - [source code]

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]

45
Separate_data

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

46
CDD_HDD

CDD_HDD - [source code]

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

47
CDD_HDD

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. Also, this
number differs based on the factors that affect the human energy balance of the
occupants inside of the buildings such as; building program, climate zone, solar
exposure, number, age, activity, and clothing of occupants, lighting, equipment,
insulation, etc. Therefore, it is highly recommended to set this number as a temperature
at which the building will start cooling.

heatingBaseTemperature [Default]

Base temperature for heating (in degrees Celsius). Default is set to 18.3C but this can
be much lower if the analysis is for a building with high heat gain or insulation. Also, this
number differs based on the factors that affect the human energy balance of the
occupants inside of the buildings such as; building program, climate zone, solar
exposure, number, age, activity, and clothing of occupants, lighting, equipment,
insulation, etc. Therefore, it is highly recommended to set this number as a temperature
at which the building will start heating.

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

48
CDD_HDD

whole year, connect this to the grasshopper chart/graph component.

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

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

49
Wind_Speed_Calculator

Wind Speed Calculator - [source code]

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

50
Wind_Speed_Calculator

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 or text string that sets the terrain class associated with the output
windSpeedAtHeight. Interger values represent the following terrain classes: 0 = City:
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 interger or text string 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 = City: 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 2 m above ground, which is what a person standing on the
ground would feel.

epwHeight [Optional]

An optional number to set the height at which the _windSpeed_tenMeters was recorded

51
Wind_Speed_Calculator

if the wind was not recorded at 10 meters above the ground. The default is set to 10
meters as this is the height at which all wind in EPW files is recorded.

powerOrLog [Optional]

Set to "True" to use a power law to translate the wind speed to that at a given height
and set to "False" to use a log law to translate the wind speed. The default is set to
"True" for a power law as this is the function that is used by EnergyPlus.

analysisPeriod [Optional]

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.

Outputs
readMe!

...

windSpeedAtHeight

The wind speed at the connected height above the ground.

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

52
Adaptive_Comfort_Calculator

Adaptive Comfort Calculator - [source code]

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

53
Adaptive_Comfort_Calculator

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.

outdoorTemperature [Required]

The direct output of dryBulbTemperature from the Import EPW component. Alternatively,
this can be a number representing the prevailing outdoor temperature in degrees
Celcius. It can also be a list of prevailing outdoor temperatures that corresponds with
the number of values connected above. Note that, when putting in values without a
header like this, the values are meant to be the PREVAILING temperature (not the
actual hourly outdoor temperature).

windSpeed [Optional]

A number representing the wind speed of the air in meters per second. If no value is

54
Adaptive_Comfort_Calculator

plugged in here, this component will assume a very low wind speed of 0.3 m/s,
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.

analysisPeriod [Optional]

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.

55
Adaptive_Comfort_Calculator

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.

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

56
Outdoor_Comfort_Calculator

Outdoor Comfort Calculator - [source code]

Use this component to calculate the Universal Thermal Climate Index (UTCI) for a set of
input climate conditions. Perhaps the most familiar application of Universal 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

57
Outdoor_Comfort_Calculator

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

windSpeed_tenMeters [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.05 m/s,
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.

58
Outdoor_Comfort_Calculator

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.

analysisPeriod [Optional]

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]

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

59
Outdoor_Comfort_Calculator

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

percentOfTimeComfortable

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

60
PMV_Comfort_Calculator

PMV Comfort Calculator - [source code]

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

61
PMV_Comfort_Calculator

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

62
PMV_Comfort_Calculator

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.

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.05 m/s,
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.
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.

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.

comfortPar [Optional]

Optional comfort parameters from the "Ladybug_PMV Comfort Parameters" component.

63
PMV_Comfort_Calculator

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.

analysisPeriod [Optional]

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.

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

64
PMV_Comfort_Calculator

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.

percentOfTimeComfortable

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

65
Thermal_Comfort_Indices

Thermal Comfort Indices - [source code]

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)

66
Thermal_Comfort_Indices

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.

dryBulbTemperature [Required]

Air temperature. Input a single value or a whole list from "Import epw" component's
"dryBulbTemperature" output. - In Celsius degrees (C).

meanRadiantTemperature [Optional]

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

67
Thermal_Comfort_Indices

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

windSpeed [Optional]

Wind speed at 1.1 meters height from analysis surface (height of standing person’s
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.

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.

solarRadiationPerHour [Optional]

Amount of solar radiation that an analysis person received. - 1) If you would like to do
an analysis accounted for shading (more precise) use the "Sunpath shading"
component and its "shadedSolarRadiationPerHour" output. Or use "Radiation Analysis"
component's "radiationResult" output. Be sure to scale the "radiationResult" output data
1000 times (to convert it from kW/m2 to W/m2). The "Sunpath shading" component will
account for partial shading from the trees, while "Radiation Analysis" will not. - 2) If you
would not like to do an analysis accounted for shading (because it's quicker that way),

68
Thermal_Comfort_Indices

then you can simply supply the data from "Import epw" component's
"diffuseHorizontalRadiation" output. In this way it will be assumed that an analysis is
being conducted in outdoor in-shade conditions, or indoor conditions. - If nothing
supplied, default value of 0 Wh/m2 will be used (no solar radiation at all). - In Wh/m2.

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:
35 - 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.

analysisPeriod [Optional]

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!

If your _comfortIndex is set to either 15 or 16, and you are performing analysis for a
single hour, then this output will show additional results related with PET (Physiological
Equivalent Temperature).

69
Thermal_Comfort_Indices

comfortIndexValue

The value of the chosen comfort.

comfortIndexLevel

The level (category, sensation) of the chosen index.

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

70
Ankle_Draft_Discomfort

Ankle Draft Discomfort - [source code]

Use this component to calculate discomfort from cold drafts at ankle-level. The original tests
used to create the model involved blowing cold air on subject's ankles at a height of 10 cm
off of the ground. The formula has been submitted to be incorporated in the ASHRAE 55
standard with a recommendation that PPD from ankle draft not exceed 20%. The papers in
which this model is published can be found here: Schiavon, S., D. Rim, W. Pasut, W.
Nazaroff. 2016. Sensation of draft at uncovered ankles for women exposed to displacement
ventilation and underfloor air distribution systems. Building and Environment, 96, 228–236. _
Liu, S., S. Schiavon, A. Kabanshi, W. Nazaroff. 2016. Predicted percentage of dissatisfied
with ankle draft. Accepted Author Manuscript. Indoor Environmental Quality.
http://escholarship.org/uc/item/9076254n -

71
Ankle_Draft_Discomfort

Inputs
fullBodyPMV [Required]

The predicted mean vote (PMV) of the subject. This can be calculated using the
"Ladybug_PMV Comfort Calculator" component. The reason for why PMV is
incorporated into this draft discomfort model is that people are likely to feel more
uncomfortable from downdraft when their whole body is already feeling cold.

draftAirVeloc [Required]

The velocity of the draft in m/s.

Outputs
PPD

Script variable Python

Check Hydra Example Files for Ankle Draft Discomfort

72
CDH_HDH

CDH_HDH - [source code]

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

73
CDH_HDH

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
be much lower if the analysis is for a building with high heat gain or insulation.

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
whole year, connect this to the grasshopper chart/graph component.

daily_heatingDegHours

Heating degree-days summed for each day of the year. For visualizations of over the
whole year, connect this to the grasshopper chart/graph component.

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.

74
CDH_HDH

annual_heatingDegHours

The total heating degree-days for the entire year.

Check Hydra Example Files for CDH_HDH

75
Clothing_Function

Clothing Function - [source code]

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

76
Clothing_Function

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.

analysisPeriod [Optional]

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

77
Clothing_Function

_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

78
Draft_Discomfort

Draft Discomfort - [source code]

Use this component to calculate discomfort from cold drafts on the back of the neck
(arguably the most sensitive part of the human body to cold drafts). This model was derived
from empircal tests that involved blowing cold air on the back of subjects's necks who were
otherwise at thermally neutral conditions by the pmv standard.
This model used to be the standard endorsed by ASHRAE 55 and EN-12521 for all draft
cases but has since been replaced with a model that more accurately targets draft
discomfort at foot level. The paper in which this model was published can be found here:
Fanger, P.O., Melikov, A.K., Hanzawa, H., Ring, J. “Air Turbulence and Sensation of
Draught.” Energy and Buildings 12, no. 1 (1988): 21–39. -

79
Draft_Discomfort

Inputs
draftAirTemp [Required]

The air temperature of the draft in degrees Celcius.

draftAirVeloc [Required]

The velocity of the draft in m/s.

Outputs
PPD

Script variable Python

Check Hydra Example Files for Draft Discomfort

80
Humidity_Ratio_Calculator

Humidity Ratio Calculator - [source code]

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

81
Humidity_Ratio_Calculator

dryBulbTemperature [Required]

The dry bulb temperature from the Import epw component.

relativeHumidity [Required]

The relative humidity from the Import epw component.

barometricPressure [Optional]

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

82
Radiant_Asymmetry_Discomfort

Radiant Asymmetry Discomfort - [source

code]

Use this component to calculate discomfort from radiant assymetry. _ The comfort functions
in this function come from Figure 5.2.4.1 of ASHRAE 55 2010. -

Inputs
radTempDifference [Required]

The temperature difference between one side of a pla

83
Radiant_Asymmetry_Discomfort

radAsymmType [Required]

An integer that represents the type of radiant assymetry being evaluated. Occupants
are more sensitive to warm cielings and cool walls than cool ceilings and warm walls.
Choose from the following options: 0 = Warm Ceiling 1 = Cool Wall 2 = Cool Cieling 3 =
Warm Wall

PPDThreshold [Optional]

The percentage of people dissatisfied (PPD) above which conditions are not longer
considered acceptable. The default is set to 5%, which is the specification for the
ASHRAE 55 comfort standard. The EN-7730 varies from 6% to 10% depending on the
building class.

Outputs
readMe!

...

PPD

The percentage of people dissatisfied (PPD) from radiant asymmetry.

comfOrNot

A lidt of 0's and 1's (or "False" and "True" values) indicating whether occupants are
comfortable under the input conditions.

Check Hydra Example Files for Radiant Asymmetry Discomfort

84
SunriseSunset

SunriseSunset - [source code]

Use this component to get information about the sun - This component is based on NOAA's
research (National Oceanic and Atmospheric Administration) and it uses equations from
Astronomical Algorithms, by Jean Meeus. "The sunrise and sunset results are theoretically
accurate to within a minute for locations between +/- 72° latitude, and within 10 minutes
outside of those latitudes." Special thanks goes to the authors of the spreadsheets Solar
Calculation and the web page http://www.esrl.noaa.gov/gmd/grad/solcalc/index.html - This
component calculates sunrise and sunset per hourly data. The approximation error of
OfficialSunriseSunset could be about one-two minutes. - Despite this component does not
consider the leap day (FEB 29th), results are accurate enough. -

85
SunriseSunset

Inputs
location [Required]

The output from the importEPW or constructLocation component. This is essentially a

list of text summarizing a location on the earth.

HOYorAnalysisPeriod [Required]

Connect: a) a list of HOYs from outputs of the Ladybug_DOY_HOY for specific date; b)
OR a list of values from 1 to 8760 for the whole year; c) OR Ladybug Analysis Period for
the whole year.

isSunUpshift [Optional]

Set the number of hour after the sunrise and before the sunset you intend to exclude
from the calculation of isSunUp. If no value is connected, the default value is 0.

isSunUpAltitude [Optional]

write a conditional statement about solar altitude. Use 'v' as variable. - Here's an
example: v > 25.5 and v < 67.3 - It is possible to use the following symbols: and, or, ==,
!=, >, <, >=, <=, ), (

year [Optional]

A number between -1000 to 3000. The approximations used in these script are very
good for years between 1800 and 2100. Results should still be sufficiently accurate for
the range from -1000 to 3000.

Outputs
readMe!

...

officialSunriseSunset

It is the time between day and night when there is light outside and the Sun is on the
horizon (90°50').

solarNoon

Solar noon is when the sun is at its highest point in the sky each day.

solarElevationCorrected

86
SunriseSunset

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

solarAzimut

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

sunVector

Vector(s) indicating the direction of sunlight for each sun position.

isSunUp

A list of number. 1 if the sun is up and 0 if the sun is down. - Use Ladybug Analysis
Period or a list of values from 1 to 8760 to generate data for the whole year. - Try to
connect this output to Ladybug 3D Chart to get a daylight chart of your location.

date

Detailied information for each sun position including date and time.

sunLightDuration

Duration of sunlight per day expressed in minutes. - This output is available just for
_HOYorAnalysisPeriod type a) and b) - Try to connect this output to Ladybug_Average
Data to create charts of your location using Ladybug_Monthly Bar Chart.

Check Hydra Example Files for SunriseSunset

87
WetBulbTemp

WetBulbTemp - [source code]

Use this component to calculate Wet Bulb Temperature and Dew Point Temperature - This
component uses the "Method for obtaining wet-bulb temperatures by modifying the
psychrometric formula" created by J. Sullivan and L. D. Sanders (Center for Experiment
Design and Data Analysis). NOAA - National Oceanic and Atmospheric Administration
Special thanks goes to the authors of the online wet-bulb temperature calculator
http://www.srh.noaa.gov/epz/?n=wxcalc_rh -

Inputs
dryBulbTemperature [Required]

88
WetBulbTemp

The dry bulb temperature [°C] from Import epw component and Ladybug_Average Data
or generic lists of numbers.

relativeHumidity [Required]

The relative humidity [%] from Import epw component and Ladybug_Average Data or
generic lists of numbers.

barometricPressure [Default]

The barometric pressure [Pa] from Import epw component and Ladybug_Average Data
or generic lists of numbers. If no value is connected here, the default pressure will be
101325 Pa, which is air pressure at sea level.

Outputs
readMe!

...

wetBulbTemp

The lowest temperature that can be reached by evaporating water into the air.

dewPointTemp

The temperature at which the water vapor contained in a volume of air at a given
atmospheric pressure reaches saturation and condenses to form dew.

Check Hydra Example Files for WetBulbTemp

89
2 | VisualizeWeatherData

Component list:

3D_Chart
Adaptive_Comfort_Chart
Line_Chart
Monthly_Bar_Chart
Psychrometric_Chart
Design_Day_Sky_Model
GenCumulativeSkyMtx
Surface_Hourly_Solar
selectSkyMtx
Colored_Sky_Visualizer
Outdoor_Solar_Temperature_Adjustor
Radiation_Calla_Dome
Radiation_Rose
Sky_Dome
SunPath
Wind_Boundary_Profile
Wind_Rose
Bioclimatic_Chart
Import_Ground_Temp

90
3D_Chart

3D Chart - [source code]

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]

91
3D_Chart

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 0.25, which will will plot each
cell of the graph with an x dimension that is 0.25 of the y. Connect a list of values for
multiple graphs.

yScale [Default]

The scale of the Y axis of the graph. The default is set to 1, which 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 is set to 1, which 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]

An integer that tells the component if/how to bake the bojects in the Rhino scene. The
default is set to 0. Choose from the following options: 0 (or False) - No geometry will be
baked into the Rhino scene (this is the default). 1 (or True) - The geometry will be baked
into the Rhino scene as a colored hatch and Rhino text objects, which facilitates easy
export to PDF or vector-editing programs. 2 - The geometry will be baked into the Rhino
scene as colored meshes, which is useful for recording the results of paramteric runs as
light Rhino geometry.

92
3D_Chart

Outputs
readMe!

...

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

93
3D_Chart

94
Adaptive_Comfort_Chart

Adaptive Comfort Chart - [source code]

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

95
Adaptive_Comfort_Chart

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 'Read EP Result' or '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 from the 'Read EP Result' or 'Import EPW' component.

outdoorTemperature [Required]

The direct output of dryBulbTemperature from the Import EPW component. Alternatively,
this can be a number representing the prevailing outdoor temperature in degrees
Celcius. It can also be a list of prevailing outdoor temperatures that corresponds with
the number of values connected above. Note that, when putting in values without a
header like this, the values are meant to be the PREVAILING temperature (not the
actual hourly outdoor temperature).

windSpeed [Optional]

96
Adaptive_Comfort_Chart

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

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.

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.

analysisPeriod [Optional]

An optional analysis period from the Analysis Period component. If no Analysis period is
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
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

97
Adaptive_Comfort_Chart

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.

legendPar [Optional]

Optional legend parameters from the Ladybug Legend Parameters component.

bakeIt [Optional]

An integer that tells the component if/how to bake the bojects in the Rhino scene. The
default is set to 0. Choose from the following options: 0 (or False) - No geometry will be
baked into the Rhino scene (this is the default). 1 (or True) - The geometry will be baked
into the Rhino scene as a colored hatch and Rhino text objects, which facilitates easy
export to PDF or vector-editing programs. 2 - The geometry will be baked into the Rhino
scene as colored meshes, which is useful for recording the results of paramteric runs as
light Rhino geometry.

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

98
Adaptive_Comfort_Chart

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.

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.

prevailingTemp

A stream of temperature values in degrees Celcius indicating the prevailing outdoor

temperature. This is the temperture that determines the conditions occupants find
comfortable and is either a monthly average temperature or a running mean of outdoor
temperature.

targetTemperature

A stream of temperature values in degrees Celcius indicating the mean target

temperture (or neutral temperature) that the most people will find most comfortable.

chartCurvesAndTxt

The chart curves and text labels of the adaptive chart.

99
Adaptive_Comfort_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

The legend base point, which can be used to move the legend in relation to the chart
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
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

100
Line_Chart

Line Chart - [source code]

Use this component to make a line chart in the Rhino scene of any data with a ladybug
header on it. -

Inputs
inputData [Required]

A list of input data to plot. This should usually be data out of the "Ladybug_Average
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

101
Line_Chart

the "Ladybug_3D Chart" component for daily or hourly data as this is usually a bit
clearer.

chartType [Optional]

An integer that sets the type of chart that will be drawn. Choose from the following
options: 0 = Normal - Data will be plotted as polylines right next to each other. 1 =
Stacked - Data will be plotted as lines stacked on top of one another. 2 = Stacked Area -
Data will be plotted as filled areas stacked on top of one another.

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

legendPar [Optional]

Optional legend parameters from the Ladybug Legend Parameters component.

bakeIt [Optional]

An integer that tells the component if/how to bake the bojects in the Rhino scene. The
default is set to 0. Choose from the following options: 0 (or False) - No geometry will be
baked into the Rhino scene (this is the default). 1 (or True) - The geometry will be baked

102
Line_Chart

into the Rhino scene as a colored hatch and Rhino text objects, which facilitates easy
export to PDF or vector-editing programs. 2 - The geometry will be baked into the Rhino
scene as colored meshes, which is useful for recording the results of paramteric runs as
light Rhino geometry.

Outputs
readMe!

...

dataMesh

A list of meshes that represent the different input data.

dataCurves

A list of curves that represent the different input data.

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

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

103
Line_Chart

output to a grasshopper "Geo" component in order to preview the legend in the Rhino
scene.

legendBasePt

The legend base point, which can be used to move the legend in relation to the chart
with the grasshopper "move" component.

Check Hydra Example Files for Line Chart

104
Monthly_Bar_Chart

Monthly Bar Chart - [source code]

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

105
Monthly_Bar_Chart

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

106
Monthly_Bar_Chart

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.

labelPtsOffset [Default]

A number in Rhino model units that represents the distance between the top of bars on
the chart and the location where the dataLabelPts are. If you set this value to 0, you can
use the dataLabelPts to create a polyline of monthly values. The default is
autocalculated based on the scale of the chart.

legendPar [Optional]

Optional legend parameters from the Ladybug Legend Parameters component.

bakeIt [Optional]

An integer that tells the component if/how to bake the bojects in the Rhino scene. The
default is set to 0. Choose from the following options: 0 (or False) - No geometry will be
baked into the Rhino scene (this is the default). 1 (or True) - The geometry will be baked
into the Rhino scene as a colored hatch and Rhino text objects, which facilitates easy
export to PDF or vector-editing programs. 2 - The geometry will be baked into the Rhino
scene as colored meshes, which is useful for recording the results of paramteric runs as
light Rhino geometry.

Outputs
readMe!

...

107
Monthly_Bar_Chart

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

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

The legend base point, which can be used to move the legend in relation to the chart
with the grasshopper "move" component.

dataLabelPts

108
Monthly_Bar_Chart

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

comfortLegend

A legend for the comfort model. This legend will only be provided if temperature is fed to
this component and the value provided to the comfortModel_ is either 1, 2, or 3.

Check Hydra Example Files for Monthly Bar Chart

109
Psychrometric_Chart

Psychrometric Chart - [source code]

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 seven-
point 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

110
Psychrometric_Chart

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

relativeHumidity [Required]

A number between 0 and 100 representing the relative humidity of the air in percentage.
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.

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

111
Psychrometric_Chart

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 the same as the
connected dry bulb temperature (and the X-Axis of the Psychrometric Chart is for
Operative Temperature instead of Dry Bulb Temperature). This input can also accept a
list of temperatures and this will produce several comfort polygons (one for each mean
radiant temperature).

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.05 m/s,
characteristic of most indoor conditions. This input can also accept a list of wind speeds
representing conditions and this will produce several comfort polygons (one for each
wind speed).

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 and will produce multiple comfort
polygons accordingly.

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

112
Psychrometric_Chart

in the section above and you wish to merge all of the computed comfort polygons into
one.

comfortPar [Optional]

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.

analysisPeriod [Optional]

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.

annualHourlyData [Optional]

An optional list of hourly data from the Import epw component, which will be used to

113
Psychrometric_Chart

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

basePoint [Optional]

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.

legendPar [Optional]

Optional legend parameters from the Ladybug Legend Parameters component.

bakeIt [Optional]

An integer that tells the component if/how to bake the bojects in the Rhino scene. The
default is set to 0. Choose from the following options: 0 (or False) - No geometry will be
baked into the Rhino scene (this is the default). 1 (or True) - The geometry will be baked
into the Rhino scene as a colored hatch and Rhino text objects, which facilitates easy
export to PDF or vector-editing programs. 2 - The geometry will be baked into the Rhino
scene as colored meshes, which is useful for recording the results of paramteric runs as
light Rhino geometry.

runIt [Required]

Set to "True" to run the component and generate a psychrometric chart! Returns:

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

115
Psychrometric_Chart

legendBasePt

The legend base point, which can be used to move the legend in relation to the chart
with the grasshopper "move" component.

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

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

116
Design_Day_Sky_Model

Design Day Sky Model - [source code]

Use this component to generate a clear sky for a cooling design day, which can then be
used to size a HVAC system. This component outputs both the hourly solar radiation values
as well as a cumulative sky that can be used in solar radiation studies (if requested).
Specifically, this component uses the ASHRAE Revised Clear Sky Model (“Tau Model”),
which was originally published in the ASHRAE 2009 Handbook of Fundementals (American
Society of Heating, Refrigerating and Air-Conditioning Engineers. (2009). 2009 ASHRAE
handbook: Fundamentals. Atlanta, GA: American Society of Heating, Refrigeration and Air-
Conditioning Engineers). The "Tau Model" is currently the recommended sky model for
cooling design day calculations and is the default assumption of Honeybee EnergyPlus

117
Design_Day_Sky_Model

HVAC sizing calculations. More information on the calculation for the can be found in the
EnergyPlus Input/Output reference: http://bigladdersoftware.com/epx/docs/8-4/engineering-
reference/climate-calculations.html#ashrae-revised-clear-sky-model-tau-model -

Inputs
location [Required]

The output from the importEPW or constructLocation component. This is essentially a

list of text summarizing a location on the earth.

tauBeam [Required]

Values representing the optical sky depth for beam (direct) solar radiation. Optical depth
is the natural logarithm of the ratio of incident to transmitted radiant power through the
atmosphere. It can vary from month to month as water vapor concentrations in the
atmosphere change. This input can be either a single value for the whole year, a list of
12 monthly values, or the output from the "Ladybug_Import stat" component. Typical
values range from 0.3 in cool dry months to 0.65 in warm humid months.

tauDiffuse [Required]

Values representing the optical sky depth for diffuse solar radiation. Optical depth is the
natural logarithm of the ratio of incident to transmitted radiant power through the
atmosphere. It can vary from month to month as water vapor concentrations in the
atmosphere change. This input can be either a single value for the whole year, a list of
12 monthly values, or the output from the "Ladybug_Import stat" component. Typical
values range from 1.75 in warm humid months to 2.5 in cool dry months.

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.

workingDir [Optional]

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.

118
Design_Day_Sky_Model

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.

genCumSky [Optional]

Set to 'True' to have this component generate a cumulative sky matrix for the design
day sky. This can then be used in Ladybug solar radiation studies and visualized with
the "Ladybug_Sky Dome" or "Ladybug_Radiation Rose."

Outputs
readMe!

...

directNormRad

The hourly Direct Normal Radiation in Wh/m2 for an ASHRAE Revised Clear Sky (“Tau
Model”). Direct normal radiation is the amount of solar radiation in Wh/m2 received
directly from the solar disk on a surface perpendicular to the sun's rays.

diffuseHorizRad

The hourly Diffuse Horizontal Radiation in Wh/m2 for an ASHRAE Revised Clear Sky
(“Tau Model”). Diffuse horizontal radiation is the amount of solar radiation in Wh/m2
received from the sky (excluding the solar disk) on a horizontal surface. globalHorizRad;
The hourly Global Horizontal Radiation in Wh/m2 for an ASHRAE Revised Clear Sky
(“Tau Model”). Diffuse horizontal radiation is the total amount of direct and diffuse solar
radiation in Wh/m2 received on a horizontal surface.

globalHorizRad

Script variable DesignDaySky

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 Design Day Sky Model

119
Design_Day_Sky_Model

120
GenCumulativeSkyMtx

GenCumulativeSkyMtx - [source code]

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.radiance-
online.org/learning/documentation/manual-pages/pdfs/gendaymtx.pdf -

Inputs

121
GenCumulativeSkyMtx

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.

workingDir [Optional]

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

122
Surface_Hourly_Solar

Surface Hourly Solar - [source code]

Use this component to quickly compute the hourly solar radiation or illuminance falling on an
unobstructed surface that faces any direction from EPW inputs. _ The calculation method of
this component is faster than running a full Ladybug Solar Radiation Analysis but this comes
at the cost of not being able to account for obstructions that block the sun. -

Inputs
location [Required]

The output from the importEPW or constructLocation component. This is essentially a

123
Surface_Hourly_Solar

list of text summarizing a location on the earth.

directNormal [Required]

A list of 8760 hourly values (with an optional Ladybug header on it) that denotes direct
normal solar. This can be either directNormalRadiation or directNormalIlluminance
(depending on what output is needed). These values can be obtained from the
"Ladybug_Import EPW" component or the "Ladybug_Design Day Sky Model"
component.

diffuseHorizontal [Required]

A list of 8760 hourly values (with an optional Ladybug header on it) that denotes diffuse
horizontal solar. This can be either globalHorizontalRadiation or
globalHorizontallIlluminance (depending on what output is needed). These values can
be obtained from the "Ladybug_Import EPW" component or the "Ladybug_Design Day
Sky Model" component.

srfAzimuth [Default]

A number between 0 and 360 that represents the azimuth that a surface is facing in
degrees. A value of 0 means North, 90 means East, 180 means South, and 270 means
West. If no value is connected here, a default azimuth of 180 will be assumed for a
south facing window.

srfAltitude [Default]

A number between 0 and 90 that represents the altitude that a surface is facing in
degrees. A value of 0 means the surface is facing the horizon and a value of 90 means
a surface is facing straight up. If no value is connected here, a default altitude of 90 will
be assumed for a surface facing straignt up.

skyModel [Optional]

Set to "True" to use an isotropic sky model, which assumes that diffuse radiation is
evenly distributed across the sky and is suitale for both cloudy and clear skies. Set to
"False" to use an anisotropic sky model, that places more diffuse radiation near the
solar disc and is more accourate for clear skies but is not suitable for cloudy skies. The
default is set to "True" of an isotropic sky model.

Outputs
readMe!

124
Surface_Hourly_Solar

...

srfDirect

Hourly direct solar falling on the surface.

srfDiffuse

Hourly diffuse solar falling on the surface.

srfTotal

Hourly total solar falling on the surface.

srfDirection

A vector showing the direction that the surface is facing in the Rhino scene.

Check Hydra Example Files for Surface Hourly Solar

125
selectSkyMtx

selectSkyMtx - [source code]

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]

126
selectSkyMtx

An hour of the year or list of hours of the year for which you would like to select a sky.
This must be a value between 1 and 8760.

analysisPeriod [Default]

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

127
Colored_Sky_Visualizer

Colored Sky Visualizer - [source code]

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

128
Colored_Sky_Visualizer

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

location [Required]

The output from the importEPW or constructLocation component. This is essentially a

list of text summarizing a location on the earth.

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.

projection [Default]

129
Colored_Sky_Visualizer

A number to set the projection of the sky hemisphere. The default is set to draw a 3D
hemisphere. Choose from the following options: 0 = 3D hemisphere 1 = Orthographic
(straight projection to the XY Plane) 2 = Stereographic (equi-angular projection to the
XY Plane) 3 = Cylindrical (unrolled rectangular map of the sky - like a Mercator
projection)

bakeIt [Optional]

An integer that tells the component if/how to bake the bojects in the Rhino scene. The
default is set to 0. Choose from the following options: 0 (or False) - No geometry will be
baked into the Rhino scene (this is the default). 1 (or True) - The geometry will be baked
into the Rhino scene as a colored hatch and Rhino text objects, which facilitates easy
export to PDF or vector-editing programs. 2 - The geometry will be baked into the Rhino
scene as colored meshes, which is useful for recording the results of paramteric runs as
light Rhino geometry.

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

130
Outdoor_Solar_Temperature_Adjustor

Outdoor Solar Temperature Adjustor -

[source code]

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 _baseTemperature input. If you do not hook up a _baseTemperature, 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

131
Outdoor_Solar_Temperature_Adjustor

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
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. This is used to
determine the position of the sun.

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

diffuseHorizRad [Required]

If you are running a simple analysis with Direct Normal Radiation above, you must
provide the diffuseHorizaontalRadiation ouput from the 'Ladybug_Import epw'
component here. Otherwise, this input is not required.

baseTemperature [Required]

A number or list of numbers representing either the outdoor dry bulb air temperture (if
the input below is set to 'True') or the long wave mean radiant temperature (MRT) of the
surrounding surfaces in degrees Celcius (if the input below is set to 'False'). The former
is useufl for computing outdoor MRT if you only have the air temperature while the latter
is useful for indoor conditions when you can compute a starting long wave MRT from
the indoor surface temperatures.

baseDryBulbOrMRT [Default]

Set to 'True' to have the _baseTemperature above understood as the outdoor dry bulb
air temperature, in which case this component will attempt to account for long wave
radiation by computing sky temperature and assuming all other surfaces are at the
specified _baseTemperature. Set to 'False' to have the input above interpreted as a

132
Outdoor_Solar_Temperature_Adjustor

starting long wave MRT, which will only be increased to account for short wave
radiation. The latter is useful for indoor conditions where you can compute a starting
long wave MRT from the indoor surface temperatures. The default is set to 'True' to
interpret the input above as outdoor air temperature.

horizInfraredRad [Default]

A number or list of numbers representing downwelling long wave infrared radiation from
the sky. This input can also be the horizontalInfraredRadiation output of the Import EPE
component. The values are necessary to calculate long wave sky temperature when the
input above is set to 'True.'

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.

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 _baseTemperature that accounts for the temperature of all the temperture of
these shading surfaces.

north [Optional]

133
Outdoor_Solar_Temperature_Adjustor

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 degrees off from the y-axis to make North. The default
North direction is set to the Y-axis (0 degrees).

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
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 the whole year if using raw epw DirNormRad
or will run for noon on the winter solstice if using cumSkyMtx.

legendPar [Optional]

Optional legend parameters from the Ladybug Legend Parameters component.

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.
The default is set to 'False'.

parallel [Optional]

134
Outdoor_Solar_Temperature_Adjustor

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

bakeIt [Optional]

An integer that tells the component if/how to bake the bojects in the Rhino scene. The
default is set to 0. Choose from the following options: 0 (or False) - No geometry will be
baked into the Rhino scene (this is the default). 1 (or True) - The geometry will be baked
into the Rhino scene as a colored hatch and Rhino text objects, which facilitates easy
export to PDF or vector-editing programs. 2 - The geometry will be baked into the Rhino
scene as colored meshes, which is useful for recording the results of paramteric runs as
light Rhino geometry.

runIt [Required]

The legend base point, which can be used to move the legend in relation to the chart
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

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 _baseTemperature 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

135
Outdoor_Solar_Temperature_Adjustor

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

136
Radiation_Calla_Dome

Radiation Calla Dome - [source code]

Use this component to draw Radiation Calla 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 Dome can be understood in three different ways: _ 1) The
Calla 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 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 Dome is a smart radiation analysis of a
hemisphere. Your results would effectively be the same if you made a hemisphere in Rhino

137
Radiation_Calla_Dome

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

scale [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).

projection [Default]

A number to set the projection of the sky hemisphere. The default is set to draw a 3D
hemisphere. Choose from the following options: 0 = 3D hemisphere 1 = Orthographic
(straight projection to the XY Plane) 2 = Stereographic (equi-angular projection to the
XY Plane)

legendPar [Optional]

Optional legend parameters from the Ladybug Legend Parameters component.

138
Radiation_Calla_Dome

bakeIt [Optional]

An integer that tells the component if/how to bake the bojects in the Rhino scene. The
default is set to 0. Choose from the following options: 0 (or False) - No geometry will be
baked into the Rhino scene (this is the default). 1 (or True) - The geometry will be baked
into the Rhino scene as a colored hatch and Rhino text objects, which facilitates easy
export to PDF or vector-editing programs. 2 - The geometry will be baked into the Rhino
scene as colored meshes, which is useful for recording the results of paramteric runs as
light Rhino geometry.

runIt [Required]

Set to "True" to run the component and generate a radiation Calla Dome.

Outputs
readMe!

...

radiationMesh

A colored mesh representing radiation of the Calla Dome.

baseCrvs

A set of guide curves for the Calla Dome.

altitudeCrvs

Script variable radiationCallaLily

legend

A legend of the radiation on the Calla Dome. Connect this output to a grasshopper
"Geo" component in order to preview the legend in the Rhino scene.

testPts

The vertices of the Calla Dome mesh. These are hidden by default.

testPtsInfo

Information for each test point of the Calla Dome 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.

139
Radiation_Calla_Dome

values

The radiation values for each test points (or mesh faces) of the Calla Doem 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 Dome.
"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 Dome

140
Radiation_Rose

Radiation Rose - [source code]

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]

Input a vector to be used as a true North direction for the sun path or a number between

141
Radiation_Rose

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

selectedSkyMtx [Required]

The output from the selectSkyMtx component.

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

centerPoint [Default]

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.

legendPar [Optional]

Optional legend parameters from the Ladybug Legend Parameters component.

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

142
Radiation_Rose

one of the total radiation.

bakeIt [Optional]

An integer that tells the component if/how to bake the bojects in the Rhino scene. The
default is set to 0. Choose from the following options: 0 (or False) - No geometry will be
baked into the Rhino scene (this is the default). 1 (or True) - The geometry will be baked
into the Rhino scene as a colored hatch and Rhino text objects, which facilitates easy
export to PDF or vector-editing programs. 2 - The geometry will be baked into the Rhino
scene as colored meshes, which is useful for recording the results of paramteric runs as
light Rhino geometry.

runIt [Required]

Set to "True" to run the component and generate a radiation rose.

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

143
Radiation_Rose

The radiation values in kWh/m2 for each rose arrow.

Check Hydra Example Files for Radiation Rose

144
Sky_Dome

Sky Dome - [source code]

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]

Input a vector to be used as a true North direction for the sun path or a number between

145
Sky_Dome

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

selectedSkyMtx [Required]

The output from the selectSkyMtx component.

centerPoint [Default]

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.

projection [Default]

A number to set the projection of the sky hemisphere. The default is set to draw a 3D
hemisphere. Choose from the following options: 0 = 3D hemisphere 1 = Orthographic
(straight projection to the XY Plane) 2 = Stereographic (equi-angular projection to the
XY Plane)

legendPar [Optional]

Optional legend parameters from the Ladybug Legend Parameters component.

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.

bakeIt [Optional]

An integer that tells the component if/how to bake the bojects in the Rhino scene. The
default is set to 0. Choose from the following options: 0 (or False) - No geometry will be
baked into the Rhino scene (this is the default). 1 (or True) - The geometry will be baked
into the Rhino scene as a colored hatch and Rhino text objects, which facilitates easy
export to PDF or vector-editing programs. 2 - The geometry will be baked into the Rhino
scene as colored meshes, which is useful for recording the results of paramteric runs as
light Rhino geometry.

runIt [Required]

Set to "True" to run the component and generate a sky dome.

146
Sky_Dome

Outputs
readMe!

...

skyPatchesMesh

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

baseCrvs

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

altitudeCrvs

A set of circular curves that denote the altitude. Note that these will only appear when
the projection is set to something other than a 3D sun path.

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

The legend base point(s), which can be used to move the legend(s) in relation to the
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

147
Sky_Dome

148
SunPath

SunPath - [source code]

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]

149
SunPath

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 degrees off from the y-axis to make North. The default
North direction is set to the Y-axis (0 degrees).

location [Required]

The output from the importEPW or constructLocation component. This is essentially a

list of text summarizing a location on the earth.

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.

analysisPeriod [Optional]

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.

150
SunPath

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.

projection [Default]

A number to set the projection of the sky hemisphere. The default is set to draw a 3D
hemisphere. Choose from the following options: 0 = 3D hemisphere 1 = Orthographic
(straight projection to the XY Plane) 2 = Stereographic (equi-angular projection to the
XY Plane)

annualHourlyData [Optional]

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

conditionalStatement [Optional]

This input allows users to remove data that does not fit specific conditions or criteria
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).

legendPar [Optional]

Optional legend parameters from the Ladybug Legend Parameters component.

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 [Default]

151
SunPath

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]

An integer that tells the component if/how to bake the bojects in the Rhino scene. The
default is set to 0. Choose from the following options: 0 (or False) - No geometry will be
baked into the Rhino scene (this is the default). 1 (or True) - The geometry will be baked
into the Rhino scene as a colored hatch and Rhino text objects, which facilitates easy
export to PDF or vector-editing programs. 2 - The geometry will be baked into the Rhino
scene as colored meshes, which is useful for recording the results of paramteric runs as
light Rhino geometry.

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 curves that mark the path of the sun across the sky dome.

compassCrvs

A set of curves and text meshes that denote the cardinal directions and azimuth angles.

152
SunPath

altitudeCrvs

A set of circular curves that denote the altitude. Note that these will only appear when
the projection is set to something other than a 3D sun path.

legend

A legend for the sun path. 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
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

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

153
SunPath

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

154
Wind_Boundary_Profile

Wind Boundary Profile - [source code]

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. - The wind profile will point you in the direction of prevailing wind if
EPW data is connected to windSpeed_tenMeters and windDirections. In case you are trying
to orient your building to take advantage of natural ventilation, as a good rule of thumb, it
always a good strategy to align the shorter axis of your building parellel to the prevailing
wind directions. - More information on the power law of the wind profile can be found here:
http://en.wikipedia.org/wiki/Wind_profile_power_law -

Inputs

155
Wind_Boundary_Profile

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 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. 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 or text string that sets the terrain class associated with the output
windSpeedAtHeight. Interger values represent the following terrain classes: 0 = City:
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 interger or text string 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 = City: 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).

powerOrLog [Optional]

Set to "True" to use a power law to translate the wind speed to that at a given height
and set to "False" to use a log law to translate the wind speed. The default is set to
"True" for a power law as this is the function that is used by EnergyPlus.

156
Wind_Boundary_Profile

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.

analysisPeriod [Optional]

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.

annualHourlyData [Optional]

An optional list of hourly data from the Import epw component, which will be overlaid on
wind rose (e.g. dryBulbTemperature)

conditionalStatement [Optional]

This input allows users to remove data that does not fit specific conditions or criteria
from the wind rose. 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 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

157
Wind_Boundary_Profile

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.

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.

legendPar [Optional]

Optional legend parameters from the Ladybug Legend Parameters component.

bakeIt [Optional]

An integer that tells the component if/how to bake the bojects in the Rhino scene. The
default is set to 0. Choose from the following options: 0 (or False) - No geometry will be
baked into the Rhino scene (this is the default). 1 (or True) - The geometry will be baked
into the Rhino scene as a colored hatch and Rhino text objects, which facilitates easy
export to PDF or vector-editing programs. 2 - The geometry will be baked into the Rhino
scene as colored meshes, which is useful for recording the results of paramteric runs as
light Rhino geometry.

Outputs
readMe!

158
Wind_Boundary_Profile

...

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

159
Wind_Boundary_Profile

160
Wind_Rose

Wind Rose - [source code]

Use this component to make a windRose in the Rhino scene. In this wind rose diagram,
each wedge represents the percentage of time the wind came from that direction during the
analysis period you choose. You will note that each wedge is also colored. These colors
relate directly with the legend displayed on the right. The colors in a wedge conveys the
relative percentage of time the wind coming from that direction was within that speed range.
-

Inputs
north [Default]

161
Wind_Rose

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

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.

annualHourlyData [Optional]

An optional list of hourly data from the Import epw component, which will be overlaid on
wind rose (e.g. dryBulbTemperature)

analysisPeriod [Default]

An optional analysis period from the Analysis Period component.

conditionalStatement [Optional]

This input allows users to remove data that does not fit specific conditions or criteria
from the wind rose. 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 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). This also
accepts output from Ladybug_Beaufort Ranges component.

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.

centerPoint [Default]

162
Wind_Rose

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]

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.

showFrequency [Optional]

Connect boolean and set it to True to display frequency of wind coming from each
direction. By default, these values will be displayed in gray color.

showAverageVelocity [Optional]

Connect boolean and set it to True to display average wind velocity in m/s for wind
coming from each direction. If a conditional statement is connected to the
conditionalStatement_ input, a beaufort number is plotted(in square brackets) along with
the average velocities. This number indicates the effect caused by wind of average
velocity coming from that partcular direction. By default, these values will be displayed
in black color.

scale [Default]

Input a number here to change the scale of the wind rose. The default is set to 1.

legendPar [Optional]

Optional legend parameters from the Ladybug Legend Parameters component.

bakeIt [Optional]

An integer that tells the component if/how to bake the bojects in the Rhino scene. The
default is set to 0. Choose from the following options: 0 (or False) - No geometry will be
baked into the Rhino scene (this is the default). 1 (or True) - The geometry will be baked
into the Rhino scene as a colored hatch and Rhino text objects, which facilitates easy
export to PDF or vector-editing programs. 2 - The geometry will be baked into the Rhino
scene as colored meshes, which is useful for recording the results of paramteric runs as
light Rhino geometry.

runIt [Required]

163
Wind_Rose

Set this value to "True" to run the component and generate a wind rose in 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

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
order to preview the legend separately in the Rhino scene.

legendBasePts

The legend base point(s), which can be used to move the legend in relation to the rose
with the grasshopper "move" component.

title

The title for the wind rose. Connect this output to a grasshopper "Geo" component in
order to preview the legend separately in the Rhino scene.

averageVelocityMesh

Mesh output for average wind velocities displayed on WindRose. This will only output

164
Wind_Rose

meshes if boolean value of True is provided to showAverageVelocity_. By default, these

meshes are displayed in black color.

frequencyMesh

Mesh output for frequencies displayed on WindRose. This will only output meshes if
boolean value of True is provided to showFrequency_. By default, these meshes are
displayed in gray color.

windSpeeds

Wind speed data for the wind rose displayed in the Rhino scene.

windDirections

Wind direction data for the wind rose displayed in the Rhino scene.

averageVelocities

A list containing average wind velocity for all wind rose directions.

frequencies

A list containing frequency of time the wind is coming from a particular direction for all
wind rose directions.

Check Hydra Example Files for Wind Rose

165
Bioclimatic_Chart

Bioclimatic Chart - [source code]

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:

166
Bioclimatic_Chart

1. Olgyay, V., 1963. Design with Climate. Bioclimatic Approach to Architectural Regio
nalism. Van Nostrand reinhold, New York.
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. Energy COnservation Through Building Design. McGraw Hill Book Company.
4. Yezioro, A. & E. Shaviv. 1996. A Knowledge Based CAD System for Determining Therma
l Comfort Design Strategies. Renewable Energy, 8: (1-4), (pp. 133-138).
5. Brown G.Z. and DeKay M., 2001. Sun, WInd & Light. Architectural Design Strategies
(2nd edition). John WIley & Sons, Inc.

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. Indoor
temperatures from Honeybee energy simulations are also possible inputs.

relativeHumidity [Required]

A number between 0 and 100 representing the relative humidity of the air in percentage.
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.

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.

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

167
Bioclimatic_Chart

as 2 to 4 clo.

passiveStrategy [Optional]

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]

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. ONLY WORKS FOR THE WHOLE YEAR RIGHT NOW!!

analysisPeriodSummer [Optional]

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. ONLY WORKS FOR THE WHOLE YEAR RIGHT NOW!!

basePoint [Optional]

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.

legendPar [Optional]

Optional legend parameters from the Ladybug Legend Parameters component.

runIt [Required]

168
Bioclimatic_Chart

Set to "True" to run the component and calculate the adaptive comfort metrics.

Outputs
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
default, this ouput is hidden and, to see it, you should connect it to a Grasshopper
preview component.

hourPointColorsByComfort

169
Bioclimatic_Chart

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
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
default, this ouput is hidden and, to see it, you should connect it to a Grasshopper
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

The legend base point, which can be used to move the legend in relation to the chart
with the grasshopper "move" component.

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

170
Bioclimatic_Chart

171
Import_Ground_Temp

Import Ground Temp - [source code]

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]

172
Import_Ground_Temp

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

In every epw file there are monthly ground temperatures at 3 different depths this is the
2nd

groundtemp3rd

In every epw file there are monthly ground temperatures at 3 different depths this is the
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

173
Import_Ground_Temp

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

174
3 | EnvironmentalAnalysis

Component list:

Radiation_Analysis
Sunlight_Hours_Analysis
Set_Rhino_Sun
View_Analysis
View_From_Sun
view_Rose
Bounce_from_Surface
Comfort_Shade_Benefit_Evaluator
Shading_Mask
SolarEnvelope
SolarFan
Sun_Shades_Calculator
Cone_Of_Vision
Forward_Raytracing
ShadingDesigner
SolarEnvelopeBasic
SolarFanBasic
Steady_State_Surface_Temperature
Surface_View_Analysis
Window_Downdraft

175
Radiation_Analysis

Radiation Analysis - [source code]

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

176
Radiation_Analysis

Inputs
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 degrees off from the y-axis to make North. The default
North direction is set to the Y-axis (0 degrees).

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 testPts of this component are 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.

selectedSkyMtx [Required]

177
Radiation_Analysis

The output from the selectSkyMtx component.

legendPar [Optional]

Optional legend parameters from the Ladybug Legend Parameters component.

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]

An integer that tells the component if/how to bake the bojects in the Rhino scene. The
default is set to 0. Choose from the following options: 0 (or False) - No geometry will be
baked into the Rhino scene (this is the default). 1 (or True) - The geometry will be baked
into the Rhino scene as a colored hatch and Rhino text objects, which facilitates easy
export to PDF or vector-editing programs. 2 - The geometry will be baked into the Rhino
scene as colored meshes, which is useful for recording the results of paramteric runs as
light Rhino geometry.

workingDir [Optional]

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!

...

178
Radiation_Analysis

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

179
Radiation_Analysis

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

180
Sunlight_Hours_Analysis

Sunlight Hours Analysis - [source code]

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

181
Sunlight_Hours_Analysis

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 degrees off from the y-axis to make North. The default
North direction is set to the Y-axis (0 degrees). In case you have provided rotation value
for the North in the Sunpath component, there's no need to provide the same rotation
value here. Doing this will give you erroneous results.

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]

A number in Rhino model units that represents the average size of a grid cell for
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.

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 sunlight hours analysis is done for the
correct side of the test _geometry. If the resulting testPts of this component are 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.

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]

182
Sunlight_Hours_Analysis

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
set to 1 such that one ssun vector is generated for each hour.

legendPar [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 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]

An integer that tells the component if/how to bake the bojects in the Rhino scene. The
default is set to 0. Choose from the following options: 0 (or False) - No geometry will be
baked into the Rhino scene (this is the default). 1 (or True) - The geometry will be baked
into the Rhino scene as a colored hatch and Rhino text objects, which facilitates easy
export to PDF or vector-editing programs. 2 - The geometry will be baked into the Rhino
scene as colored meshes, which is useful for recording the results of paramteric runs as
light Rhino geometry.

workingDir [Optional]

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.

183
Sunlight_Hours_Analysis

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

Vectors for each of the test points on the test _geometry, which indicate the direction for
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.

184
Sunlight_Hours_Analysis

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.

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

185
Set_Rhino_Sun

Set Rhino Sun - [source code]

Use this component to set the Rhino sun from grasshopper and coordinate your Rhino
visualizations with the Ladybug weatherfile and other solar parameters. -

Inputs
location [Required]

get location from Ladybug_Import epw component. This will update rhino solar system
to the correct coordinates and timezone

186
Set_Rhino_Sun

north [Optional]

North direction of the model. This can be either an number representing angle, or a
vector. (by default North is set on the y axis)

month [Default]

A number that represents the month you want to visualize

day [Default]

A number that represents the Day you want to visualize

hour [Default]

A number that represents the Hour you want to visualize

runIt [Required]

Set to True to run the component and position the Rhino Sun.

Outputs
readMe!

...

Check Hydra Example Files for Set Rhino Sun

187
View_Analysis

View Analysis - [source code]

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

188
View_Analysis

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]

A number in Rhino model units that represents the average size of a grid cell for
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.

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

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 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]

189
View_Analysis

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 - Sky Exposure - The percentage of the sky that is visible from the
points of the input _geometry (as opposed to Sky View, which is the amount of sky seen
by a surface). This is equivalent to a solid angle or even-spaced ray-tracing calculation
from the point. It is useful for evaluating one's general visual connection to the sky at a
given set of points. 4 - Sky View - The percentage of the sky that is visible from the
surface _geometry (as opposed to Sky Exposure, which is the amount of sky seen by
the points). While Sky Exposure treats each patch of the sky with relatively equal
weight, sky view weights these patches by their area projected into the plane of the
surface being evaluated. In other words, sky view for a horizontal surface would give
more importance to the sky patches that are overhead vs near the horizon. Sky view is
an important factor in for modelling urban heat island since the inability of warm urban
surfaces to radiate heat to a cool night sky is one of the largest contributors of the heat
island effect.

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.

geometryBlocksView [Optional]

Set to 'True' to have the component count the input geometry as opaque and set to
'False' to discount the _geometry from the calculation and only look at context that
blocks the view. The default is set to 'False' for all types of view studies except for (3 -
Sky Exposure) and (4 - Sky View), where the default is set to 'True.'

legendPar [Optional]

190
View_Analysis

Optional legend parameters from the Ladybug Legend Parameters component.

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]

An integer that tells the component if/how to bake the bojects in the Rhino scene. The
default is set to 0. Choose from the following options: 0 (or False) - No geometry will be
baked into the Rhino scene (this is the default). 1 (or True) - The geometry will be baked
into the Rhino scene as a colored hatch and Rhino text objects, which facilitates easy
export to PDF or vector-editing programs. 2 - The geometry will be baked into the Rhino
scene as colored meshes, which is useful for recording the results of paramteric runs as
light Rhino geometry.

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

191
View_Analysis

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

Vectors for each of the test points on the test _geometry, which indicate the direction for
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

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

192
View_Analysis

193
View_From_Sun

View From Sun - [source code]

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.

194
View_From_Sun

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

195
view_Rose

view Rose - [source code]

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.

196
view_Rose

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

197
Bounce_from_Surface

Bounce from Surface - [source code]

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

198
Bounce_from_Surface

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.

sunVectors [Required]

A sun vector from the sunPath component or a list of sun vectors to be forward ray-
traced.

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.

runIt [Required]

Script variable bounceFromSurface

Outputs
rays

199
Bounce_from_Surface

The sun rays traced forward through the geometry.

bouncePts

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

200
Comfort_Shade_Benefit_Evaluator

Comfort Shade Benefit Evaluator - [source

code]

This is a component for visualizing the desirability of shade in terms of thermal comfort by
using solar vectors, a series of hourly temperatures (usually outdoor temperatures), and an
assumed "balance" temperature (or comfort temperature). The balance temperature
represents the median temperture that people find comfortable, which is usually around
17.5C in outdoor conditions. 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

201
Comfort_Shade_Benefit_Evaluator

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 helpful winter sun than harmful
summer sun). Desaturated cells indicate that shading the cell will have relatively little effect
on thermal comfort. The units for shade desirability are degree-days, which are essentially
the amount of time in days that sun is blocked by a given cell multiplied by the degrees
above (or below) the _balanceTemperature during that time. So, if a given square meter of
_testShade has a shade desirability of 10 degree-days, this means that a shade in this
location provides roughly 1 day of sun protection from conditions 10 degrees celcius warmer
than the balanceTemperature to 1 square meter of testRegion. More information on the
methods sued by this component can be found in the following publication: Mackey,
Christopher; Sadeghipour Roudsari, Mostapha; Samaras, Panagiotis. “ComfortCover: A
Novel Method for the Design of Outdoor Shades.” In Proceedings of Symposium on
Simulation for Archoitecture and Urban Design. Washington, DC, United States, Apr 12-15
2015. https://drive.google.com/file/d/0Bz2PwDvkjovJQVRTRHhMSXZWZjQ/view?
usp=sharing -

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]

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]

202
Comfort_Shade_Benefit_Evaluator

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]

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 degrees off from the y-axis to make North. The default
North direction is set to the Y-axis (0 degrees).

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

203
Comfort_Shade_Benefit_Evaluator

legendPar [Optional]

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.

bakeIt [Optional]

An integer that tells the component if/how to bake the bojects in the Rhino scene. The
default is set to 0. Choose from the following options: 0 (or False) - No geometry will be
baked into the Rhino scene (this is the default). 1 (or True) - The geometry will be baked
into the Rhino scene as a colored hatch and Rhino text objects, which facilitates easy
export to PDF or vector-editing programs. 2 - The geometry will be baked into the Rhino
scene as colored meshes, which is useful for recording the results of paramteric runs as
light Rhino geometry.

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

204
Comfort_Shade_Benefit_Evaluator

colors).

legend

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 degree-days helped by shading the given cell. If a given square meter
of testShade has a shade helpfulness of 10 degree-days, this means that a shade in
this location provides roughly 1 day of sun protection from conditions 10 degrees celcius
warmer than the balanceTemperature to 1 square meter of _testRegion.

shadeHarmfulness

The cumulative degree-days harmed by shading the given cell. If a given square meter
of testShade has a shade harmfulness of -10 degree-days, this means that a shade in
this location blocks roughly 1 day of sun duirng conditions that are 10 degrees celcius
colder than the balanceTemperature to 1 square meter of _testRegion.

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

205
Shading_Mask

Shading Mask - [source code]

Use this component to see the portion of the sky dome that is masked by context geometry
around a given point. 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). -output

Inputs
centerPtOrPlane [Default]

206
Shading_Mask

A point or plane from which the visible portion of the sky will be evaluated. If a point is
input here, the component will calculate Sky Exposure (or the fraction of the sky
hemisphere that is visible from the point). If a plane is input here, the component will
calculate Sky View (or the fraction of the sky visible from a surface in this plane). If no
value is input here, the component will assume a point (Sky Exposure) at the Rhino
origin.

context [Optional]

Context geometry surrounding the centerPtOrPlane that could block the view to the sky.
Geometry can be either a list of surfaces, breps, or meshes (this component converts
everything to a mesh for a fast calculation).

orientation [Optional]

A number between 0 and 360 that sets the orientation of a vertically-oriented surface for
which you want to visualize the sky view. Alternatively, this input can just be the words
"north", "east", "south" or "west." This will block out the portion of the sky that is not
visible from a vertical surface with this orientation. Note that an input here will project
the patches into the plane of this vertical orientation to calculate a Sky View result
(overriding any plane input to the centerPtOrPlane). The default is set to have no
orientation.

overhangProject [Optional]

A number between 0 and 90 that sets the angle between the centerPtOrPlane and the
edge of an imagined horizontal overhang projecting past the point. Note that this option
is only available when there is an input for orientation_ above. This allows one to
visualise the portion of the sky blocked by an overhang with this projection anle.

leftFinProject [Optional]

A number between 0 and 180 that sets the angle between the centerPtOrPlane and the
edge of an imagined vertical fin projecting past the left side of the point. Note that this
option is only available when there is an input for orientation_ above. This allows one to
visualise the portion of the sky blocked by vertical fin on the left side of the point with
this projection anle.

rightFinProject [Optional]

A number between 0 and 180 that sets the angle between the centerPtOrPlane and the
edge of an imagined vertical fin projecting past the right side of the point. Note that this
option is only available when there is an input for orientation_ above. This allows one to
visualise the portion of the sky blocked by vertical fin on the right side of the point with

207
Shading_Mask

this projection anle.

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. Higher
numbers input here will ensure a greater accuracy but will also take longer. The default
is set to 3 to give you an error that is usually less than 1% sky view. It is recommended
that you use values of 3 or above for accurate results.

projection [Default]

A number to set the projection of the sky hemisphere. The default is set to draw a 3D
hemisphere. Choose from the following options: 0 = 3D hemisphere 1 = Orthographic
(straight projection to the XY Plane) 2 = Stereographic (equi-angular projection to the
XY Plane)

scale [Default]

Use this input to change the scale of the sky dome. The default is set to 1.

bakeIt [Optional]

An integer that tells the component if/how to bake the bojects in the Rhino scene. The
default is set to 0. Choose from the following options: 0 (or False) - No geometry will be
baked into the Rhino scene (this is the default). 1 (or True) - The geometry will be baked
into the Rhino scene as a colored hatch and Rhino text objects, which facilitates easy
export to PDF or vector-editing programs. 2 - The geometry will be baked into the Rhino
scene as colored meshes, which is useful for recording the results of paramteric runs as
light Rhino geometry.

Outputs
contextMask

A mesh of the portion of the sky dome masked by the context_ geometry.

orientationMask

A mesh of the portion of the sky dome masked by the fact that a surface is facing a
given orientation.

strategyMask

208
Shading_Mask

A mesh of the portion of the sky dome masked by the overhang, left fin, and right fin
projections.

skyMask

A mesh of the portion of the sky dome visible by the centerPtOrPlane through the
context_ geometry.

contextExposure

The percentage of the hemispherical sky dome masked by the context_ geometry.

orientExposure

The percentage of the hemispherical sky dome masked by the fact that a surface is
facing a given orientation.

strategyExposure

The percentage of the hemispherical sky dome masked by the overhang, left fin, and
right fin projections.

skyExposure

The percentage of the hemispherical sky dome visible through the context_ geometry
and the strategy geometry.

Check Hydra Example Files for Shading Mask

209
SolarEnvelope

SolarEnvelope - [source code]

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.

210
SolarEnvelope

obstacleCrvs [Required]

List of curves indicating the top borders of our surroundings that are taken into account
in calculating the solar collection.

sunVectors [Required]

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.

211
SolarEnvelope

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

212
SolarFan

SolarFan - [source code]

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]

213
SolarFan

A surface representing a piece of land (such as a park) or a window for which solar
access is desired.

sunVectors [Required]

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.

noUnion [Optional]

By default this component will attempt to boolean union all the solar fans created,
sometimes the underlying boolean union rhino operation fails and as a result only some
of the solar fans are created. When this happens you can set this input to false and the
boolean union operation will not be performed on the solar fans ensuring that all solar
fans will be created.

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

214
Sun_Shades_Calculator

Sun_Shades_Calculator - [source code]

Use this component to generate shading devices, either surface or pergola, for any glazed
surface or list of glazed surfaces.
The component first culls all sun vectors obstructed by the context, if provided. By default it
calculates the device as a "new brand" one but it also can calculate the cut profile for a given
surface. The default it will generate an overhang over the window (or multiple overhangs if
the _numOfShds is increased).
References: Shaviv E., 1975. "A Method for the Design of Fixed External Sun-Shades".
"Build International" (8), Applied Science Publishers LTD, England, (pp.121-150). Shaviv E.,
1984. "A Design Tool for Determining the Form of Fixed & Movable Sun-Shades". "ASHRAE
Trans." Vol. 90, AT-84-18 No. 4, Atlanta (pp.1-14). -

215
Sun_Shades_Calculator

Inputs
SurfaceOrPergola [Default]

0= Device optimised for period, will give the horizontal or tilted surface over the top of
the window, or the cut profile device on a provided shading surface. 1= Pergola with
fins. Default is 0.

window [Required]

A Surface or Brep representing a window to be used for shading design. This can also
be a list of Surfaces of Breps.

numOfShds [Default]

The number of shades to generated for each glazed surface.

udiv [Default]

Number of row divisions of the window. Used for choosing the lower and higher rows
you want to protect. Default is 1.

sunVectors [Required]

Output of Ladybug sunPath component.

context [Optional]

Breps/surfaces that you want to account for as blocking objects.

shadeSurface [Optional]

An optional shade surface representing a 2D area under consideration for shading.

shdSrfAngle [Default]

In case NO shadeSurface is provided a plane over the window will be used as base for
the calculation. In this case you can provide the angle of this plane. Default is 0.0.

shdSrfShift [Default]

In case NO shadeSurface is provided a plane over the window will be used as base for
the calculation. In this case you can provide a shift distance from top of the window.
Default is 0.01

delaunayHeight [Default]

216
Sun_Shades_Calculator

Distance from base curve and top intersection points. Used by the Delauney Mesh
component. Default is 5.

offsetFactor [Default]

VERY important input!! The offset factor for the ConvexHull curve. Will be used for the
Delauneay mesh. Default is 40.

cullRes [Default]

Resolution for culling points. 0=Don't cull, 1= Regular cull, 2= Cull a lot. Check the final
surface for quality of results, 3= Extreme cull. Be carefull with the results. Default is 1.

Outputs
readMe!

...

pointsOnWindow

Net of points on window

uPoints

Net of points on window

ptsContext

Show the intersection point of sun vectors with context

cullPts

Show the points that define the contour of the shading device. Pay attention to those
more/less dense areas covered by these points.

finalSrf

Surface representing the shape of the shading device.

Check Hydra Example Files for Sun_Shades_Calculator

217
Cone_Of_Vision

Cone Of Vision - [source code]

Use this component to generate and visualize cones of vision. - This component can help
you to customize view analysis. Plug its outputs into Ladybug_View Analysis. - Car at 25
mph, Car at 45 mph, Car at 65 mph (horizontal angle, distance limits) Source: U. S. Bureau
of Land Management. Visual Resource Management Program (Course 8400-05) 2008. -
Human, Color Recognition, Sign Recognition, Word Recognition (horizontal angle) Human,
Color Recognition, Optimal Video Display Area (vertical angle) Source: INO - CNR Istituto
Nazionale di Ottica www.ino.it Titolo: Il processo della Visione e Stereoscopia Relatore: Luca
Mercatelli 16 aprile 2010 Polo viale. -

Inputs

218
Cone_Of_Vision

type [Optional]

This input sets the cone of vision, the cone is defined by four values that are vertical
angle+, vertical angle-, horizontal angle+, horizontal angle-, distance limits. - Connect a
number from 0 to 9. The default is set to 0. - 0 = Human (50°, 70°, 62°, 62°, 10 meters)
1 = Peripheral vision (60°, 70°, 60°, 60°, 10 meters) 2 = Outdoor (90°, 15°, 180°, 180°,
100 meters) 3 = Car at 25 mph (50°, 15°, 50°, 50°, 182.88 meters) 4 = Car at 45 mph
(50°, 15°, 33°, 32.5°, 365.76 meters) 5 = Car at 65 mph (50°, 15°, 22°, 20°, 609.60
meters) 6 = Color Recognition (30°, 40°, 30°, 30°, 10 meters) 7 = Sign Recognition (30°,
40°, 15°, 15°, 10 meters) 8 = Word Recognition (30°, 40°, 5°, 5°, 10 meters) 9 = Optimal
Video Display Area (0°, 30°, 30°, 30°, 10 meters) - If no value is provided, it will be 2
("Outdoor").

viewPoint [Default]

The point of vision in which to generate the cone of vision. If not supplied, default value
will be the Rhino origin.

viewDirection [Default]

A vector that represents the view direction. If not supplied, default value will be the
vector of Y-Axis.

distanceLimit [Optional]

Set the limit of the view. - This input let you customize the cone of vision.

vAngleUp [Optional]

The vertical angle of the upper visual field. A number from 0.0 to 90.0. - This input let
you customize the cone of vision.

vAngleDown [Optional]

The vertical angle of the lower visual field. A number from 0.0 to 90.0. - This input let
you customize the cone of vision.

hAngle [Optional]

The horizontal angle from the standard line of sight. A number from 0.0 to 180.0. - This
input let you customize the cone of vision.

Outputs
readMe!

219
Cone_Of_Vision

...

coneOfVision

Brep that represent the cone of vision.

parameters

Connect this list to Ladybug_View Analysis for customizing the view analysis. - the
parameters are vertical angle+ (°), vertical angle- (°), horizontal angle (°), distance limit
(meters), view direction in the horizontal plane (°). NB. 0° is the direction of green axis
of Rhino.

Check Hydra Example Files for Cone Of Vision

220
Forward_Raytracing

Forward Raytracing - [source code]

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

221
Forward_Raytracing

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 ray-
traced.

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

222
ShadingDesigner

ShadingDesigner - [source code]

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]

223
ShadingDesigner

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.

224
ShadingDesigner

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

225
SolarEnvelopeBasic

SolarEnvelopeBasic - [source code]

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

226
SolarEnvelopeBasic

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]

The output from the importEPW or constructLocation component. This is essentially a

list of text summarizing a location on the earth.

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]

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

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

227
SolarEnvelopeBasic

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

228
SolarFanBasic

SolarFanBasic - [source code]

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

229
SolarFanBasic

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]

The output from the importEPW or constructLocation component. This is essentially a

list of text summarizing a location on the earth.

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]

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

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 =

230
SolarFanBasic

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
readMe!

...

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

231
Steady_State_Surface_Temperature

Steady State Surface Temperature - [source

code]

Use this component to calculate a steady state interior/exterior surface temperature from
given given indoor/outdoor air temperatures and surface U-Values. Note that this component
does not currently account for solar radiation, which can greatly alter surface temperatures
in the real world. _ The formulas used to account for air film resistance in this component
come from ASHRAE Fundementals 2013, Chapter 26, Table 10 (26.20). -

Inputs

232
Steady_State_Surface_Temperature

outTemp [Required]

A number (or list of numbers) that represent the outdoor air temperature in degrees
Celcius.

inTemp [Required]

A number (or list of numbers) that represent the indoor air temperature in degrees
Celcius.

uValue [Required]

A number that represents the U-Value of the surface dividing the interior and exterior in
SI (W/K·m2).

intEmiss [Optional]

A number between 0 and 1 that represents the interior emissivity of the surface dividing
the interior and exterior. The default is set to 0.9 for a non-metallic surface.

srfOrient [Optional]

A number between 180 (downwards) and 0 (upwards) that represents the angle in
degrees of the direction of heat flow. This is related to the orientation of the surface
dividing the interior and exterior. This input can also be the normal vector of a surface
that is facing the correct direction of heat flow. The default is set to 90 degrees for a
verically-oriented surface (horizontal heat flow).

outWindSpd [Optional]

A number (or list of numbers) that represents the outdoor wind speed in m/s. This is
used to calculate the outdoor film coefficient. If no value is input here, a default of 6.7
m/s will be assumed (indicating a winter design day).

Outputs
inFilmCoeff

The interior film coefficient as calculated by the interior emissivity, surface orientation
and Chapter 26, Table 10 of AHSHRAE Fundemantals.

extFilmCoeff

Script variable ssSrfTemp

inSrfTemp

233
Steady_State_Surface_Temperature

The steady state interior surface temperature in degrees Celcius.

extSrfTemp

The steady state exterior surface temperature in degrees Celcius.

Check Hydra Example Files for Steady State Surface Temperature

234
Surface_View_Analysis

Surface View Analysis - [source code]

Use this component to calculate view factors from a point or plane to a set of surfaces. View
factors are used in many thermal comfort calculations such as mean radiant temperture
(MRT) or discomfort from radiant assymetry. -

Inputs
testPtsOrPlanes [Required]

A point or plane from which view vectors will be pojected. Note that, if a point is
connected, all view vectors will be weighted evenly (assuming no directional bias).

235
Surface_View_Analysis

However, if a plane is connected, vectors will be weighted based on their angle to the
plane normal, producing view factors for a surface in the connected plane. The first is
useful for MRT calculations while the latter is needed for radiant assymetry calculations.
This input can also be a list of points or planes.

testSrfs [Required]

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

context [Optional]

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

viewResolution [Default]

An interger, which sets the number of times that the tergenza skyview patches are split.
A higher number will ensure a greater accuracy but will take longer. The default is set to
0 for a quick calculation.

parallel [Optional]

Set to "True" to run the calculation in parallel and set to "False" to run it with a single
core. The default is set to "False."

runIt [Required]

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

Outputs
readMe!

...

srfViewFactors

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

viewVecSrfIndex

236
Surface_View_Analysis

The index of the surface that each view vector hit. This can be used to identify which
view pathces are intersected by each surface. If no surfaces are intersected, this value
will be -1.

viewVectors

The view vectors that were projected from each testPtOrPlane.

viewPatches

The patches of the sphere that each view vector correspond to.

viewPatchBasePt

The center of the viewPatches sphere. This can be used to move the view patches
between the testPts.

Check Hydra Example Files for Surface View Analysis

237
Window_Downdraft

Window Downdraft - [source code]

Use this component to compute the floor-level downdraft air temperature and velocity at a
given set of points that are located close to a cold surface such as a window. The draft
conditions produced by this model are assumed to be 10 cm off of the floor. The model used
in this component comes from physical measurements of window downdraft that were
further validated using several CFD experiments. Ther are published in these papers:
Heiselberg, P. (1994). “Draft Risk from Cold Vertical Surfaces.” Building and Environment,
29: 297-301. Manz, H. and Frank, T. (2003). "Analysis of Thermal Comfort near Cold Vertical
Surfaces by Means of Computational Fluid Dynamics." Indoor Built Environment. 13: 233-
242. -

238
Window_Downdraft

Inputs
testPts [Required]

The test points at which downdraft conditions will be evaluated.

windowSrfs [Required]

Breps or Surfaces representing the window surfaces off of which downdraft flows.

winSrfTemp [Required]

A number representing the surface temperature of the windows in degrees Celcius.

airTemp [Required]

A number representing the air temperature of the room in degrees Celcius.

defaultVeloc [Optional]

A number in m/s that represents the speed of the air that is not in the downdraft. The
default is set to 0.05 m/s.

runIt [Required]

Set to 'True' to run the component and claculate downdraft conditions.

Outputs
draftAirTemp

Script output PPD.

draftAirVeloc

Script variable downDraft

airFlowPlanes

Script variable downDraft

Check Hydra Example Files for Window Downdraft

239
4 | Renewables

Component list:

Photovoltaics_Surface
Solar_Water_Heating_Surface
PV_SWH_System_Size
Photovoltaics_Performance_Metrics
Sunpath_Shading
Tilt_And_Orientation_Factor
Cold_Water_Temperature
Commercial_Public_Apartment_Hot_Water
Residential_Hot_Water
Solar_Water_Heating_Performance_Metrics
Solar_Water_Heating_System
Solar_Water_Heating_System_Detailed
DC_to_AC_derate_factor
Import_CEC_Photovoltaics_Module
Import_Sandia_Photovoltaics_Module
Simplified_Photovoltaics_Module

240
Photovoltaics_Surface

Photovoltaics Surface - [source code]

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) and thin-film 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

241
Photovoltaics_Surface

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 "Simplified Photovoltaics Module" or "Import

Sandia Photovoltaics Module" or "Import CEC Photovoltaics Module" components to
generate them. - If not supplied, the following PV module settings will be used by
default:
module material: crystalline silicon (c-Si)
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).

242
Photovoltaics_Surface

albedo [Optional]

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.

annualHourlyData [Optional]

An optional list of hourly data from Ladybug's "Import epw" component (e.g.
dryBulbTemperature), which will be used for "conditionalStatement_".

conditionalStatement [Optional]

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="" 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="" 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.

243
Photovoltaics_Surface

ACenergyPerYear

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.

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

244
Solar_Water_Heating_Surface

Solar Water Heating Surface - [source code]

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

245
Solar_Water_Heating_Surface

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]

Input .epw file path by using the "File Path" parameter, or Ladybug's "Open EPW And
STAT Weather Files" component.

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:
glazed flat plate collectors
active

246
Solar_Water_Heating_Surface

closed loop
pipe length: 20 meters
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]

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.

annualHourlyData [Optional]

An optional list of hourly data from Ladybug's "Import epw" component (e.g.
dryBulbTemperature), which will be used for "conditionalStatement_".

conditionalStatement [Optional]

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="" 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="" time="" period="" when=""
temperature="" is="" between="" 18°c="" 23°c,="" 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.

247
Solar_Water_Heating_Surface

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.

248
Solar_Water_Heating_Surface

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

249
PV_SWH_System_Size

PV SWH System Size - [source code]

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.

250
PV_SWH_System_Size

PVmoduleSettings [Required]

A list of PV module settings. Use the "Simplified Photovoltaics Module" or "Import CEC
Photovoltaics Module" or "Import Sandia Photovoltaics Module" components 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]

251
PV_SWH_System_Size

Number of rows to which PV or SWH array will be divided to. - If not supplied, 1 will be
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. - Use Ladybug "Analysis Period"
component to define this input. - 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.

252
PV_SWH_System_Size

arrayOriginCorner [Optional]

Corner at which the PV/SWH array begins: - 0 - center bottom 1 - left bottom 2 - right
bottom 3 - center top - If not supplied, 0 will be used as a default (bottom center).

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

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 "Residential Hot Water" or "Commercial Public Apartment
Hot Water" components to calculate it (simply plugin their "heatingLoadPerHour"
outputs). - 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...).

minimalSpacing

Minimal distance between fixed (anchor) points of rows. The distance is measured on
the ground (or along the base surface if it has been inputted). - In meters.

minimalSpacingDate

253
PV_SWH_System_Size

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.

Check Hydra Example Files for PV SWH System Size

254
Photovoltaics_Performance_Metrics

Photovoltaics Performance Metrics - [source

code]

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

255
Photovoltaics_Performance_Metrics

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 percent (all surface area will be
covered in PV modules) is used. - In percent.

PVmoduleSettings [Optional]

A list of PV module settings. Use the "Simplified Photovoltaics Module" or "Import

Sandia Photovoltaics Module" or "Import CEC Photovoltaics Module" components to
generate them. - If not supplied, the following PV module settings will be used by
default:
module material: crystalline silicon (c-Si)
moduleType: Close (flush) roof mount
moduleEfficiency: 15 %
temperatureCoefficient: -0.5 %/C
moduleActiveAreaPercent: 90 %

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

256
Photovoltaics_Performance_Metrics

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. - If not
supplied default value of 4410 (MJ/m2) will be used. - In MJ/m2 (megajoules per square
meter).

embodiedCO2PerM2 [Optional]

Carbon emissions produced during PV module's life-cycle per square meter. - If not
supplied default value of 225 (kg CO2/m2) will be used. - In kg CO2/m2 (kilogram of
CO2 per square meter).

lifetime [Optional]

Life expectancy of a PV module. - If not supplied default value of 30 (years) will be

used. - In years.

gridEfficiency [Optional]

An average primary energy to electricity conversion efficiency. - If not supplied default

value of 29 (perc.) will be used. - In percent.

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

257
Photovoltaics_Performance_Metrics

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

258
Photovoltaics_Performance_Metrics

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

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

259
Photovoltaics_Performance_Metrics

260
Sunpath_Shading

Sunpath Shading - [source code]

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 "skyExposureFactor" outputs for Solar Water Heating
collectors shading, or any other purpose. Use "shadedSolarRadiationPerHour" data for
"solarRadiationPerHour_" input of "Thermal Comfort Indices" component to account for
shading. - "annualShading" output is based on "Using sun path charts to estimate the

261
Sunpath_Shading

effects of shading on PV arrays", University of Oregon, Frank Vignola:

http://solardat.uoregon.edu/download/Papers/UsingSunPathChartstoEstimatetheEffecto
fShadingonPVArrays.pdf -

Inputs
epwFile [Required]

Input .epw file path by using the "File Path" parameter, or Ladybug's "Open EPW And
STAT Weather Files" component.

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. 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. - Input
polysurfaces, surfaces, or meshes.

coniferousAllyearIndex [Optional]

262
Sunpath_Shading

All year round transmission index for coniferous(evergreen) context trees. 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.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 skyExposureFactor,
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

263
Sunpath_Shading

you are calculating shading analysis for any other purpose (of point(s) for example)
leave this input empty too.

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]

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 _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 20 will be used.

264
Sunpath_Shading

legendPar [Optional]

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

bakeIt [Optional]

Set to "True" to bake the Sunpath shading results into the Rhino scene. - Baking can
only be used if surface(s) is(are) inputted into analysisGeometry and data is inputted in
ACenergyPerHour. Otherwise there will be nothing to be baked. - If not supplied default
value "False" will be used.

runIt [Required]

...

Outputs
readMe!

...

skyExposureFactor

Continuous Sky Exposure Factor - portion of the visible sky (dome). It defines the
shading of the diffuse irradiance components. 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
for Ladybug "Solar Water Heating System" or "Solar Water Heating System Detailed"
component's "skyExposureFactor_" 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

265
Sunpath_Shading

Total shaded incidence for each hour during a year. Data from this output can be used
for "solarRadiationPerHour_" input of "Thermal Comfort Indices" component to account
for shading. - In Wh/m2.

Sep21toMar21Shading

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 "sunWindowCenPt" point in the Rhino scene.

sunWindowCrvs

Geometry of the sun window based on 3D polar sun path diagram. Perpendicular

266
Sunpath_Shading

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

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.

267
Sunpath_Shading

hours

Solar time hour strings. - Use grasshopper's "Text tag" component to visualize them.

Check Hydra Example Files for Sunpath Shading

268
Tilt_And_Orientation_Factor

Tilt And Orientation Factor - [source code]

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]

Input .epw file path by using the "File Path" parameter, or Ladybug's "Open EPW And

269
Tilt_And_Orientation_Factor

STAT Weather Files" component.

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]

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]

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.

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. - If not supplied, default value of 20 will be used.

scale [Optional]

Scale of the overall geometry. - If not supplied, default value of 1 will be used.

270
Tilt_And_Orientation_Factor

origin [Optional]

Origin for the final "geometry" output. - If not supplied, default point of (-15,0,0) will be
used.

legendPar [Optional]

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

analysisPeriod [Optional]

Script variable TOF

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 (°).

271
Tilt_And_Orientation_Factor

PVsurfaceAzimuth

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

272
Tilt_And_Orientation_Factor

Legend base point, which can be used to move the "legend" geometry with
grasshopper's "Move" component.

Check Hydra Example Files for Tilt And Orientation Factor

273
Cold_Water_Temperature

Cold Water Temperature - [source code]

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-2013-
003/CEC-400-2013-003-CMF-REV.pdf http://www.nrel.gov/docs/fy04osti/35917.pdf
http://www.solarthermalworld.org/sites/gstec/files/story/2015-05-31/textbook_swh.pdf -

Inputs
method [Optional]

A method by which the cold water temperature will be calculated: - 0 - Carslaw and

274
Cold_Water_Temperature

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.

dryBulbTemperature [Required]

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 1°C (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

275
Cold_Water_Temperature

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

276
Commercial_Public_Apartment_Hot_Water

Commercial Public Apartment Hot Water -

[source code]

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

277
Commercial_Public_Apartment_Hot_Water

primary school
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
rooms: hotel/motel
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

278
Commercial_Public_Apartment_Hot_Water

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,
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]

Total number of hours in a single day during which the chosen buildingType will be
used. It can not be less than 1 nor larger than 24. Also it can not exceed the 24 when
summed with occupancyStartingHour. - 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

279
Commercial_Public_Apartment_Hot_Water

taken as a default weekend days.

holidayDays [Optional]

List of days (1 to 365) which are holiday (nonworking) days. - If not supplied, no holiday
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 60°C (140°F) to avoid the risk of Legionella
pneumophila bacteria appearance. - If not supplied, default value: 60°C (140°F) 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).

280
Commercial_Public_Apartment_Hot_Water

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 Commercial Public Apartment Hot Water

281
Residential_Hot_Water

Residential Hot Water - [source code]

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_lbl-
37805_rev.pdf -

Inputs
epwFile [Required]

282
Residential_Hot_Water

Input .epw file path by using the "File Path" parameter, or Ladybug's "Open EPW And
STAT Weather Files" component.

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.

283
Residential_Hot_Water

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.

deliveryWaterTemperature [Optional]

Required (set) water temperature. It is recommended for delivery water temperature to

not be lower than 60°C (140°F) to avoid the risk of propagation of Legionella
pneumophila bacteria. - Electric water heater used as a default. - If not supplied, default
value: 60°C (140°F) 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!

...

284
Residential_Hot_Water

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

285
Solar_Water_Heating_Performance_Metrics

Solar Water Heating Performance Metrics -

[source code]

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.

286
Solar_Water_Heating_Performance_Metrics

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"

component. - In kWh.

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"

component. - 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. - In currency/kWh.

collectorEmbodiedEnergyPerM2 [Optional]

Energy necessary for product life-cycle of SWH collector per square meter. - If not

287
Solar_Water_Heating_Performance_Metrics

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

288
Solar_Water_Heating_Performance_Metrics

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

289
Solar_Water_Heating_Performance_Metrics

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

290
Solar_Water_Heating_System

Solar Water Heating System - [source code]

Use this component to define Solar water heating system settings. - If nothing inputed, the
following swh system will be used by default:

glazed flat plate collectors

active
closed loop
1 story
unshaded -

Inputs

291
Solar_Water_Heating_System

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 30°C (86°F). - 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 60°C (140°F). - 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 90°C (194°F) degrees, up to 177°C
(350°F). - - 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 mild-
warm 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 back-
up 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 5°C(41°F) degrees). Only suitable for locations with low water hardness
(mineral content) otherwise limescale will form in solar collectors. - - If not supplied,

292
Solar_Water_Heating_System

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

skyExposureFactor [Optional]

Continuous Sky Exposure Factor - portion of the visible sky (dome). It defines the
shading of the diffuse irradiance components. It ranges from 0 to 1. Import it from
"Sunpath shading" component's "skyExposureFactor" output. - If not supplied, 1 will be
used as a default value (SWHsurface is unshaded). - Unitless.

beamIndexPerHour [Optional]

Transmission index of beam (direct) irradiance for each hour during a year. It ranges
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

293
Solar_Water_Heating_System

294
Solar_Water_Heating_System_Detailed

Solar Water Heating System Detailed -

[source code]

Use this component to define a detailed Solar water heating system settings. - If nothing
inputed, the following swh system will be used by default:

glazed flat plate collectors

active
closed loop
pipe length: 20 meters
unshaded -

295
Solar_Water_Heating_System_Detailed

Inputs
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 non-
freezing 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 -10°C: water-
propylenglycol 25%: 4080 J/kg/°C. up to -10°C: water-ethylenglycol 20%: 4020 J/kg/°C.
up to -20°C: water-propylenglycol 38%: 4000 J/kg/°C. up to -20°C: water-ethylenglycol
34%: 3840 J/kg/°C. up to -30°C: water-propylenglycol 47%: 3890 J/kg/°C. up to -40°C:
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.

296
Solar_Water_Heating_System_Detailed

IAMcoefficient [Optional]

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.

skyExposureFactor [Optional]

Continuous Sky Exposure Factor - portion of the visible sky (dome). It defines the
shading of the diffuse irradiance components. It ranges from 0 to 1. Import it from
"Sunpath shading" component's "skyExposureFactor" output. - If not supplied, 1 will be
used as a default value (SWHsurface is unshaded). - Unitless.

beamIndexPerHour [Optional]

Transmission index of beam (direct) irradiance for each hour during a year. It ranges
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-99°C. - If not supplied 95°C (203°F)
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-3°C degrees less than maximal working temperature. - If
not supplied maxWorkingTemperature-3°C will be used. - In °C.

deliveryWaterTemperature [Optional]

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 60°C
(140°F). For space heating, it varies from 33 to 82°C (90 to 180°F) depending on the
type (in-floor tubes, radiators/baseboards, heat exchanger inside a forced-air heater).
For space cooling it varies from 60 to 80°C (140 to 176°F) depending on the cooling
system used. - If not supplied, default value: 60°C (140°F) will be used. - In °C.

297
Solar_Water_Heating_System_Detailed

avrJanuaryColdWaterTemperature [Optional]

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 20°C 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]

298
Solar_Water_Heating_System_Detailed

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

299
Solar_Water_Heating_System_Detailed

heightDiameterTankRatio [Optional]

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

300
DC_to_AC_derate_factor

DC to AC derate factor - [source code]

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

301
DC_to_AC_derate_factor

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 high-
traffic, 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 current-
voltage 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

302
DC_to_AC_derate_factor

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

303
Import_CEC_Photovoltaics_Module

Import CEC Photovoltaics Module - [source

code]

Use this component to import Photovoltaics module settings for particular module from
"California Energy Commission (CEC) Modules" library. Download library's newest version
from the bottom of the following page: https://sam.nrel.gov/libraries -

Inputs
modulesLibraryFile [Required]

Add "California Energy Commission (CEC) Modules" .csv file path to this input. -

304
Import_CEC_Photovoltaics_Module

Download its newest version on the bottom of this web page sam.nrel.gov/libraries

moduleIndex [Optional]

An index corresponding to chosen module from "allModuleNames" output. - If nothing

added to this input, "0" will be used as a default (the first module from the
"allModuleNames" output will be chosen).

newModuleMountType [Optional]

New mounting type (configuration) of the module. Each module from

"_modulesLibraryFile" input comes with predefined mounting type (configuration). You
can see it in "moduleMountType" output. If you would like to change that predefined
mounting type, then use this input, and the following values: - 0 = Insulated back (pv
curtain wall, pv skylights, BIPV installations with obstructed backside airflow) 1 = Close
(flush) roof mount (pv array mounted parallel and relatively close to the plane of the roof
(between 5 and 15 centimenters)) 2 = Open rack (ground mount array, flat/sloped roof
array that is tilted, pole-mount solar panels, solar carports, solar canopies, BIPV
installations with sufficient backside airflow) - This input is actually the same as
"mountType" input of the Ladybug "Simplified Photovoltaics Module" component. - If
nothing is added to this input, default mount type of the chosen module will be used
(you can check which one by looking at the "moduleMountType" output).

moduleHeightAboveGround [Optional]

Height (vertical distance) from ground surface to the lowest part of the module. - If not
supplied, default value of 3 meters (10 feet) will be used. - In Rhino document units
(meters, feet, inches...).

moduleActiveAreaPercent [Optional]

Percentage of the module's area excluding module framing and gaps between cells. - If
not supplied, default value of 90(perc.) will be used. - In percent.

Outputs
readMe!

...

allModuleNames

Names of all crystalline silicon modules from the "_modulesLibraryFile" file.

305
Import_CEC_Photovoltaics_Module

moduleName

Name of the chosen module, according to "moduleIndex_" input.

moduleMaterial

Material of the chosen module.

moduleMountType

Final mount type (configuration) of the chosen module. This output can have two
values: - a) default one: coming directly from "modulesLibraryFile". This value will only
appear if "newModuleMountType" input is empty. b) custom one: altered mounting type,
according to "newModuleMountType_" input. - One of the following mount types will be
shown: - 0 = Insulated back (pv curtain wall, pv skylights, BIPV installations with
obstructed backside airflow) 1 = Close (flush) roof mount (pv array mounted parallel and
relatively close to the plane of the roof (between 5 and 15 centimenters)) 2 = Open rack
(ground mount array, flat/sloped roof array that is tilted, pole-mount solar panels, solar
carports, solar canopies, BIPV installations with sufficient backside airflow)

moduleArea

Area of the chosen module. - In square meters.

modulePower

Module's power at maximum-power point of the chose module. - In Watts.

moduleEfficiency

Module's aperture (active area) efficiency. - In percent (%).

sourceNotes

Source notes corresponding to the chosen module. It basically contains source from
which the "PVmoduleSettings" output data has been generated, and date when it has
been generated.

PVmoduleSettings

A list of PV module settings. Plug it to "Photovoltaics surface" component's

"PVmoduleSettings_" input.

Check Hydra Example Files for Import CEC Photovoltaics Module

306
Import_CEC_Photovoltaics_Module

307
Import_Sandia_Photovoltaics_Module

Import Sandia Photovoltaics Module -

[source code]

Use this component to import Photovoltaics module settings for particular module from
"Sandia National Laboratories Modules" library. Download library's newest version from the
bottom of the following page: https://sam.nrel.gov/libraries -

Inputs
modulesLibraryFile [Required]

Add "Sandia National Laboratories Modules" .csv file path to this input. - Download its

308
Import_Sandia_Photovoltaics_Module

newest version on the bottom of this web page sam.nrel.gov/libraries

moduleIndex [Optional]

An index corresponding to chosen module from "allModuleNames" output. - If nothing

added to this input, "0" will be used as a default (the first module from the
"allModuleNames" output will be chosen).

newModuleMountType [Optional]

New mounting type (configuration) of the module. Each module from

"_modulesLibraryFile" input comes with predefined mounting type (configuration). You
can see it in "moduleMountType" output. If you would like to change that predefined
mounting type, then use this input, and the following values: - 0 = Insulated back (pv
curtain wall, pv skylights, BIPV installations with obstructed backside airflow) 1 = Close
(flush) roof mount (pv array mounted parallel and relatively close to the plane of the roof
(between 5 and 15 centimenters)) 2 = Open rack (ground mount array, flat/sloped roof
array that is tilted, pole-mount solar panels, solar carports, solar canopies, BIPV
installations with sufficient backside airflow) - This input is actually the same as
"mountType" input of the Ladybug "Simplified Photovoltaics Module" component. - If
nothing is added to this input, default mount type of the chosen module will be used
(you can check which one by looking at the "moduleMountType" output).

moduleActiveAreaPercent [Optional]

Percentage of the module's area excluding module framing and gaps between cells. - If
not supplied, default value of 90(perc.) will be used. - In percent.

Outputs
readMe!

...

allModuleNames

Names of all crystalline silicon modules from the "_modulesLibraryFile" file.

moduleName

Name of the chosen module, according to "moduleIndex_" input.

moduleMaterial

Material of the chosen module.

309
Import_Sandia_Photovoltaics_Module

moduleMountType

Final mount type (configuration) of the chosen module. This output can have two
values: - a) default one: coming directly from "modulesLibraryFile". This value will only
appear if "newModuleMountType" input is empty. b) custom one: altered mounting type,
according to "newModuleMountType_" input. - One of the following mount types will be
shown: - 0 = Insulated back (pv curtain wall, pv skylights, BIPV installations with
obstructed backside airflow) 1 = Close (flush) roof mount (pv array mounted parallel and
relatively close to the plane of the roof (between 5 and 15 centimenters)) 2 = Open rack
(ground mount array, flat/sloped roof array that is tilted, pole-mount solar panels, solar
carports, solar canopies, BIPV installations with sufficient backside airflow)

moduleArea

Area of the chosen module. - In square meters.

modulePower

Module's power at maximum-power point of the chose module. - In Watts.

moduleEfficiency

Module's aperture (active area) efficiency. - In percent (%).

sourceNotes

Source notes corresponding to the chosen module. It basically contains source from
which the "PVmoduleSettings" output data has been generated, and date when it has
been generated.

PVmoduleSettings

A list of PV module settings. Plug it to "Photovoltaics surface" component's

"PVmoduleSettings_" input.

Check Hydra Example Files for Import Sandia Photovoltaics Module

310
Simplified_Photovoltaics_Module

Simplified Photovoltaics Module - [source

code]

Use this component to define simplified Photovoltaics crystalline silicon (c-Si) module
settings. - If nothing inputed, the following PV module settings will be used by default:

module material: crystalline silicon (c-Si)

mountType: Close (flush) roof mount
moduleEfficiency: 15%
temperatureCoefficient: -0.5 %/C
moduleActiveAreaPercent: 90% - If you would like to use a thin-film module, then use
the thin-film module from "Import Sandia Photovoltaics Module" or "Import CEC

311
Simplified_Photovoltaics_Module

Photovoltaics Module" components. Also for choosing a specific module, not a

simplified one, use one of those two components as well. - Sources:
http://prod.sandia.gov/techlib/access-control.cgi/2004/043535.pdf -

Inputs
mountType [Optional]

Mounting type (configuration) of a module. There are three of them: - 0 = Insulated back
(pv curtain wall, pv skylights, BIPV installations with obstructed bakside airflow) 1 =
Close (flush) roof mount (pv array mounted parallel and relatively close to the plane of
the roof (between 5 and 15 centimenters)) 2 = Open rack (ground mount array,
flat/sloped roof array that is tilted, pole-mount solar panels, solar carports, solar
canopies, BIPV installations with sufficient bakside airflow) - 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 14-
20% - 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.

312
Simplified_Photovoltaics_Module

Check Hydra Example Files for Simplified Photovoltaics Module

313
5 | Extra

Component list:

Gradient_Library
ImageViewer
ImageViewer
Legend_Parameters
Recolor_Mesh
SortByLayers
Adaptive_Comfort_Parameters
Body_Characteristics
PMV_Comfort_Parameters
Real_Time_Radiation_Analysis
Capture_View
Render_View
C2F
DOY_HOY
Day_Month_Hour
F2C
Generate_Mesh
Mesh-To-Hatch
Mesh_Threshold_Selector
Texture_Maker
North
True_North
False_Start_Toggle
Activities_Met_List
BTU2Wh
BTUft2Whm
Beaufort_Ranges
Cfm2M3s
CombineSolarEnvelopes
Comfort_Mannequin

314
5 | Extra

Construct_Time
Create_Legend
L2G
M3s2Cfm
MRT_Calculator
Orient_to_Camera
Orientation_Study_Parameters
Passive_Strategy_List
Passive_Strategy_Parameters
Separate_By_Normal
Set_the_View
Shading_Parameters_List
Wh2BTU
Whm2BTUft
fly
lux2ft-cd
ms2mph
rIP2rSI
uIP2uSI
uSI2uIP

315
Gradient_Library

Gradient Library - [source code]

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]

316
Gradient_Library

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 22 - Glare Potential 23 - Radiation
Benefit

Outputs
customColors

A series of colors to be plugged into the "Ladybug_Legend Parameters" component.

Check Hydra Example Files for Gradient Library

317
ImageViewer

ImageViewer - [source code]

Preview image files Please find the source code from:

https://github.com/MingboPeng/Ironbug

Inputs
imagePath [Optional]

one or a list of image file path.

coordinates [Optional]

318
ImageViewer

A list of points for extracting colors from the source image.

scale [Default]

Set this image viewport scale.

Outputs
imagePath

A new image marked with coordinates.

colors

Color infomation that extracted from the input image.

GIF

Generates an animated gif image when there is a list of images.

Check Hydra Example Files for ImageViewer

319
Legend_Parameters

Legend Parameters - [source code]

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

320
Legend_Parameters

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

321
Legend_Parameters

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

322
Recolor_Mesh

Recolor Mesh - [source code]

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]

323
Recolor_Mesh

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

lowBoundColor [Optional]

A color representing the higher boundary of the legend's numerical range, use the
Swatch component to specify a color.

highBoundColor [Optional]

A color representing the lowest boundary of the legend's numerical range, use the
Swatch component to specify a color.

legendPar [Optional]

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]

An integer that tells the component if/how to bake the bojects in the Rhino scene. The
default is set to 0. Choose from the following options: 0 (or False) - No geometry will be
baked into the Rhino scene (this is the default). 1 (or True) - The geometry will be baked
into the Rhino scene as a colored hatch and Rhino text objects, which facilitates easy

324
Recolor_Mesh

export to PDF or vector-editing programs. 2 - The geometry will be baked into the Rhino
scene as colored meshes, which is useful for recording the results of paramteric runs as
light Rhino geometry.

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

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

The colors associated with each face of the newMesh.

legendColors

The colors associated with each segment of the newLegend.

Check Hydra Example Files for Recolor Mesh

325
SortByLayers

SortByLayers - [source code]

Sort and group Rhino objects by layers. Please find the source code from:
https://github.com/MingboPeng/Ironbug

Inputs
K []

A list of Rhino objects that associated with sortable layers

A []

326
SortByLayers

Optional object list to sort synchronously

Outputs
K

Sorted objects by layers

Synchronously sorted objects

Grouped layer names

Check Hydra Example Files for SortByLayers

327
Adaptive_Comfort_Parameters

Adaptive Comfort Parameters - [source

code]

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

328
Adaptive_Comfort_Parameters

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
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 (EN-
15251) 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]

329
Adaptive_Comfort_Parameters

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

330
Body_Characteristics

Body Characteristics - [source code]

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

331
Body_Characteristics

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" 3 or "average sex". - 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/clo-
clothing-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.

332
Body_Characteristics

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.

metabolicRate [Optional]

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

333
Body_Characteristics

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

334
PMV_Comfort_Parameters

PMV Comfort Parameters - [source code]

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

335
PMV_Comfort_Parameters

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 infrequenlty-
occupied 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

336
PMV_Comfort_Parameters

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

337
Real_Time_Radiation_Analysis

Real Time Radiation Analysis - [source code]

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]

338
Real_Time_Radiation_Analysis

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

339
Capture_View

Capture View - [source code]

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]

340
Capture_View

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

transparBack [Optional]

Set to "True" to have a transparent background for the image and set to "False" to save

341
Capture_View

a picture using the Rhino viewport background color. The default is set to "False" for an
opaque background.

capture [Required]

Set to "True" to capture the image of the Rhino viewport and save it to your hard drive.

Outputs
imagePath

The filepath of the image taken with this component.

Check Hydra Example Files for Capture View

342
Render_View

Render View - [source code]

Use this component to render Rhino views and save them to your hard drive. This
component is fully-functional with both Rhino Render and V-Ray for Rhino. Other rendering
plugins may still work but are not fully supported yet. _ This component is particularly useful
if you are trying to create animations of Grasshopper geometry and want to automate the
capturing of views. -

Inputs
fileName [Required]

343
Render_View

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

renderTime [Optional]

An optional number in seconds that represents the time you anticipate the render
taking. This can be used to create rendered animations for V-Ray 3, which currently
does not have a dot net interface.

viewNames [Optional]

The Rhino viewport name which you would like to render. 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 render 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 render in pixels. If no value is provided
here, the component will set the height to that of the active Rhino viewport on your
screen.

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

saveAlpha [Optional]

Set to "True" to have an alpah image saved next to the RGB rendering and set to

344
Render_View

"False" to have only have the RGB image saved. The default is set to "False" to only
save the RGB.

capture [Required]

Set to "True" to render the image and save it to your hard drive.

Outputs
readMe!

The filepath of the image taken with this component.

imagePath

The filepath of the image taken with this component.

Check Hydra Example Files for Render View

345
C2F

C2F - [source code]

Use this component to convert temperatures from Celcius to Fahrenheit. -

Inputs
C [Required]

A temperature or list of temperatures in Celcius.

Outputs

346
C2F

The input temperatures converted to Fahrenheit.

Check Hydra Example Files for C2F

347
DOY_HOY

DOY_HOY - [source code]

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]

348
DOY_HOY

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

349
Day_Month_Hour

Day_Month_Hour - [source code]

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

350
Day_Month_Hour

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

351
F2C

F2C - [source code]

Use this component to convert temperatures from Fahrenheit to Celcius. -

Inputs
F [Required]

A temperature or list of temperatures in Fahrenheit.

Outputs

352
F2C

The input temperatures converted to Celcius.

Check Hydra Example Files for F2C

353
Generate_Mesh

Generate Mesh - [source code]

Use this component to genrate a mesh with corresponding test points. The resulting mesh
will be in a format that the Recolor Mesh component will accept. -

Inputs
testGeometry [Required]

Test surface as a Brep.

gridSize [Required]

354
Generate_Mesh

Size of the test grid.

distBaseSrf [Required]

Distance from base surface.

moveTestMesh [Optional]

Set to 'False' if you want test mesh not to move. Default is 'True'.

Outputs
readMe!

...

testPoints

Test points

ptsVectors

Vectors

facesArea

Script output facesArea.

mesh

Analysis mesh

Check Hydra Example Files for Generate Mesh

355
Mesh-To-Hatch

Mesh-To-Hatch - [source code]

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.

356
Mesh-To-Hatch

layerName [Optional]

Optional text for the layer name on which the hatch will be added.

visible [Optional]

An optional boolean to set whether the layer that the hatch is baked on is visible. The
default is set to True to have the hatch layer visible.

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

357
Mesh_Threshold_Selector

Mesh Threshold Selector - [source code]

Use this component to select out the part of a colored mesh that meets a certain conditional
statement. This has multiple uses: The generation of a custom shade from a shade benefit
analysis, Quantifying the daylight area from a daylight analysis, Selecting out the portion of a
roof with enough solar radiation for PV panels, and much more. -

Inputs
inputMesh [Required]

The mesh for which you would like to highlight the portion that meets a threshold.

358
Mesh_Threshold_Selector

analysisResult [Required]

A numerical data set whose length corresponds to the number of faces in the
_inputMesh.

operator [Default]

A text string representing an operator for the the conditional statement. The default is
set to be greater than (>). This must be an operator in python and examples include:
Greater Than < - Less Than = - Greater or Equal <= - Less or Equal == -
Equals

percentToKeep [Optional]

A number between 0 and 100 that represents the percentage of the mesh faces that you
would like to include in the resulting newColoredMesh. By default, this is set to 25%.

levelOfPerform [Optional]

An optional number that represents the threshold above which a given mesh face is
included in the newColoredMesh. An input here will override the percent input above.

Outputs
readMe!

...

totalValue

The sum of all of the values that meet the criteria multiplied by the mesh face area. For
example, if the _inputMesh is a radiation study mesh, this is equal to the total radiation
falling on the newColoredMesh. For an energy shade benefit mesh, this is the total
energy saved by a shade of this size.

areaMeetsThresh

The area of the newColoredMesh in Rhino model units.

newColoredMesh

A new colored mesh with the vlues below the threshold deleted out of it.

newMeshOutline

A set of curves outlining the portion of the mesh that is above the threshold.

359
Mesh_Threshold_Selector

Check Hydra Example Files for Mesh Threshold Selector

360
Texture_Maker

Texture Maker - [source code]

Use this component to generate textures from colored meshes. In order to export model as
*obj you should Bake the new mesh and apply texture to its layer material. It is also
compatible with Google Earth. How to use it: 1) connect colored mesh which comes from LB
analysis component 2) run the component The output are: a new mesh that you have to
bake and a texture that you should add to material of the layer where your mesh will be. -
Special thanks goes to the author of the function, Vincente Soler. .
http://www.grasshopper3d.com/forum/topics/how-to-render-mesh-colors -

Inputs

361
Texture_Maker

analysisMesh [Required]

A list of colored Meshes that comes from Grasshopper OR . "radiationMesh" of

"Ladybug_Radiation Analysis" . "viewStudyMesh" of "Ladybug_View Analysis" . and so
on..

transparency [Optional]

An optional number between 0 and 1 to set the opacity/transparency of the image. Note
that Rhino may not display this transparency but rendering programs like V-Ray will be
able to render it.

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:/USERNAME/AppData/Roaming/Ladybug/LB_TextureMesh.

name [Optional]

The file name that you would like the image to be saved as. If no input is provided it will
be created automatically.

layerName [Default]

An optional text string to set the name of the layer onto which the image-mapped mesh
will be baked.

softBake [Optional]

Set to "True" to run the component and bake the mesh with image material. However, if
this component runs again, the old geometry in the Rhino scene will be overwritten by
new geometry, allowing you to make things like rendered animations.

bakeIt [Required]

Set to "True" to run the component, generate texture images, and bake the mesh into
the scene with the image as a material.

Outputs
readMe!

...

imagePath

362
Texture_Maker

Use this image as texture for the new mesh. Connect imagePath to "DB" input of
"Human Create/Modify material" and its output to "Human Create/Modify Layers" to
apply material to a layer.

alphaPath

Script variable Texture Maker

mesh

A new mesh that is structured to correctly accept the image map. This has been baked
into the scene for you.

Check Hydra Example Files for Texture Maker

363
North

North - [source code]

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
represents the degrees off from the y-axis to make North. The default North direction is
set to the Y-axis (0 degrees).

364
North

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

365
True_North

True North - [source code]

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 ([email protected]), 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 -

366
True_North

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
set to the Y-axis (0 degrees).

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 (°).

367
True_North

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

368
False_Start_Toggle

False Start Toggle - [source code]

Just like a normal Boolean Toggle, except it always reverts to "False" on file open.

Inputs
Check Hydra Example Files for False Start Toggle

369
Activities_Met_List

Activities Met List - [source code]

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

370
BTU2Wh

BTU2Wh - [source code]

Use this component to convert energy values in BTU to Wh or kBTU to kWh. -

Inputs
BTU [Required]

An energy value or list of energy values in BTU or kBTU.

Outputs

371
BTU2Wh

Wh

The input enervy values converted to Wh or kWh (depeding on input).

Check Hydra Example Files for BTU2Wh

372
BTUft2Whm

BTUft2Whm - [source code]

Use this component to convert energy values in BTU/ft2 to Wh/m2 (or kBTU/ft2 to kWh/m2).
-

Inputs
BTU_ft2 [Required]

An energy value or list of energy values in BTU/ft2, kBTU/ft2.

Outputs

373
BTUft2Whm

Wh_m2

The input energy flux values converted to Wh/m2 or kWh/m2 (depeding on input).

Check Hydra Example Files for BTUft2Whm

374
Beaufort_Ranges

Beaufort Ranges - [source code]

This component outputs conditional statements as per beaufort scale that you can plug in
conditionaStatement_ input of wind rose component. These conditionals statements
basically represent a range of wind velocity. For example, “Calm” relates to winds with
velocities in the range of 0 m/s to 0.2 m/s. On plugging this component to wind rose, a
summary would be added to the text displayed at the bottom of this wind rose. For those
interested in learning more about Beaufort scale, following is a good resource
https://github.com/devngc/References/tree/master/Beaufort%20Scale
https://en.wikipedia.org/wiki/Beaufort_scale

Inputs

375
Beaufort_Ranges

Check Hydra Example Files for Beaufort Ranges

376
Cfm2M3s

Cfm2M3s - [source code]

Use this component to convert volume flow rate from U.S. cubic feet per minute (cfm) to S.I.
cubic meters per second (m3/s). -

Inputs
cfm [Required]

A value or list of values in cubic feet per minute (cfm).

Outputs

377
Cfm2M3s

m3_s

Input volume flow rate converted to cubic meters per second (m3/s).

Check Hydra Example Files for Cfm2M3s

378
CombineSolarEnvelopes

CombineSolarEnvelopes - [source code]

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.

379
CombineSolarEnvelopes

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

380
Comfort_Mannequin

Comfort Mannequin - [source code]

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

381
Comfort_Mannequin

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.

legendPar [Optional]

Optional legend parameters from the Ladybug Legend Parameters component.

bakeIt [Optional]

An integer that tells the component if/how to bake the bojects in the Rhino scene. The
default is set to 0. Choose from the following options: 0 (or False) - No geometry will be
baked into the Rhino scene (this is the default). 1 (or True) - The geometry will be baked
into the Rhino scene as a colored hatch and Rhino text objects, which facilitates easy
export to PDF or vector-editing programs. 2 - The geometry will be baked into the Rhino
scene as colored meshes, which is useful for recording the results of paramteric runs as
light Rhino geometry.

Outputs

382
Comfort_Mannequin

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 legend base point, which can be used to move the legend in relation to the chart
with the grasshopper "move" component.

Check Hydra Example Files for Comfort Mannequin

383
Construct_Time

Construct Time - [source code]

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]

384
Construct_Time

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

385
Create_Legend

Create Legend - [source code]

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]

386
Create_Legend

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.

legendPar [Optional]

Optional legend parameters from the Ladybug Legend Parameters component.

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.

387
Create_Legend

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

388
L2G

L2G - [source code]

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

389
L2G

Input volume converted to U.S. Gallons.

Check Hydra Example Files for L2G

390
M3s2Cfm

M3s2Cfm - [source code]

Use this component to convert volume flow rate from S.I. cubic meters per second (m3/s) to
U.S. cubic feet per minute (cfm). -

Inputs
m3_s [Required]

A value or list of values in cubic meters per second (m3/s).

Outputs

391
M3s2Cfm

cfm

Input volume flow rate converted to cubic feet per minute (cfm).

Check Hydra Example Files for M3s2Cfm

392
MRT_Calculator

MRT Calculator - [source code]

Use this component calculate Mean Radiant Temperature (MRT) given a set of temperatures
and corresponding view factors. This component will check to be sure view factors add to 1
and will use the following formula: MRT = (V1T1^4 + V2T2^4 + ...) ^ (1/4) Where V
corresponds to a view factor and T corresponds to a temperature. -

Inputs
temperatures [Required]

A list of radiant temperatures in Celcius that correspond to view factors below.

393
MRT_Calculator

viewFactors [Required]

A list of viewFactors that correspond to the temperatures above. These should sum to 1.

Outputs
MRT

The Mean Radiant Temperature that results from the input temperatures and view
factors.

Check Hydra Example Files for MRT Calculator

394
Orient_to_Camera

Orient to Camera - [source code]

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]

395
Orient_to_Camera

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

396
Orientation_Study_Parameters

Orientation Study Parameters - [source

code]

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

397
Orientation_Study_Parameters

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

basePoint [Optional]

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

398
Passive_Strategy_List

Passive Strategy List - [source code]

Provides a list of passive thermal strategies to be plugged into the Ladybug_Psychrometric

Chart

Inputs
Check Hydra Example Files for Passive Strategy List

399
Passive_Strategy_Parameters

Passive Strategy Parameters - [source code]

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

400
Passive_Strategy_Parameters

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 12 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 3 C.

maxComfortableAirSpeed [Optional]

An optional number in m/s that represents the maximum winds speed tolerable before
becomes annoying to occupants. This is used to shape the "Occupant Use of Fans"

401
Passive_Strategy_Parameters

Polygon and the default is set ot 1 m/s, which is right below the speed at which papers
on a desk might move in the wind.

bldgBalancePt [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.

solarHeatCapacity [Optional]

A number representing the amount of solar flux (W/m2) that is needed to raise the
temperature of the therorical building 1 degree Celcius. The lower this number, the more
efficiently the space is able to absorb passive solar heat. The default is set to 50 W/m2,
which assumes a relatively small passively solar heated zone with full glazing on a the
facade.

timeConstant [Optional]

A number that represents the amount of time in hours that a therortical building can
passively maintain its temperature. This is used to determine how many hours a space
can maintain a cool temperature after night flushing for the "Thermal Mass + Night Vent"
polygon. It is also used to determine how many hours a space can store solar radiation
for the "Passive Solar Heating" polygon. The default is set to 8 hours, which assumes a
relatively well-isulated building with a thermal mass typical of most contemporary
buildings.

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

402
Separate_By_Normal

Separate By Normal - [source code]

Select surfaces based on orientation. -

Inputs
geometry [Required]

Geometry for which facades will be selected. Geometry must be either a Brep, a Mesh
or a list of Breps or Meshes.

maxUpDecAngle [Default]

403
Separate_By_Normal

Maximum normal declination angle from ZAxis that should be still considerd up

maxDownDecAngle [Default]

Maximum normal declination angle from ZAxis that should be still considerd down

orientation [Default]

A number between 0 and 8 for desired orientation. 0 = North, 1 = NE, 2 = East, ... 7 =
NW, 8 = Roof. Default is South.

plusDeg [Default]

Angle in degrees for deviation from orientation. Default = 23. For selecting all vertical
orientations give 359 for this input and 0 for the _minusDeg (or viceversa)

minusDeg [Default]

Angle in degrees for deviation from orientation. Default = 23. For selecting all vertical
orientations give 359 for this input and 0 for the _plusDeg (or viceversa)

Outputs
readMe!

...

selFaces

Selected faces/surfaces

Check Hydra Example Files for Separate By Normal

404
Set_the_View

Set the View - [source code]

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.

405
Set_the_View

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

406
Shading_Parameters_List

Shading Parameters List - [source code]

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.

407
Shading_Parameters_List

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

408
Wh2BTU

Wh2BTU - [source code]

Use this component to convert energy values in Wh to BTU (or kWh to kBTU). -

Inputs
Wh [Required]

An energy value or list of energy values in Wh or kWh.

Outputs

409
Wh2BTU

BTU

The input enervy values converted to BTU or kBTU (depeding on input).

Check Hydra Example Files for Wh2BTU

410
Whm2BTUft

Whm2BTUft - [source code]

Use this component to convert energy values in Wh/m2 to BTU/ft2 (or kWh/m2 to kBTU/ft2).
-

Inputs
Wh_m2 [Required]

An energy value or list of energy values in Wh/m2, kWh/m2.

Outputs

411
Whm2BTUft

BTU_ft2

The input energy flux values converted to BTU/ft2, or kBTU/ft2 (depeding on input).

Check Hydra Example Files for Whm2BTUft

412
fly

fly - [source code]

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]

413
fly

Script Variable _inputSliders

fly [Required]

Script Variable _fly

Outputs
Vviiiiiiiiiizzz

Output parameter Vviiiiiiiiiizzz

Check Hydra Example Files for fly

414
lux2ft-cd

lux2ft-cd - [source code]

Use this component to convert illuminance from lux to foot-candles. -

Inputs
lux [Required]

An illuminance in lux.

Outputs

415
lux2ft-cd

ftcd

The input illuminance converted to foot-candles.

Check Hydra Example Files for lux2ft-cd

416
ms2mph

ms2mph - [source code]

Convert from m/s to mile/h -

Inputs
ms []

Input wind speed in meters per second

Outputs

417
ms2mph

mph

Output wind speed in miles per hour

Check Hydra Example Files for ms2mph

418
rIP2rSI

rIP2rSI - [source code]

Use this component to convert R-Values in IP (h·ft2·°F/BTU) to R-Values in SI (K·m2/W) to

plug into any of the Honeybee material components. -

Inputs
R_IP [Required]

A R-Value in IP (h·ft2·°F/BTU).

Outputs

419
rIP2rSI

R_SI

The R-Value in SI (K·m2/W).

Check Hydra Example Files for rIP2rSI

420
uIP2uSI

uIP2uSI - [source code]

Use this component to convert U-Values in IP (BTU/h·ft2·°F) to U-Values in SI (W/K·m2) to

plug into any of the Honeybee material components. -

Inputs
U_IP [Required]

A U-Value in IP (BTU/h·ft2·°F).

Outputs

421
uIP2uSI

U_SI

The U-Value in SI (W/K·m2).

Check Hydra Example Files for uIP2uSI

422
uSI2uIP

uSI2uIP - [source code]

Use this component to convert U-Values in SI (W/K·m2) to U-Values in IP (BTU/h·ft2·°F). -

Inputs
U_SI [Required]

A U-Value in SI (W/K·m2).

Outputs

423
uSI2uIP

U_IP

The U-Value in IP (BTU/h·ft2·°F).

Check Hydra Example Files for uSI2uIP

424
6 | Developers

Component list:

Export_Ladybug
Update_Ladybug

425
Export_Ladybug

Export Ladybug - [source code]

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]

426
Export_Ladybug

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

427
Update_Ladybug

Update Ladybug - [source code]

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]

428
Update_Ladybug

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.

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

429
7 | WIP

Component list:

Location_Finder
Search
Countour_Mesh
ENVI-Met_Building_Terrain
ENVI-Met_Display
ENVI-Met_Find_Output_Folder
ENVI-Met_Grid
ENVI-Met_Manage_Workspace
ENVI-Met_Read_Library
ENVI-Met_Results_Reader
ENVI-Met_Soil_Plant_Source
ENVI-Met_Spaces
Kmz_Generator
Pedestrian_Wind_Comfort
Shading_Mask_II
Shadow_Study
Terrain_Generator

430
Location_Finder

Location Finder - [source code]

This component uses Google Maps API to generate locations. - This component requires an
internet connection and a secure connection (HTTPS), it runs for free up to 2,500 requests
per day. Once you go over this limit the component doesn't work. For informations about the
rules of use of Google Maps API, take a look at this link:
https://developers.google.com/maps/pricing-and-plans/#details - Special thanks goes to
Google Maps. -

Inputs
address [Required]

431
Location_Finder

Write a location address. For example, - 'Colosseum, Rome' OR . 'Colosseum, Piazza

del Colosseo, 1, 00184 Roma, Italy'

APIKey [Required]

Your Google PLACES API KEY. Generate one from:

https://developers.google.com/maps/documentation/geocoding/get-api-key

Outputs
readMe!

...

location

A list of text summarizing the location data in the weather file (use this to construct the
sun path).

Check Hydra Example Files for Location Finder

432
Search

Search - [source code]

Use this to look for the components in the Ladybug suite of tools that are most relevant to
your query. -

Inputs
keyword [Required]

A word. This only accepts text inputs. Example is ("drybulb Temperature" or "tunnel")
without quotation marks.

433
Search

occurrences [Default]

An integer. This number determines the search resolution. The default value is set to 3.
Meaning, all the components in which the keyword appears at least 3 times, will be
served as results. You may raise or reduce this number as per your convenience. This
number can not be less than 1.

open [Optional]

A boolean. If boolean of True value is provided, primer pages for the components that
appear in the result will be opened in your browser. PLEASE BE MINDFUL of the
number of components in the result. If the list of components in the result is long,
opening up the primer pages for all of them at once may free your browser. If the
number of components in result is large, you are advised to raise the number to
occurrences input before connecting a boolean value of True to this input.

Outputs
log

Run time messages

result

The list of components across all Lasybug Tools plugins in which the keyword appears
at least the number of times set in occurrences input.

Check Hydra Example Files for Search

434
Countour_Mesh

Countour Mesh - [source code]

Use this component to create contoured visualizations of any analysis mesh and
corresponding numerical dataset in Ladybug + Honeybee. Note that this component
currently only works for planar meshes. -

Inputs
analysisResult [Required]

A numerical data set whose length corresponds to the number of faces in the
_inputMesh. This data will be used to generate contours from the mesh.

435
Countour_Mesh

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.

contourType [Default]

An integer to set the type of contour visualization. The default is set to 0 for colored
regions. Choose from the following options: 0 - Colored Regions + Labeled Lines 1 -
Colored Regions 2 - Labeled Lines 3 - Colored Lines

heightDomain [Optional]

Optional height domain to create a 3D mesh result. Use Construct Domain component
to create a domain

legendPar [Optional]

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

labelSize [Default]

A number to set the size of the text labels for the contours when contourType 0 or 2 is
selected. The default is auto-calculated based on the size of the mesh.

bakeIt [Optional]

An integer that tells the component if/how to bake the bojects in the Rhino scene. The
default is set to 0. Choose from the following options: 0 (or False) - No geometry will be
baked into the Rhino scene (this is the default). 1 (or True) - The geometry will be baked
into the Rhino scene as a colored hatch and Rhino text objects, which facilitates easy
export to PDF or vector-editing programs. 2 - The geometry will be baked into the Rhino
scene as colored meshes, which is useful for recording the results of paramteric runs as

436
Countour_Mesh

light Rhino geometry.

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!

...

contourMesh

A list of colored meshes that is organized with each contour region as its own color.

underlayMesh

A mesh that is colored face-by-face (like a typical Ladybug mesh), which is plaed under
the contour mesh to make the visualization read when the Rhino intersection fails to
produce a complete contourMesh.

contourLines

Curves that show values of constant value along the results.

contourColors

Connect these to a native Grasshopper Preview componen along with the contourLines
to get a colored line visualization.

contourLabels

A list of text meshes that show the value along each contour line.

legend

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.

437
Countour_Mesh

legendColors

A list of colors that correspond to each step in the legend.

intPlanes

The planes that were used to intersect the mesh to genrate the contours. Set
heightDomain_ to a non-zer number to visualize.

Check Hydra Example Files for Countour Mesh

438
ENVI-Met_Building_Terrain

ENVI-Met Building Terrain - [source code]

Use this component to generate inputs for "LB ENVI-Met Spaces". - Sometimes some
buildings are not generated when you connect terrain input. Try to move buildings or move
the terrain to solve this issue. -

Inputs
buildings [Required]

Geometry that represent ENVI-Met buildings. - Geometry must be closed Brep/Breps. -

Try to connect "threeDeeShapes" output of "Gismo" (a plugin for GIS environmental

439
ENVI-Met_Building_Terrain

analysis).

terrain [Optional]

Optional geometry that represent ENVI-Met terrain. Geometry must be the output of "LB
Terrain Generator".

defaultMaterialsld [Default]

Default wall/roof property. Use this input to set default building materials. - If no input is
connected this input will be concrete slab/roofing tile (00, R1).

wallMaterialsId [Optional]

Use this input to change wall materials.

roofMaterialsId [Optional]

Use this input to change roof materials.

runIt [Required]

Set to "True" to run the component and generate envimetBuildings and envimetTerrain.

Outputs
readMe!

...

envimetBuildings

Connect this output to "ENVI-Met Spaces" in order to add buildings to ENVI-Met model.

envimetTerrain

Connect this output to "ENVI-Met Spaces" in order to add a terrain to ENVI-Met model.

Check Hydra Example Files for ENVI-Met Building Terrain

440
ENVI-Met_Display

ENVI-Met Display - [source code]

Use this component to visualize ENVI-Met v4.0 3D geometry models. -

Inputs
basePoint [Optional]

Input a point here to move ENVI-Met grid. If no input is provided it will be origin point.

INXfileAddress [Required]

Output which comes from "ENVI-Met Spaces" or a complete file path of a INX file on

441
ENVI-Met_Display

your machine.

Outputs
readMe!

...

buildings

ENVI-Met buildings preview.

terrain

ENVI-Met terrain preview.

Check Hydra Example Files for ENVI-Met Display

442
ENVI-Met_Find_Output_Folder

ENVI-Met Find Output Folder - [source code]

This component let you select output folders from Workspace folder. -

Inputs
folder [Required]

Workspace folder where there are output folders.

runIt [Required]

Set to "True" to run the component.

443
ENVI-Met_Find_Output_Folder

Outputs
outputFolder

ENVI-Met output folder path.

Check Hydra Example Files for ENVI-Met Find Output Folder

444
ENVI-Met_Grid

ENVI-Met Grid - [source code]

Use this component to visualize ENVI-Met v4.0 data. Connect "resultFileAddress" which
comes from ENVI-Met reader. - Component mainly based on:
https://www.researchgate.net/publication/281031049_Outdoor_Comfort_the_ENVI-
BUG_tool_to_evaluate_PMV_values_point_by_point -

Inputs
basePoint [Optional]

Input a point here to move ENVI-Met grid. If no input is provided it will be origin point.

445
ENVI-Met_Grid

resultFileAddress [Required]

Output comes from "ENVI-Met Reader".

selXY [Default]

Connect an integer to generate a XY section. Plug a panel to "readMe!" for more info. -
Default value is 0.

selXZ [Optional]

Connect an integer to generate a XZ section. Plug a panel to "readMe!" for more info.

selYZ [Optional]

Connect an integer to generate a YZ section. Plug a panel to "readMe!" for more info.

legendPar [Optional]

Optional legend parameters from the Ladybug Legend Parameters component.

runIt [Required]

Set to "True" to run the component and perform ENVI-Met data visualization.

Outputs
readMe!

...

analysisMesh

Analysis grid of ENVI-Met (XY plane, ZX plane and ZY plane).

analysisResult

Values corrisponding to each analysis Grid.

testPoints

Test points on grids.

legend

Legend geometry of ENVI-Met Grid.

titleLabel

446
ENVI-Met_Grid

Title geometry with information about project name, location, and date.

Check Hydra Example Files for ENVI-Met Grid

447
ENVI-Met_Manage_Workspace

ENVI-Met Manage Workspace - [source code]

Use this component to create a Workspace folder. - Connect "folder" output to ENVI-Met
Spaces. -

Inputs
workspaceFolder [Required]

Main folder where you have to save an Envimet project.

projectName [Default]

448
ENVI-Met_Manage_Workspace

Name of Envimet project folder where you have to save: 1) EnviMet geometry file (.INX)
2) Configuration file (.SIM)

ENVImetInstallFolder [Optional]

Optional folder path for ENVImet4 installation folder.

Outputs
readMe!

...

folder

Envimet project folder. Connect it to "_folder" input of ENVI-Met Spaces

Check Hydra Example Files for ENVI-Met Manage Workspace

449
ENVI-Met_Read_Library

ENVI-Met Read Library - [source code]

This component let you select materials from ENVI-Met library. -

Inputs
dataType [Required]

Connect an integer from 0 to 6. - 0 = soil 1 = profile 2 = material 3 = wall 4 = source 5 =

plant 6 = plant3D - Default value is 0.

keyword [Default]

450
ENVI-Met_Read_Library

Connect a keyword to filter data. E.g. 'asphalt' (_dataType = 0)

Outputs
readMe!

...

soilId

ENVI-Met soil ID.

soilData

0 = Id 1 = Description 2 = Versiegelung 3 = Water Contentat Saturation 4 = Water

Content At Field Cap 5 = WaterContentWiltingPoint6 = Matrix Potential 7 = Hidraulic
Conductivity 8 = Volumetric HeatCapacity 9 = Clapp Constant 10 = Heat Conductivity 11
= Group 12 = Color

Check Hydra Example Files for ENVI-Met Read Library

451
ENVI-Met_Results_Reader

ENVI-Met Results Reader - [source code]

This component generate readable output files of ENVI-Met v4.0 for Ladybug. - Component
mainly based on:
https://www.researchgate.net/publication/281031049_Outdoor_Comfort_the_ENVI-
BUG_tool_to_evaluate_PMV_values_point_by_point - Special thanks goes to MIT. -

Inputs
outputFolder [Required]

ENVI-Met output folder path. E.g. 'C:...\NewSimulation_output'.

452
ENVI-Met_Results_Reader

studyFolder [Default]

ENVI-Met sub-folder, connect a number from 0 to 4. Default value is 0. - 0 =

atmosphere 1 = pollutants 2 = radiation 3 = soil 4 = surface

selectItem [Default]

Connect an integer number which represent the index of the file you want to read. Plug
a panel to 'outputFiles' to see them. - Default value is 0, the first file in ENVI-Met model
folder.

variable [Default]

Select one variable. - 1 = Flow u (m/s) 2 = Flow v (m/s) 3 = Flow w (m/s) 4 = Wind
Speed (m/s) 5 = Wind Speed Change () 6 = Wind Direction (deg) 7 = Pressure
Perturbation (Diff) 8 = Air Temperature (C) 9 = Air Temperature Delta (K) 10 = Air
Temperature Change (K/h) 11 = Spec. Humidity (g/kg) 12 = Relative Humidity () 13 =
TKE (m/m) 14 = Dissipation (m/m) 15 = Vertical Exchange Coef. Impuls (m/s) 16 =
Horizontal Exchange Coef. Impuls (m/s) 17 = Vegetation LAD (m/m) 18 = Direct Sw
Radiation (W/m) 19 = Diffuse Sw Radiation (W/m) 20 = Reflected Sw Radiation (W/m)
21 = Temperature Flux (Km/s) 22 = Vapour Flux (g/kgm/s) 23 = Water on Leafes (g/m)
24 = Leaf Temperature (C) 25 = Local Mixing Length (m) 26 = Mean Radiant Temp. (C)
27 = TKE normalised 1D ( ) 28 = Dissipation normalised 1D ( ) 29 = Km normalised 1D (
) 30 = TKE Mechanical Turbulence Prod. ( ) 31 = Stomata Resistance (s/m) 32 = CO2
(mg/m3) 33 = CO2 (ppm) 34 = Plant CO2 Flux (mg/kgm/s) 35 = Div Rlw Temp change
(K/h)

runIt [Required]

Set to "True" to run the component and perform ENVI-Met data visualization.

Outputs
readMe!

...

outputFiles

File list that you can read.

resultFileAddress

Connect this output to "ENVI-Met visualizer".

453
ENVI-Met_Results_Reader

Check Hydra Example Files for ENVI-Met Results Reader

454
ENVI-Met_Soil_Plant_Source

ENVI-Met Soil Plant Source - [source code]

Use this component to generate ENVI-Met inputs for "LB ENVI-Met Spaces". - Some
'plant3Did_' could not work properly. -

Inputs
basePoint [Optional]

Input a point here to move ENVI-Met grid. If no input is provided it will be origin point.

soil [Default]

455
ENVI-Met_Soil_Plant_Source

Geometry that represent ENVI-Met soil. Geometry must be a Surface or Brep on xy

plane.

plant2D [Default]

Geometry that represent ENVI-Met plant 2d. Geometry must be a Surface or Brep on xy
plane.

plant3D [Default]

Geometry that represent ENVI-Met plant 3d. Geometry must be a Surface or Brep on xy
plane.

source [Default]

Geometry that represent ENVI-Met plant 3d. Geometry must be a Surface or Brep on xy
plane.

soilId [Default]

ENVI-Met profile id. You can use "id outputs" which comes from "LB ENVI-Met Read
Library". - E.g. L0

plantId [Default]

ENVI-Met plant id. You can use "id outputs" which comes from "LB ENVI-Met Read
Library". - E.g. XX

plant3Did [Default]

ENVI-Met plant3D id. You can use "id outputs" which comes from "LB ENVI-Met Read
Library". - E.g. PI,.Pinus Pinea

sourceId [Default]

ENVI-Met source id. You can use "id outputs" which comes from "LB ENVI-Met Read
Library". - E.g. FT

Outputs
readMe!

...

envimetPlants

456
ENVI-Met_Soil_Plant_Source

Connect this output to "ENVI-Met Spaces" in order to add plants to ENVI-Met model.

envimetSoils

Connect this output to "ENVI-Met Spaces" in order to add soils to ENVI-Met model.

envimetSources

Connect this output to "ENVI-Met Spaces" in order to add sources to ENVI-Met model.

Check Hydra Example Files for ENVI-Met Soil Plant Source

457
ENVI-Met_Spaces

ENVI-Met Spaces - [source code]

Use this component to generate ENVI-Met v4.0 3D geometry models. - Analyze parametric
models with ENVI-Met! - Save the model in the ENVI_MET Workspace, set the simulation
file with ENVI_MET ConfigWizard and run the simulation. N.B. It can write files with
equidistant grid only. If you want to visualize INX file with ENVI_MET SPACES you need to
use "Open 3D view". -

Inputs
location [Required]

458
ENVI-Met_Spaces

The output from the importEPW or constructLocation component. This is essentially a

list of text summarizing a location on the earth.

north [Default]

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

basePoint [Optional]

Input a point here to move ENVI-Met grid. If no input is provided it will be origin point.

numX [Default]

Number of grid cells in base plane x direction. Default value is 20.

numY [Default]

Number of grid cells in base plane y direction. Default value is 20.

numZ [Default]

Number of grid cells in base plane z direction. Default value is 20.

dimX [Default]

Size of grid cell in meter. Default value is 3.0.

dimY [Default]

Size of grid cell in meter. Default value is 3.0.

dimZ [Default]

Size of grid cell in meter. Default value is 3.0.

baseSoilmaterial [Optional]

Connect a profileId that you want to use as base material of soil. If no id is provided it
will be 'LO'.

numNestingGrid [Optional]

Connect an integer to set nesting grid around main area. If no input is connected this
will be 3.

nestingGridSoil [Optional]

459
ENVI-Met_Spaces

Connect two envimet ID soils to set soil profile for nesting grids. Use "LB ENVI-Met
Read Library" for that. - If no input is connected this input will be ('LO', 'LO').

envimetBuildings [Required]

Output which comes from "LB ENVI-Met Building Terrain".

envimetTerrain [Optional]

Output which comes from "LB ENVI-Met Building Terrain".

envimetPlants [Optional]

Output which comes from "LB ENVI-Met Soil Plant Source".

envimetSoils [Optional]

Output which comes from "LB ENVI-Met Soil Plant Source".

envimetSources [Optional]

Output which comes from "LB ENVI-Met Soil Plant Source".

folder [Required]

The folder into which you would like to write the envimet model. This should be a
complete file path to the folder.

fileName [Optional]

The file name that you would like the envimet model to be saved as. Default name is
"LBenvimet".

runIt [Required]

Set to "True" to run the component and generate the envimet model.

Outputs
readMe!

...

points

Preview of 3D grid of points.

460
ENVI-Met_Spaces

INXfileAddress

The file path of the inx result file that has been generated on your machine.

Check Hydra Example Files for ENVI-Met Spaces

461
Kmz_Generator

Kmz Generator - [source code]

Use this component to export geometries into an Google Earth file. It requires Google Earth.
You can download it at this link: https://www.google.it/earth/download/ge/agree.html Once
you open kmz file you can continue to update it. This is useful when you change geometries
or you want to compare different scenarios. . Updating: Just setting again to "True"
_writeKmz, after that right click and select "update" on Google Earth. - Special thanks goes
to Google and the authors of gHowl. -

Inputs
geometry [Required]

462
Kmz_Generator

A list of Breps, Meshes and Surfaces to export.

basePoint [Default]

Input a point here to georeference the model. Default value is origin point.

location [Required]

It accepts two type of inputs. a) latitude, longitude and elevation that represent WSG84
coordinates of the base point. You can achieve these type of coordinates from Google
Maps or similar. e.g. 40.821796, 14.426439, 990 - b) location, you can obtain this type
of input from "Ladybug_Construct Location", "Ladybug_Location Finder",
"Ladybug_Import epw", "Ladybug_Import Location".

terrain [Required]

Connect the terrain output of "Ladybug_Terrain Generator" to move the geometries in

the right altitude automatically.

folder [Default]

The folder into which you would like to write the kmz file. This should be a complete file
path to the folder. If no folder is provided, the images will be written to Ladybug default
folder.

name [Optional]

Name of kmz file.

material [Optional]

Connect Create Material component of Grasshopper, it is part of Display tab. If not

supplied it will be default material.

bakeIt [Required]

Connect a Grasshopper button. Set to "True" to bake the geometries for Google Earth.

writeKmz [Required]

Connect a Boolean Toggle. After the baking, set it to "True" to export from Rhino Model
to KMZ format.

Outputs
readMe!

463
Kmz_Generator

...

kmzPath

Complete path of kmz file.

pointOnTerrain

basePoint projected on terrain.

geometry

Geometries on the ground.

Check Hydra Example Files for Kmz Generator

464
Pedestrian_Wind_Comfort

Pedestrian Wind Comfort - [source code]

Use this component to analyse pedestrian wind comfort and safety for the present and
potential (newly built) urban environments. Construction of a new building changes the wind
microclimate in its vicinity. These changes can result in either decreased or increased wind
speeds around the building, which may be uncomfortable or even dangerous. - Based on
Lawson’s Pedestrian Comfort Criteria (1990)
https://www.dropbox.com/s/t9pxhr45vwg2xd2/Wind_Microclimate.pdf?dl=0 -

Inputs
epwFile [Required]

465
Pedestrian_Wind_Comfort

Input an .epw file path by using the "File Path" parameter, or Ladybug's "Open EPW
And STAT Weather Files" component.

windFactor [Required]

Division of cfd simulation's wind speed values, and annual average wind speed value
from the weather data (.epw file) at 10 meters height. They are used to normalize
against the weather data (.epw file), given that a CFD simulation with the exact .epw file
wind speed and direction has not been performed. - _windFactor data should be
supplied into different branches corresponding to different directions for which the cfd
simulation has been performed. For example: the first branch holds windFactors for all
analysis points for wind direction 0. Second branch would hold windFactors for all
analysis points for wind direction 20. Third branch would hold windFactors for all
analysis points for wind direction 40 ... and so on.

analysisGeometry [Required]

Input a mesh for whose face centroids the cfd simulation has been performed. - The
number of mesh face centroids needs to be equal to the number of values in each of the
_windFactor branches.

pedestrianType [Optional]

Choose the pedestrian type used at the analysis location: 0 = typical pedestrian (20
m/s) 1 = sensitive pedestrian (15 m/s): elderly people, cyclists, children. - This input is
used to analyse pedestrian safety. - If not supplied, the 0 (typical pedestrian) will be
used by default.

northCfd [Optional]

Input a vector to be used as a Cfd simulation's 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 Cfd direction will be set to the Y-axis (0 degrees).

north [Optional]

Input a vector to be used as Rhino's 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).

legendPar [Optional]

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

resultGradient [Optional]

466
Pedestrian_Wind_Comfort

Choose whether or not the resulting geometry-values will be created as a gradient-float

or not. - It allows the following two inputs: True - the resulting pedestrianComfortMesh,
pedestrianSafetyMesh will be created as a gradient, and the
pedestrianComfortCategory, pedestrianSafetyCategory will be outputed as float values.
False - the resulting pedestrianComfortMesh, pedestrianSafetyMesh will NOT be
created as a gradient, and the pedestrianComfortCategory, pedestrianSafetyCategory
will be outputed as integer values. - If not supplied, no gradient (integer values) will be
set by default.

analysisPeriod [Optional]

An optional analysis period from the "Analysis Period" component. - This input can be
useful in cases where certain areas show higher pedestrianComfortCategory than
required. For example: when analysis is run for the whole year period, the component
shows that a certain location does not fulfill the comfort criteria for sitting. However if we
perform the analysis for the period from late spring to early autumn (when the sitting is
suppose to happen), the comfort criteria for sitting can be fulfilled. - If not supplied, the
whole year period will be used as an analysis period.

annualHourlyData [Optional]

An optional list of hourly data from Ladybug's "Import epw" component (e.g.
windSpeed), which will be used for "conditionalStatement_".

conditionalStatement [Optional]

This input allows users to calculate the Pedestrian wind comfort component results only
for those annualHourlyData values which fit specific conditions or criteria. To use this
input correctly, hourly data, such as windSpeed or windDirection, must be plugged into
the "annualHourlyData" input. The conditional statement input here should be a valid
condition statement in Python, such as "a>4" or "b<90" (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="" of="" lists="" (in=""
their="" respective="" order):="" "a"="" always="" represents="" 1st="" list,="" "b"=""
2nd="" etc.="" -="" for="" example,="" if="" you="" have="" an="" windspeed=""
connected="" first="" winddirection="" second="" list="" (both="" annualhourlydata_=""
input),="" want="" plot="" data="" time="" period="" when="" is="" larger="" than=""
4m="" s="" southerly,="" written="" "a="">4 and b==180" (without the quotation marks).

bakeIt [Optional]

Set to "True" to bake the pedestrianComfortMesh, pedestrianSafetyMesh, legend,

467
Pedestrian_Wind_Comfort

legend2 into the Rhino scene. - If not supplied default value "False" will be used.

runIt [Required]

...

Outputs
readMe!

...

pedestrianComfortCategory

Pedestrian wind comfort categories for each face centroid of the analysisGeometry
mesh. The categories depend on the threshold wind speed for particular point: the wind
speed that for 95% of the chosen analysis period is below a certain value. With values
being the following: - 0) < 4 m/s sitting (outdoor cafes, patios, terraces, benches,
gardens, parks, fountains, monuments...) 1) 4-6 m/s standing (building entrances or
exits, bus stops, children’s play areas...) 2) 6-8 m/s leisurely walking (general areas of
walking, strolling and sightseeing, window shopping, public/private sidewalks, pathways,
public spaces...) 3) 8-10 m/s business walking (walking from one place to another
quickly, or where individuals pass rapidly through local areas around buildings,
public/private vehicular drop-off zones, roads and car parks, cyclists pathways...) 4) >
10 m/s uncomfortable (uncomfortable for all pedestrian activities) - If resultGradient
input is set to True, then upper mentioned category values will be calculated as floats,
instead of integers.

pedestrianSafetyCategory

Pedestrian wind safety categories for each face centroid of the analysisGeometry mesh.
- Infrequent strong wind can cause some pedestrians to have difficulties with walking, to
stumble or fall. The location is safe if these infrequent strong winds appear for only
0.01% of the whole year period, and do not exceed the: - 20 m/s for typical pedestrians
(pedestrianType = 0) 15 m/s for sensitive pedestrians (pedestrianType = 1): elderly
people, cyclists, children - So the pedestrian safety categories are the following: - 0) not
safe (upper mentioned wind speeds and its occurrences are exceeded) 1) safe (upper
mentioned winds speeds and its occurrences are NOT exceeded) - If resultGradient
input is set to True, then the mentioned category values will be calculated as floats,
instead of integers.

thresholdWindSpeed

Wind speed that for 95% of the chosen analysis period is below the outputted value, for

468
Pedestrian_Wind_Comfort

each _analysisGeometry face centroid. It is used to determine the

pedestrianComfortCategory output. - In meters/second.

strongestLocationWindSpeed

The strongest wind speed for the chosen analysis period, for each analysisGeometry
face centroid. It is used along with pedestrianType input to determine the
pedestrianSafetyCategory output. - In meters/second.

pedestrianComfortMesh

Colored _analysisGeometry mesh in accordance with disposition of the pedestrian wind

comfort categories. For explanation of each of the categories, check the upper
"pedestrianComfortCategory" output.

pedestrianSafetyMesh

Colored _analysisGeometry mesh. Coloring performed on the basis of whether the

pedestrian safety criteria for the chosen location is fulfilled or not. For explanation of
each of the categories, check the upper "pedestrianSafetyCategory" output. - Green
colored areas are locations where the pedestrian safety criteria has been fulfilled. Red
colored areas are locations where the pedestrian safety criteria has NOT been fulfilled.

legend

Legend for the pedestrianComfortMesh and its title.

legend2

Legend for the pedestrianSafetyMesh and its title. - Red colored areas are locations
where the pedestrian safety criteria has NOT been fulfilled. Green colored areas are
locations where the pedestrian safety criteria has been fulfilled.

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 point in the Rhino scene.

legendBasePt2

Legend2 base point, which can be used to move the "legend2" geometry with
grasshopper's "Move" component. - Connect this output to a Grasshopper's "Point"
parameter in order to preview the point in the Rhino scene.

Check Hydra Example Files for Pedestrian Wind Comfort

469
Pedestrian_Wind_Comfort

470
Shading_Mask_II

Shading Mask_II - [source code]

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]

471
Shading_Mask_II

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. You are also advised to provide surfaces
instead of solid objects. Providing surfces will make the calculation faster and accurate.
So if you are using this component to check the percent of sky visible from a courtyard,
please only provide surfaces immediate to the couryard and the not the whole building
as a brep.

skyDensity [Optional]

An integer, that is greater than or equal to 0. This value is used to generate test points
on skyDome. from which the maskedSky surfaces are derived. The default value is set
to 1. Incresing this value will increase the calculation time. You are adviced to increase
this number only if you are trying to analyze too many shading surfaces.

radius [Optional]

A float, that controls the radius of skyDome.

merge [Optional]

A boolean. Set it to True to merge maskedSky surfaces

Outputs
maskedSrfOnGround

A list of surfaces. These are masked horizontal projections of maskedSky surfaces.

They're useful when the skyDome is viewed from the top.

maskedCrvsOnSky

A list of Curves. These are edge curves for maskedSky surfaces.

maskedSkyDome

A list of surfaces. The portion of sky not blocked by the context geometry

unmaskedSkyDome

A list of surfaces. The portion of sky blocked by the context geometry

472
Shading_Mask_II

percMasked

Percentage of the sky blocked by the context geometry

Check Hydra Example Files for Shading Mask_II

473
Shadow_Study

Shadow Study - [source code]

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. Connect output of
Ladybug_Analysis period component to analysisPeriod on Ladybug_SunPath component.
This will let you use a range of sunvectors. Using these range of sunvectors, you can turn
this shadow study into a shadow range study. 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.

474
Shadow_Study

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

Meshes 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

Meshes 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

475
Terrain_Generator

Terrain Generator - [source code]

This component uses Google Maps API to achieve elevation data and satellite images of the
terrain generated. - This component requires an internet connection and it runs for free up to
2,500 requests per day. Once you go over this limit the component doesn't work. Note that
each surface is a request, for example if you use a surface made by sub-surfaces 6x6, this
will be 36 requests. For informations about the rules of use of Google Maps API, take a look
at this link: https://developers.google.com/maps/pricing-and-plans/#details - Special thanks
goes to Google Maps and the authors of gHowl. -

Inputs

476
Terrain_Generator

location [Required]

It accepts two type of inputs. a) latitude, longitude and elevation that represent WSG84
coordinates of the base point. You can achieve these type of coordinates from Google
Maps or similar. e.g. 40.821796, 14.426439, 990 - b) location, you can obtain this type
of input from "Ladybug_Construct Location", "Ladybug_Location Finder",
"Ladybug_Import epw", "Ladybug_Import Location".

basePoint [Default]

Input a point here to georeference the terrain model.

radius [Default]

A radius to make the terrain 3D model in Rhino model units. The default is set to 100. -
If you provide a big radius, this could require lots of time (also a couple of minutes).

type [Optional]

Select the type of output: 0 = rectangular mesh 1 = rectangular surface - The default
value is 0.

numOfTiles [Default]

Set the number of tiles (e.g. 4, that means 4x4). If no input is connected this will be 3
(tiles: 3x3).

numDivision [Default]

Set the number of points for each tile. If no input is connected this will be 12 (grid:
13x13).

imgResolution [Default]

Connect an integer number which manage the quality of single satellite image. - The
following list shows the approximate level of detail you can expect to see at each
imgResolution level: 1 = World 5 = Landmass/continent 10 = City 15 = Streets 20 =
Buildings - The default value is 18.

mapType [Optional]

Connect an integer number, from 0 to 3, which manages the formats of map. - 0 =

Satellite (default) 1 = Roadmap, specifies a standard roadmap image 2 = Terrain, it
shows terrain and vegetation 3 = Hybrid, it specifies a hybrid of the satellite and
roadmap image

477
Terrain_Generator

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:/USERNAME/AppData/Roaming/Ladybug/IMG_Google.

runIt [Required]

Set to "True" to run the component and generate the 3D terrain model.

Outputs
readMe!

...

pointsGeo

WSG84 coordinates of the grid points (longitude, latitude).

pointsXY

Cartesian coordinates of the grid points (X, Y).

pointsZ

Z values of the grid points. Connect this output to a Z vector to move the pointsXY in the
right positions.

tiles

The area which will be calculated. If you want to visualize Satellite images connect this
output to 'G' input of 'Human Custom Preview Material'.

imagePath

Satellite images from Google Static Maps API. Connect it to 'DB' input of 'Human
Custom Preview Material' to apply textures to the 3d model or to the list of input
surfaces.

terrain

3D terrain model.

origin

The origin (center) point of the "terrain" geometry.

478
Terrain_Generator

elevation

Elevation of the origin_ input.

Check Hydra Example Files for Terrain Generator

479