Ladybug Primer

Ladybug Primer

Table of Contents What is this premier?

0

Components

1

0 | Ladybug Ladybug

1.1

Ladybug Lady bug

1.1.1

Import_epw Impo rt_epw

1.1.2

Open_EPW_And_STAT_Weather_Files

1.1.3

Open _EPW_W _EPW_Wea eather_File ther_File

1.1.4

download_EPW_W ownload_EPW_Weather_File eather_File

1.1.5

Construct_Locatio Cons truct_Locationn

1.1.6

Decompose_ Deco mpose_ Location Location

1.1.7

Import_Location

1.1.8

Import_stat Impo rt_stat

1.1.9

Open _ST _STA AT_File

1.1.10

Create_LB_Header

1.1.11

1 | AnalyzeWeathe AnalyzeWeatherData rData

1.2

Analysis_Period Analysis_P eriod

1.2.1

Average_Data Average_ Data

1.2.2

Branch_Data

1.2.3

Separate_data

1.2.4

CDD_HDD

1.2.5

Wind_Speed_Calculator

1.2.6

Adaptive_Comfort_Calcula Adaptive_C omfort_Calculator tor

1.2.7

Outdoor_Comfort_Calculator

1.2.8

PMV_Comfort_Calculator

1.2.9

Thermal_Comfort_Indices

1.2.10

CDH_HDH

1.2.11

Clothing_Function

1.2.12

Humidity_Ratio_Calculator

1.2.13

2 | VisualizeWeatherData 3D_Chart

1.3 1.3.1

2

Ladybug Primer Adaptive_Comfort_Chart Adaptive_C omfort_Chart

1.3.2

Monthly_Bar_Chart

1.3.3

Psychrometric_Chart

1.3.4

GenCumulativeSkyMtx

1.3.5

selectSkyMtx

1.3.6

Colored_Sky_Visualizer

1.3.7

Outdoor_Solar_Temperature_Adjustor

1.3.8

Radiation_Calla_Lily

1.3.9

Radiation_Rose

1.3.10

Sky_Dome

1.3.11

SunPath

1.3.12

Wind_Boundary_Profile

1.3.13

Wind_Rose

1.3.14

Import_Ground_Temp

1.3.15

3 | Environmenta EnvironmentalAnalysis lAnalysis

1.4

Radiation_Analysis

1.4.1

Sunlight_Hours_Analysis

1.4.2

Bounce_from_Surface

1.4.3

View_Analysis

1.4.4

View_From_Sun

1.4.5

view_Rose

1.4.6

Comfort_Shade_Benefit_Evaluator

1.4.7

ShadingDesigner

1.4.8

SolarEnvelope

1.4.9

SolarFan

1.4.10

DC_to_AC_derate_factor

1.4.11

Photovoltaics_Performance_Metrics

1.4.12

Photovoltaics_Surface

1.4.13

Sunpath_Shading

1.4.14

Tilt_And_Orientation_Factor

1.4.15

Forward_Raytracing

1.4.16

SolarEnvelopeBasic

1.4.17

SolarFanBasic

1.4.18

4 | Extra

1.5 3

Ladybug Primer

Mesh-To-Hatch

1.5.1

North

1.5.2

Recolor_Mesh

1.5.3

True_North

1.5.4

Adaptive_Comfort_Parameters Adaptive_C omfort_Parameters

1.5.5

Body_Characteristics

1.5.6

Gradient_Library

1.5.7

Legend_Parameters

1.5.8

PMV_Comfort_Parameters

1.5.9

Passive_Strategy_List

1.5.10

Real_Time_Radiation_Analysis

1.5.11

Capture_View

1.5.12

Orient_to_Camera

1.5.13

Set_the_View

1.5.14

fly

1.5.15

C2F

1.5.16

DOY_HOY

1.5.17

Day_Month_Hour

1.5.18

F2C

1.5.19

Activities_Met_List Activities_Me t_List

1.5.20

BTU2Wh

1.5.21

CombineSolarEnvelopes

1.5.22

Comfort_Mannequin

1.5.23

Construct_Time

1.5.24

Create_Legend

1.5.25

L2G

1.5.26

Orientation_Study_Parameters

1.5.27

Passive_Strategy_Parameters

1.5.28

Shading_Parameters_List

1.5.29

Wh2BTU

1.5.30

Wh2kWh

1.5.31

kWh2Wh

1.5.32

ms2mph

1.5.33

4

Ladybug Primer rIP2rSI

1.5.34

uIP2uSI

1.5.35

5 | Developers

1.6

Export_Ladybug

1.6.1

Update_Ladybug

1.6.2

6 | WIP

1.7

Bioclimatic_Chart

1.7.1

Shadow_Study

1.7.2

PV_SWH_System_Size

1.7.3

Photovoltaics_Module

1.7.4

Cold_Water_Temperature

1.7.5

Commercial_Public_Apartment_Hot_Water

1.7.6

Residential_Hot_Water

1.7.7

Solar_Water_Heating Solar_W ater_Heating_Performance_Metri _Performance_Metrics cs

1.7.8

Solar_Water_Heating_Surface

1.7.9

Solar_Water_Heating_System

1.7.10

Solar_Water_Heating_System_Detailed

1.7.11

Shading_Mask

1.7.12

Shading_Mask_II

1.7.13

5

Ladybug Primer

ladybug-primer

This primer is generated by script. Feel free to edit the t he pages and send pull requests. Here is the source of this premier .

Ladybug for Grasshopper Ladybug is a free and open source environmental plugin for Grasshopper to help designers create an environmentally-conscious 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 of 2D and 3D designer-friendly interactive graphics graphics to support the decision-making 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.

What is this premier?

6

Ladybug Primer

Useful links Ladybug on Github Ladybug group page on Grasshopper Facebook page Ladybug on Twitter

What is this premier?

7

Ladybug Primer

Component list: Ladybug Import_epw Open_EPW_And_STAT_Weather_Files Open_EPW_Weather_File download_EPW_Weather_File Construct_Location Decompose_Location Import_Location Import_stat Open_STAT_File Create_LB_Header

0 | Ladybug

8

Ladybug Primer

Ladybug

This component carries all of Ladybug's main classes. Other components refer to these classes to run the studies. Therefore, you need to let her fly before running the studies so the classes will be copied to Rhinos shared space. So let her fly! - Ladybug: A Plugin for Environmental Analysis (GPL) started by Mostapha Sadeghipour Roudsari You should have received a copy of the GNU General Public License along with Ladybug; If not, see http://www.gnu.org/licenses/ . @license GPL-3.0+ http://spdx.org/licenses/GPL-3.0+ Source code is available at: https://github.com/mostaphaRoudsari/ladybug -

Inputs

Ladybug

9

Ladybug Primer defaultFolder [Optional]

Optional input for Ladybug default folder. If empty default folder will be set to C:\ladybug or C:\Users\%USERNAME%\AppData\Roaming\Ladybug\

Outputs Vviiiiiiiiiizzz!

Current Ladybug mood!!! Check Hydra Example Files for Ladybug

Ladybug

10

Ladybug Primer

Import epw

Use this component to import lists of weather data into Grasshopper from a standard .epw file. For detailed information about the structure of an epw file, you may want to read the "Weather Converter Program" section in "Auxiliary EnergyPlus Programs" document. All descriptions of importaed data are borrowed from this document. The document is available online at this address: "http://apps1.eere.energy.gov/buildings/energyplus/pdfs/auxiliaryprograms.pdf " -

Inputs epwFile [Required]

Import_epw

11

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

Outputs readMe!

... latitude

The latitude of the weather file location. location

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

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

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

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

"This is the hourly wind speed in m/sec. Values can range from 0 to 40. Missing value is 999." windDirection

"This is the hourly Wind Direction in degrees where the convention is that North=0.0, East=90.0, South=180.0, West=270.0. (If wind is calm for the given hour, the direction equals zero.) Values can range from 0 to 360. Missing value is 999." directNormalRadiation

Import_epw

12

Ladybug Primer "This is the hourly Direct Normal Radiation in Wh/m2. (Amount of solar radiation in Wh/m2 received directly from the solar disk on a surface perpendicular to the sun's rays, during the number of minutes preceding the time indicated.) If the field is missing ( 9999) or invalid (<0), it is set to 0. Counts of such missing values are totaled and presented at the end of the runperiod." diffuseHorizontalRadiation

"This is the hourly Diffuse Horizontal Radiation in Wh/m2. (Amount of solar radiation in Wh/m2 received from the sky (excluding the solar disk) on a horizontal surface during the number of minutes preceding the time indicated.) If the field is missing ( 9999) or invalid (<0), it is set to 0. Counts of such missing values are totaled and presented at the end of the runperiod." globalHorizontalRadiation

"This is the hourly Global Horizontal Radiation in Wh/m2. (Total amount of direct and diffuse solar radiation in Wh/m2 received on a horizontal surface during the number of minutes preceding the time indicated.) It is not currently used in EnergyPlus calculations. It should have a minimum value of 0; missing value for this field is 9999." directNormalIlluminance

"This is the hourly Direct Normal Illuminance in lux. (Average amount of illuminance in hundreds of lux received directly from the solar disk on a surface perpendicular to the sun's rays, during the number of minutes preceding the time indicated.) It is not currently used in EnergyPlus calculations. It should have a minimum value of 0; missing value for this field is 999999 and will be considered missing of >= 999900." diffuseHorizontalIlluminance

"This is the hourly Diffuse Horizontal Illuminance in lux. (Average amount of illuminance in hundreds of lux received from the sky (excluding the solar disk) on a horizontal surface during the number of minutes preceding the time indicated.) It is not currently used in EnergyPlus calculations. It should have a minimum value of 0; missing value for this field is 999999 and will be considered missing of >= 999900." globalHorizontalIlluminance

"This is the hourly Global Horizontal Illuminance in lux. (Average total amount of direct and diffuse illuminance in hundreds of lux received on a horizontal surface during the number of minutes preceding the time indicated.) It is not currently used in EnergyPlus calculations. It should have a minimum value of 0; missing value for this field is 999999 and will be considered missing of >= 999900." Import_epw

13

Ladybug Primer totalSkyCover

"This is the fraction for total sky cover (tenths of coverage). (i.e. 1 is 1/10 covered. 10 is total coverage). (Amount of sky dome in tenths covered by clouds or obscuring phenomena at the hour indicated at the time indicated.) Minimum value is 0; maximum value is 10; missing value is 99." liquidPrecipitationDepth

"The amount of liquid precipitation(mm) observed at the indicated hour for the period indicated in the liquid precipitation quantity field. If this value is not missing, then it is used and overrides the precipitation flag as rainfall. Conversely, if the precipitation flag shows rain and this field is missing or zero, it is set to 1.5 (mm)." barometricPressure

"This is the hourly weather station pressure in Pa. Valid values range from 31,000 to 120,000... Missing value for this field is 999999." modelYear

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

Import_epw

14

Ladybug Primer

Open EPW And STAT Weather Files

Use this component to automatically download a .zip file from the Department of Energy's (DOE) database, unzip the file, and open both the .epw and .stat weather files into Grasshopper. The component requires the URL of the zipped file for the specific climate that you want to import from the DOE's website. To open the DOE's website, use the Ladybug_download EPW Weather File component. Note that you can copy the zip file URL to your clipboard by right-clicking on the "ZIP" link for the climate that you want on the DOE's website and choosing "Copy Link Address." -

Inputs


15

Ladybug Primer weatherFileURL [Required]

A text string representing the .zip file URL from the Department of Energy's (DOE's) website. To open the DOE's website, use the Ladybug_download EPW Weather File component. Note that you can copy the zip file URL to your clipboard by right-clicking on the "ZIP" link for the climate that you want on the DOE's website and choosing "Copy Link Address." workingDir [Optional]

An optional text string representing a file path to a working directory on your computer where you would like to download and unzip the file. If nothing is set, the weather files will be downloaded to C:/ladybug/ and placed in a folder with the name of the weather file location.

Outputs epwFile

The file path of the downloaded epw file. statFile

The file path of the downloaded stat file. Check Hydra Example Files for Open EPW And STAT Weather Files


16

Ladybug Primer

Open EPW Weather File

Use this component to open an .epw weather file from a location on your computer. -

Inputs open [Required]

Set Boolean to True to browse for a weather file on your system.

Outputs

Open_EPW_Weather_File

17

Ladybug Primer epwFile

The file path of the selected epw file. Check Hydra Example Files for Open EPW Weather File

Open_EPW_Weather_File

18

Ladybug Primer

download EPW Weather File

Use this component to open the epwmap page in your default web browser and download an .epw weather file. -

Inputs download [Required]

Set Boolean to True to open the epw map page

Outputs download_EPW_Weather_File

19

Ladybug Primer readMe!

Will read 'Happy downloading...' in the case of successfully opening your browser Check Hydra Example Files for download EPW Weather File

download_EPW_Weather_File

20

Ladybug Primer

Construct Location

Use this component if you do not have an .epw weather file but have a latitude or other information on the site. The location output of this component can be used to make a sun plot in the absence of an .epw weather file. -

Inputs locationName [Required]

A name for the location you are constructing. (ie. Steventon Island, Antarctica)

Construct_Location

21

Ladybug Primer latitude [Required]

The latitude of the location you are constructing. Values must be between -90 and 90. Default is set to the equator. longitude [Default]

An optional numerical value representing the longitude of the location you are constructing. This can improve the accuracy of the resulting sun plot. timeZone [Default]

An optional integer representing the time zone of the location you are constructing. This can improve the accuracy of the resulting sun plot. The time zone should follow the epw convention and should be between -12 and +12, where 0 is at Greenwich, UK, positive values are to the East of Greenwich and negative values are to the West. elevation [Default]

An optional numerical value representing the elevation of the location you are constructing.

Outputs location

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

Construct_Location

22

Ladybug Primer

Decompose Location

Use this component to separate and exctract the information in the 'location' output of the importEPW or constructLocation component. -

Inputs location [Required]

The output from the importEPW or constructLocation component. This is essentially a list of text summarizing a location on the earth.

Decompose_Location

23

Ladybug Primer

Outputs locationName

Name of the location. latitude

Latitude of the location. longitude

Longitude of the location. timeZone

Time zone of the location. elevation

Elevation of the location. Check Hydra Example Files for Decompose Location

Decompose_Location

24

Ladybug Primer

Import Location

Use this component to import location data from a standard .epw file. You can use the output to draw a sunpath. -


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

Outputs Import_Location

25

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

Import_Location

26

Ladybug Primer

Import stat

Use this component to import climate data found in the .stat file that downloads with the .epw file (in the same .zip folder). Sepcifcally, this allows you to import the ASHRAE and Koppen climate zones as well as design temperatures representing the temperature extremes of the climate that should be used to design and size heating and cooling systems. Lastly, this component brings in the typical and extreme weeks of the year as ladybug analysis periods that can be plugged into the other ladybug components. -

Inputs statFile [Required]

Import_stat

27

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

Outputs readMe!

... ashraeClimateZone

The estimated ASHRAE climate zone of the STAT file. ASHRAE climate zones are frequently used to make suggestions for heating and cooling systems and correspond to recommendations for insulation levels of a building. For more information, see this pdf: https://www.ashrae.org/File%20Library/docLib/Public/20081111_CZTables.pdf koppenClimateZone

The estimated Koppen climate zone of the STAT file. The Koppen climate classification is the most widely used climate classification system and is based on the concept that native vegetation is the best expression of climate. Thus, Koppen climate zones combine average annual and monthly temperatures, precipitation, and the seasonality of precipitation. For more information, see the wikipendia page on Koppen climate: http://en.wikipedia.org/wiki/K%C3%B6ppen_climate_classification. heatingDesignTemp

The temperature in Celcius that ASHRAE recommends using to design a heating system for a building. It rempresents the one of the coldest temperatures of the year for which only 0.4% of the hours are below. coolingDesignTemp

The temperature in Celcius that ASHRAE recommends using to design a cooling system for a building. It rempresents the one of the hottest temperatures of the year for which only 0.4% of the hours are above. extremeHotWeek

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

Import_stat

28

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

An analysis period representing a typical week of the typical mean year. If the stat file does not specify a typical week, it is the typical week of Autumn. typicalColdWeek

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

An analysis period representing the coldest week of the typical mean year. If the stat file does not specify an extreme cold week, it is the most extreme week of the coldest season. Check Hydra Example Files for Import stat

Import_stat

29

Ladybug Primer

Open STAT File

Use this component to open a .stat file, which downloads with the .epw weather file and contains information such as the climate zone and maximum temperatures for designing heating/cooling systems. This component opens the file from a location on your computer. -

Inputs open [Required]

Set Boolean to True to browse for a .stat file on your system.

Open_STAT_File

30

Ladybug Primer

Outputs statFile

The file path of the selected .stat file. Check Hydra Example Files for Open STAT File

Open_STAT_File

31

Ladybug Primer

Create LB Header

Use this component to generates a Ladybug Header that can be combined with any raw data in order to format it for use with the Ladybug/Honeybee components. _ This component is particularly useful if you are bringing in data from other plugins or from instrumental measurements and you want to visualize it or analyze it with the Ladybug and Honeybee components. It is also useful if you want to replace the header on Ladybug data. -

Inputs location [Optional]

Create_LB_Header

32

Ladybug Primer A text string that represents the name of the location where the data was collected. If no value is connected here, the default will be "Somewhere." dataType [Optional]

A text string that represents the type of data that the header corresponds to. This can be "Temperature", "Wind", etc. If no value is connected here, the default will be "Some Data." units [Optional]

A text string that represents the units of the data. This can be "C", "m/s", etc. If no value is connected here, the default will be "Some Units." timeStep [Optional]

A text string that represents the time step of the data. Acceptable values include "Hourly", "Daily", "Monthly", or "Annually." If no value is connected here, the default will be "Hourly." analysisPeriod [Optional]

An optional analysis period from the Analysis Period component. If no analysis period is given, the default will be for the enitre year: (1,1,1)(12,31,24).

Outputs LBHeader

Script variable Python Check Hydra Example Files for Create LB Header

Create_LB_Header

33

Ladybug Primer

Component list: Analysis_Period Average_Data Branch_Data Separate_data CDD_HDD Wind_Speed_Calculator Adaptive_Comfort_Calculator Outdoor_Comfort_Calculator PMV_Comfort_Calculator Thermal_Comfort_Indices CDH_HDH Clothing_Function Humidity_Ratio_Calculat or

1 | AnalyzeWeatherData

34

Ladybug Primer

Analysis Period

Use this component to set an analysis period, which can be used as input for a variety of other Ladybug and Honeybee components. Default analysis period without any inputs is set to the entire year. -

Inputs fromMonth [Default]

A number between 1 and 12 that represents the month of the year for the start of the analysis. Default starting month is set to 1 (January).

Analysis_Period

35

Ladybug Primer fromDay [Default]

A number between 1 and 31 that represents the day of the month for the start of the analysis. Default starting day is set to 1 (the first of the month). fromHour [Default]

A number between 1 and 24 that represents the hour of the day for the start of the analysis. Default starting hour is set to 1 (the first hour of the day after midnight). toMonth [Default]

A number between 1 and 12 that represents the month of the year for the end of the analysis. Default end month is set to 12 (December). toDay [Default]

A number between 1 and 31 that represents the day of the month for the end of the analysis. Default end day is set to 31 (the 31st of the month). toHour [Default]

A number between 1 and 24 that represents the hour of the day for the end of the analysis. Default end hour is set to 24 (the last hour of the day before midnight)

Outputs readMe!

A text confirmation of the analysis period. analysisPeriod

Two tuples that represent the running period (fromMonth, fromDay, fromHour) to (toMonth, toDay, toHour) Check Hydra Example Files for Analysis Period

Analysis_Period

36

Ladybug Primer

Average Data

Use this component to select the data out of an annual hourly data stream (from the importEPW component) using the "Analysis Period" component. This componenent also averages or totals the connected hourly data for each day, month, and average hour of each month in the analysis period. -

Inputs annualHourlyData [Required]

An hourly data stream from the "Import epw" component.

Average_Data

37

Ladybug Primer analysisPeriod [Default]

The "analysisPeriod" Output from "Analysis Period" component. If no input is provided, the default analysis period is set to the whole year. totalOrAverage [Optional]

Set to 'True' to have the component total the values for the given periods and set to 'False' to have the component average them. The default is set to 'False' to average data.

Outputs readMe!

A text confirmation of the analysis period. selHourlyData

The hourly data stream for the analysis period. averagedDaily

The averaged data for each day during the analysis period. averagedMonthly

The averaged data for each month during the analysis period. avrMonthlyPerHour

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

The averaged data for the analysis period. Check Hydra Example Files for Average Data

Average_Data

38

Ladybug Primer

Branch Data

Use this component to convert any list of annual data into a data tree branched by day of the year, month of the year, or hour of the day. If the data is not 8760 value sof each hour, the number of data items should match number of items in HOY . -

Inputs data [Required]

A list of data to be branched for each month, day and hour. Note that this can be either a list of 8760 values for each hour of the year, the output of the "Import EPW"

Branch_Data

39

Ladybug Primer component, or a custom list of data that is matched by the data in the HOY_ input. HOY [Optional]

A list of numbers between 1 and 8760 that represents an hour of the year.

Outputs dataEachDayOfYear

The input data that has been branched data for each day of the year. The paths of the branches are in the following format {month ; dayOfMonth}. dataEachMonth

The input data that has been branched for each month of the year. Branch paths are from 0 to 11. dataEachHourOfDay

The input data that has been branched for each hour of the day. Branches are from 0 to 23. Check Hydra Example Files for Branch Data

Branch_Data

40

Ladybug Primer

Separate data

Use this component to separate the text strings from the numbers in the climate data streams output from the Import EPW component. You can then perform mathamatical functions on the numerical climate data using the Grasshopper math components or quickly preview the numerical data stream using the Grasshopper "Quick Graph" component. This component can also be used generally to separate any data stream that contains both numbers and text strings. -

Inputs inputList [Required]

Separate_data

41

Ladybug Primer A list of data that contains both text srtings and numbers. For example, a data stream output from the Import EPW component.

Outputs numbers

The numbers from in the _inputList data. Note that the order of numbers in this list is the same as the _inputList. strings

The text strings from in the _inputList data. Note that the order of text strings in this list is the same as the _inputList. Check Hydra Example Files for Separate data

Separate_data

42

Ladybug Primer

CDD_HDD

Calculates heating and cooling degree-days. Traditionally, degree-days are defined as the difference between a base temperature and the average ambient air temperature multiplied by the number of days that this difference exists. By default, this component uses a more accurate calculation than the traditional method based on the minimum and maximum temperature of each day. You may check the formulas in this page: "http://www.vesma.com/ddd/ddcalcs.htm" If you rather to use the traditional method, set useDailyAvrMethod to True. -

Inputs

CDD_HDD

43

Ladybug Primer hourlyDryBulbTemperature [Required]

Annual dry bulb temperature from the Import epw component (in degrees Celsius). coolingBaseTemperature [Default]

Base temperature for cooling (in degrees Celsius). Default is set to 23.3C but this can be much lower if the analysis is for a building with high heat gain or insulation. heatingBaseTemperature [Default]

Base temperature for heating (in degrees Celsius). Default is set to 18.3C but this can be much lower if the analysis is for a building with high heat gain or insulation. 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 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

CDD_HDD

44

Ladybug Primer The total cooling degree-days for the entire year. annual_heatingDegDays

The total heating degree-days for the entire year. Check Hydra Example Files for CDD_HDD

CDD_HDD

45

Ladybug Primer

Wind Speed Calculator

Use this component to calculate wind speed at a specific height for a given terrain type. By default, the component will calculate ground wind speed, which is useful for comfrt calculations. Also, by hooking up wind data from an epw file, you can use the resulting data to create a wind rose at any height. -

Inputs north [Optional]

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


46

Ladybug Primer 0 and 360 that represents the degrees off from the y-axis to make North. The default North direction is set to the Y-axis (0 degrees). windSpeed_tenMeters [Required]

The wind speed from the import EPW component or a number representing the wind speed at 10 meters off the ground in agricultural or airport terrian. This input also accepts lists of numbers representing different speeds at 10 meters. windDirection [Optional]

The wind direction from the import EPW component or a number in degrees represeting the wind direction from north, This input also accepts lists of numbers representing different directions. terrainType [Optional]

An interger from 0 to 3 that sets the terrain class associated with the output windSpeedAtHeight. Interger values represent the following terrain classes: 0 = Urban: large city centres, 50% of buildings above 21m over a distance of at least 2000m upwind. 1 = Suburban: suburbs, wooded areas. 2 = Country: open, with scattered objects generally less than 10m high. 3 = Water: Flat, unobstructed areas exposed to wind flowing over a large water body (no more than 500m inland). epwTerrain [Optional]

An optional interger from 0 to 3 that sets the terrain class associated with the output windSpeedAtHeight. The default is set to 2 for flat clear land, which is typical for most EPW files that are recorded at airports. Interger values represent the following terrain classes: 0 = Urban: large city centres, 50% of buildings above 21m over a distance of at least 2000m upwind. 1 = Suburban: suburbs, wooded areas. 2 = Country: open, with scattered objects generally less than 10m high. 3 = Water: Flat, unobstructed areas exposed to wind flowing over a large water body (no more than 500m inland). heightAboveGround [Optional]

Optional. This is the height above ground for which you would like to measure wind speed. Providing more than one value will generate a list of speeds at each given height. Default height is 1 m above ground, which is what a person standing on the ground would feel. analysisPeriod [Optional]

If you have connected data from an EPW component, plug in an analysis period from


47

Ladybug Primer the Ladybug_Analysis Period component to calculate data for just a portion of the year. The default is Jan 1st 00:00 - Dec 31st 24:00, the entire year. averageData [Optional]

Set to "True" to average all of the wind data that you have connected into a single speed and wind vector. The default is False, which means the component will return a list of all hours within the analysis period. If se tot Ture, the wind data will be averaged for the entire analysis period into a single value.

Outputs readMe!

... windSpeedAtHeight

The wind speed at the connected height above the ground. If averageData = True, this will be a single value representing the average speed for all connected values or values within the analysis period at each height. If averageData = False, this returns a list of

wind speeds for every hour within the analysis period at each height. Note than when averageData_ = False, the list will include a header specific to each list. This header can be removed by using the "Ladybug_Separate Data" component. windVectorAtHeight

Returns a list of vectors representing wind speed and direction at every hour within the analysis period, at each height provided. Check Hydra Example Files for Wind Speed Calculator


48

Ladybug Primer

Adaptive Comfort Calculator

Use this component to calculate the adaptive comfort for a given set of input conditions. This component will output a stream of 0's and 1's indicating whether certain conditions are comfortable given the prevailing mean monthly temperature that ocuppants tend to adapt themselves to. This component will also output a series of interger numbers that indicate the following: -1 = The average monthly temperature is too extreme for the adaptive model. 0 = The input conditions are too cold for occupants. 1 = The input conditions are comfortable for occupants. 2 = The input conditions are too hot for occupants. Lastly, this component outputs the percent of time comfortable, hot, cold and monthly extreme as well as a lit of numbers indicating the upper temperature of comfort and lower temperature of comfort. The adaptive comfort model was created in response to the shortcomings of the PMV model that

Adaptive_Comfort_Calculator

49

Ladybug Primer became apparent when it was applied to buildings wi thout 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. T his situation held true so

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/ long as the monthly mean temperature remained above 10 C and below 33.5 C.

Inputs dryBulbTemperature [Required]

A number representing the dry bulb temperature of the air in degrees Celcius. This input can also accept a list of temperatures representing conditions at different times or the direct output of dryBulbTemperature from the Import EPW component. meanRadiantTemperature [Optional]

A number representing the mean radiant temperature of the surrounding surfaces in degrees Celcius. If no value is plugged in here, this component will assume that the mean radiant temperature is equal to air temperature value above. This input can also accept a list of temperatures representing conditions at different times or the direct output of dryBulbTemperature from the Import EPW component. prevailingOutdoorTemp [Required]

A number representing the average monthly outdoor temperature in degrees Celcius. This average monthly outdoor temperature is the temperature that occupants in naturally ventilated buildings tend to adapt themselves to. For this reason, this input can also accept the direct output of dryBulbTemperature from the Import EPW component if houlry values for the full year are connected for the other inputs of this component. windSpeed [Optional]

A number representing the wind speed of the air in meters per second. If no value is plugged in here, this component will assume a very low wind speed of 0.3 m/s, Adaptive_Comfort_Calculator

50

Ladybug Primer characteristic of most naturally ventilated buildings. This input can also accept a list of wind speeds representing conditions at different times or the direct output of windSpeed from of the Import EPW component. comfortPar [Optional]

Optional comfort parameters from the "Ladybug_Adaptive Comfort Parameters" component. Use this to select either the US or European comfort model, set the threshold of acceptibility for comfort or compute prevailing outdoor temperature by a monthly average or running mean. These comfortPar can also be used to set a levelOfConditioning, which makes use of research outside of the official published standards that surveyed people in air conditioned buildings. 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. degreesFromTarget


51

Ladybug Primer A stream of temperature values in degrees Celcius indicating how far from the target temperature the conditions of the people are. Positive values indicate conditions hotter than the target temperature while negative values indicate degrees below the target temperture. targetTemperature

A stream of temperature values in degrees Celcius indicating the mean target temperture or neutral temperature that the most people will find comfortable. upperTemperatureBound

A stream of temperature values in degrees Celcius indicating the highest possible temperature in the comfort range for each hour of the input conditions. lowerTemperatureBound

A stream of temperature values in degrees Celcius indicating the lowest possible temperature in the comfort range for each hour of the input conditions. percentOfTimeComfortable

The percent of the input data for which the occupants are comfortable. Comfortable conditions are when the indoor temperature is within the comfort range determined by the prevailing outdoor temperature. percentHotCold

A list of 2 numerical values indicating the following: 0) The percent of the input data for which the occupants are too hot. 1) The percent of the input data for which the occupants are too cold. Check Hydra Example Files for Adaptive Comfort Calculator


52

Ladybug Primer

Outdoor Comfort Calculator

Use this component to calculate the Universal Thermal Climate Index (UTCI) for a set of input climate conditions. Perhaps the most familiar application of Univeral Thermal Climate Index (UTCI) is the temperature given by TV weathermen and women when they say that, "even though the dry bulb temperature outside is a certain value, the temperature actually "feels like" something higher or lower." UTCI is this temperature of what the weather "feels like" and it takes into account the radiant temperature (sometimes including solar radiation), relative humidity, and wind speed. UTCI uses these variables in a human energy balance model to give a temperature value that is indicative of the heat stress or cold stress felt by a human body in the outdoors. A UTCI between 9 and 26 degrees Celcius indicates no thermal stress or comfortable conditions outdoors. A UTCI between 26 and 28 degrees Outdoor_Comfort_Calculator

53

Ladybug Primer Celcius indicates slight heat stress (comfortable for short periods of time). Between 28 and 32 degrees, UTCI indicates moderate heat stress (hot but not dangerous). Between 32 and 38 degrees, UTCI indicates strong heat stress (dangerous beyond short periods of time). Above 38, UTCI indicates very strong to extreme heat stress (very dangerous). A UTCI between 0 and 9 degrees Celcius indicates slight cold stress (comfortable for short periods of time). Between 0 and -13 degrees, UTCI indicates moderate cold stress (cold but not dangerous). Between -13 and -27 degrees, UTCI indicates strong cold stress (dangerous beyond short periods of time). Below -27, UTCI indicates very stong to extreme cold stress (very dangerous). UTCI is result of the world's leading comfort specailists' attempt to make an interational standard of outdoor temperature sensation that fills the follwoing requirements: 1) Thermo-physiological significance in the whole range of heat exchange conditions of existing thermal environments 2) Valid in all climates, seasons, and scales 3) Useful for key applications in human biometeorology. _ The code that makes this component

possible is a Python version of the original Fortran code for calculating UTCI. Information on UTCI and the original Fortran code can be found here: http://www.utci.org/. -


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

54

Ladybug Primer This input can also accept a list of relative humidity values representing conditions at different times or the direct output of relativeHumidity from of the Import EPW component. 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).


55

Ladybug Primer conditionOfPerson

A stream of interger values from -3 to +3 that indicate the following: -3 - Strong Cold Stress - potential public health hazard with higher-than-normal mortality rates (UTCI < -13C). -2 - Moderate Cold Stress - cold but no public health hazard (-13C < UTCI < 0C). -1 - Slight Cold Stress - cool but comfortable for short periods of time (0C < UTCI < 9C) 0 - No Thermal Stress - comfortable conditions (9C < UTCI < 26C). +1 - Slight Heat Stress - warm but comfortable for short periods of time (26C < UTCI < 28C). +2 Moderate Heat Stress - hot but no public health hazard (28C < UTCI < 32C). +3 Strong Heat Stress - potential public health hazard with higher-than-normal mortality rates (UTCI > 32C). 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


56

Ladybug Primer

PMV Comfort Calculator

Use this component to calculate comfort metrics of Predicted Mean Vote (PMV), the Percent of People Dissatisfied (PPD), and the Standard Effective Temperature (SET) for a set of climate conditions and occupant behavior/clothing. This component can also calculate Outdoor Standard Effective Temperature (OUT-SET) if EPW weather data is connected. HOWEVER, if you are interested in knowing whether outdoor conditions are actually comfortable, it is highly recommended that you use the Ladybug UTCI Comfort Calculator. OUT-SET has been shown to be a poor indicator of outdoor comfort and is better used as a tool to help understand what clothing and metabolic rate a comfortable person might have in the outdoors AFTER running a UTCI study. Predicted Mean Vote (PMV) is a seven-point scale of occupant comfort from cold (-3) to hot (+3) that was used in the comfort surveys of


57

Ladybug Primer P.O. Fanger, who initially developed the scale and the PMV comfort model off of it. Each interger value of the PMV scale indicates the following: -3:Cold, -2:Cool, -1:Slightly Cool, 0:Neutral, +1:Slightly Warm, +2:Warm, +3:Hot. The range of comfort is generally accepted as a PMV between -1 and +1. Exceeding +1 will result in an uncomfortably warm occupant while dropping below -1 will result in an uncomfortably cool occupant. PMV is a MEAN vote because is meant to represent the average vote of all people under the input conditions. This component will output the PMV of the occupant for the input conditions as well as an estimated Percentage of People Dissatisfied (PPD) under the given conditions. PPD refers to the perceont of people that would give a PMV greater than/equal to 1 or less than/equal to -1. Note that, with this model, it is not possible to get a PPD of 0% and most engineers just aim to have a PPD below 20% when designing a HVAC system. This component will also output Standard Effective Temperature (SET), which is an ajusted temperature scale meant to reflect the heat stress or cold felt by the occupant. Specifically, SET is definied as the equivalent temperature of an imaginary environment at 50% relative humidity, <0.1 m/s air speed, and mean radiant temperature equal to air temperature, in which the total heat loss from the skin of an imaginary occupant is the same as that from a person existing under the input conditions. It is also important to note that the imaginary occupant is modeled with an activity level of 1.0 met and a clothing level of 0.6 clo. The actual occupant in the real

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/ environment can have different values from these.


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

58

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


59

Ladybug Primer Use this to adjust maximum and minimum acceptable humidity ratios. These comfortPar can also change whether comfort is defined by eighty or ninety percent of people comfortable. By default, comfort is defined as 90% of the occupants comfortable and there are no limits on humidity when there is no thermal stress. 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


60

Ladybug Primer The estimated percentage of people dissatisfied (PPD) under the given input conditions. Specifically, this is defined by the percent of people who would have a PMV less than -1 or greater than +1 under the conditions. Note that, with this model, it is not possible to get a PPD of 0% and most engineers just aim to have a PPD below 20%. standardEffectiveTemperature

The standard effective temperature (SET) for the given input conditions in degrees Celcius. SET is an ajusted temperature scale meant to reflect the heat stress or cold felt by the occupant. Specifically, SET is definied as the equivalent temperature of an imaginary environment at 50% relative humidity, <0.1 m/s air speed, and mean radiant temperature equal to air temperature, in which the total heat loss from the skin of an imaginary occupant is the same as that from a person existing under the input conditions. It is also important to note that the imaginary occupant is modeled with an activity level of 1.0 met and a clothing level of 0.6 clo. The actual occupant in the real environment can have different values from these. comfortableOrNot

A stream of 0's and 1's (or 'False' and 'True' values) indicating whether the occupant is comfortable for each hour of the input conditions. 0 indicates that the occupant is not comfortable while 1 indicates that the occupant is comfortable. 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


61

Ladybug Primer

Thermal Comfort Indices

Use this component to calculate various thermal comfort indices: HI (Heat Index) humidex (humidity index) DI (Discomfort Index) WCI (Wind Chill Index) WCT (Wind Chill Temperature)


62

Ladybug Primer WBGT (Wet-Bulb Globe Temperature) indoors WBGT (Wet-Bulb Globe Temperature) outdoors TE (Effective Temperature) AT (Apparent Temperature) TS (Thermal Sensation) ASV (Actual Sensation Vote) MRT (Mean Radiant Temperature) Iclp (Predicted Insulation Index Of Clothing) HR (Heart Rate) DhRa (Dehydration Risk) PET (Physiological Equivalent Temperature) THI (Temperature Humidity Index) PHS (Predicted Heat Strain) -

Inputs comfortIndex [Required]

Choose one of the comfort indices: 0 - HI (Heat Index) 1 - humidex (humidity index) 2 DI (Discomfort Index) 3 - WCI (Wind Chill Index) 4 - WCT (Wind Chill Temperature) 5 WBGT (Wet-Bulb Globe Temperature) indoors 6 - WBGT (Wet-Bulb Globe Temperature) outdoors 7 - TE (Effective Temperature) 8 - AT (Apparent Temperature) 9 - TS (Thermal Sensation) 10 - ASV (Actual Sensation Vote) 11 - MRT (Mean Radiant Temperature) 12 - Iclp (Predicted Insulation Index Of Clothing) 13 - HR (Heart Rate) 14 - DhRa (Dehydration Risk) 15 - PET (Physiological Equivalent Temperature) for temperate climates 16 - PET (Physiological Equivalent Temperature) for tropical and subtropical humid climates 17 - THI (Temperature Humidity Index) 18 - PHS (Predicted Heat Strain) location [Required]

Input data from Ladybug's "Import epw" "location" output, or create your own location data with Ladybug's "Construct Location" component. 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 Thermal_Comfort_Indices

63

Ladybug Primer same data you inputted to "_dryBulbTemperature". - If nothing supplied, it will be calculated for outdoor conditions (both in-shade and out-shade). - In Celsius degrees (°C). dewPointTemperature [Optional]

Dew point temperature. Input a single value or a whole list from "Import epw" component's "dewPointTemperature" output. - If not supplied, it will be calculated from dryBulbTemperature and relativeHumidity data. - In Celsius degrees (°C). relativeHumidity [Optional]

Relative humidity. Input a single value or a whole list from "Import epw" component's "relativeHumidity" output. - If not supplied 50% will be used as a default (indoor conditions). - In percent (from 0% to 110%). 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. globalHorizontalRadiation [Optional]

Total amount of direct and diffuse solar radiation that an analysis person received. Use the "globalHorizontalRadiation" data from Ladybug's "Import epw" component for analysis without shading. For analysis with shading included, use the "shadedSolarRadiationPerHour" output from "Sunpath shading" component instead. - If not supplied, default value of 0 Wh/m2 will be used (meaning: the analysis is conducted in outdoor in shade conditions, or indoor conditions). - In Wh/m2. totalSkyCover [Optional]

Amount of sky dome covered by clouds. Input a single value or a whole list from "Import epw" component's "totalSkyCover" output. It ranges from from 1 to 10. For example: 1 is 1/10 covered. 10 is total coverage (10/10). - If not supplied 6/10 will be used (cloud coverage of temperate humid climate). - In tenths of sky cover.


64

Ladybug Primer bodyCharacteristics [Optional]

A list of body characteristics in the following order: age, sex, height, weight, bodyPosition, clothingInsulation, acclimated, metabolicRate, activityDuration. Use Ladybug's "Body Characteristics" component to generate it. -

If not supplied, the following default values will be used: 30 - age "male" - sex 175 - height in centimeters 75 - weight in kilograms "standing" bodyPosition None (clothingInsulation - "None" means that it will be calculated based on air temperature) 37 - clothingAlbedo in % (for medium colored clothes) "unacclimated" acclimated 2.32 - metabolicRate in mets (2.32 corresponds to walking 4km/h) 480 activityDuration in minutes HOY [Optional]

An hour (or hours) of the year for which you would like to calculate thermal indices. These hours must be a value between 1 and 8760. This input will override the analysisPeriod_ input below. - If not supplied, this input will be ignored. 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!

... comfortIndexValue

The value of the chosen comfort. comfortIndexLevel

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


65

Ladybug Primer comfortableOrNot

Indication of whether that person is comfortable (1) or not (0) at particular hour. percentComfortable

Percentage of time, during which chosen index falls into the comfortable category. percentHotExtreme

Percentage of time, during which chosen index falls into the hot extreme category. percentColdExtreme

Percentage of time, during which chosen index falls into the cold extreme category. Check Hydra Example Files for Thermal Comfort Indices


66

Ladybug Primer

CDH_HDH

Calculates heating and cooling degree-hours. Degree-hours are defined as the difference between the base temperature and the average ambient outside air temperature multiplied by the number of hours that this difference condition exists. -

Inputs hourlyDryBulbTemperature [Required]

Annual dry bulb temperature from the Import epw component (in degrees Celsius).

CDH_HDH

67

Ladybug Primer coolingBaseTemperature [Default]

Base temperature for cooling (in degrees Celsius). Default is set to 23.3C but this can 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. CDH_HDH

68

Ladybug Primer annual_heatingDegHours

The total heating degree-days for the entire year. Check Hydra Example Files for CDH_HDH

CDH_HDH

69

Ladybug Primer

Clothing Function

Use this component to generate a list of values representing a clothing schedule based on outdoor air temperature. This schedule can be plugged into the clothingLevel_ input of the PMV Comfort Calculator component. By default, this function used to derive clothing levels based on outside temperature was developed by Schiavon, Stefano and implemented on the CBE comfort tool (http://smap.cbe.berkeley.edu/comforttool/). This version of the component allows users to change the maximum and minimum clothing levels, which Schiavon set at 1 and 0.46 respectively, and the temperatures at which these clothing levels occur, which Schiavon set at 26C and -5 C respectively. Note that Schiavon did not endorse the changing of these values but they are provided here to allow users an additional level of freedom. -

Clothing_Function

70

Ladybug Primer

Inputs outdoorAirTemperature [Required]

A number or list of numbers representing the dry bulb temperature of the air in degrees Celcius. This input can also accept the direct output of dryBulbTemperature from the Import EPW component and this is recommended for hourly comfort analysis. 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 Clothing_Function

71

Ladybug Primer _outdoorAirTemperature. Note that, if the component senses that you have hooked up a stream of hourly data, the clothing levels will alternate on a 12-hour basis. Check Hydra Example Files for Clothing Function

Clothing_Function

72

Ladybug Primer

Humidity Ratio Calculator

Calculates the humidity ratio from the ladybug weather file import parameters Conversion formulas are taken from the following publications: Vaisala. (2013) Humidity Conversion Formulas: Calculation Formulas for Humidity. www.vaisala.com/Vaisala%20Documents/Application%20notes/Humidity_Conversion_Form ulas_B210973EN-F.pdf W. Wagner and A. Pruß:" The IAPWS Formulation 1995 for the Thermodynamic Properties of Ordinary Water Substance for General and Scientific Use ", Journal of Physical and Chemical Reference Data, June 2002 ,Volume 31, Issue 2, pp. 387535 -

Inputs Humidity_Ratio_Calculator

73

Ladybug Primer dryBulbTemperature [Required]

The dry bulb temperature from the Import epw component. relativeHumidity [Required]

The relative humidity from the Import epw component. barometricPressure [Required]

The barometric pressure from the Import epw component.

Outputs readMe!

... humidityRatio

The hourly humidity ratio (kg water / kg air). enthalpy

The hourly enthalpy of the air (kJ / kg). partialPressure

The hourly partial pressure of water vapor in the atmosphere (Pa). saturationPressure

The saturation pressure of water vapor in the atmosphere (Pa). Check Hydra Example Files for Humidity Ratio Calculator

Humidity_Ratio_Calculator

74

Ladybug Primer

Component list: 3D_Chart Adaptive_Comfort_Chart Monthly_Bar_Chart Psychrometric_Chart GenCumulativeSkyMtx selectSkyMtx Colored_Sky_Visualizer Outdoor_Solar_Temperature_Adjustor Radiation_Calla_Lily Radiation_Rose Sky_Dome SunPath Wind_ Boundary_Prof ile Wind_Rose Import _Ground_ Temp

2 | VisualizeWeatherData

75

Ladybug Primer

3D Chart

Use this component to make a 3D chart in the Rhino scene of any climate data or hourly simulation data. -

Inputs inputData [Required]

A list of input data to plot. basePoint [Default]

3D_Chart

76

Ladybug Primer An optional point with which to locate the 3D chart in the Rhino Model. The default is set to the Rhino origin at (0,0,0). xScale [Default]

The scale of the X axis of the graph. The default will plot the X axis with a length of 3650 Rhino model units (for 365 days of the year). Connect a list of values for multiple graphs. yScale [Default]

The scale of the Y axis of the graph. The default will plot the Y axis with a length of 240 Rhino model units (for 24 hours of the day). Connect a list of values for multiple graphs. zScale [Default]

The scale of the Z axis of the graph. The default will plot the Z axis with a number of Rhino model units corresponding to the input data values. Set to 0 to see graphCurves appear on top of the mesh. Connect a list of values for multiple graphs. yCount [Default]

The number of segments on your y-axis. The default is set to 24 for 24 hours of the day. This variable is particularly useful for input data that is not for each hour of the year. legendPar [Optional]

Optional legend parameters from the Ladybug Legend Parameters component. condStatement [Optional]

An optional conditional statement, which will remove data from the chart that does not fit the conditions. The input must be a valid python conditional statement (e.g. a > 25). bakeIt [Optional]

If set to True, the chart will be Baked into the Rhino scene as a colored mesh. Text will be baked as Rhino text objects, which facilitates easy export to PDF or vector-editing programs.

Outputs readMe!

...

3D_Chart

77

Ladybug Primer graphMesh

A 3D plot of the input data as a colored mesh. Multiple meshes will be output for several input data streams or graph scales. graphCurves

A list of curves and text surfaces representing the time periods corresponding to the input data. Note that if the time period of the input data is not clear, no curves or labels will be generated here. legend

A legend of the chart. Connect this output to a grasshopper "Geo" component in order to preview the legend in the Rhino scene.g legendBasePts

The legend base point, which can be used to move the legend in relation to the chart with the native rasshopper "Move" component. title

The title text of the chart. Hook this up to a native Grasshopper 'Geo' component to preview it separately from the other outputs. titleBasePts

Points for placement of the title and axes labels of the chart, which can be used to move these text items in relation to the chart with the native Grasshopper "Move" component. dataPts

Points representing the location of each piece of data on the chart. Use this to label the points of the chart with text lables using a native grasshopper "Text Tag" component. conditionalHOY

The input data for the hours of the year that pass the conditional statement. Check Hydra Example Files for 3D Chart

3D_Chart

78

Ladybug Primer

Adaptive Comfort Chart

Use this component to calculate the adaptive comfort for a given set of input conditions. This component will output a stream of 0's and 1's indicating whether certain conditions are comfortable given the prevailing mean monthly temperature that ocuppants tend to adapt themselves to. This component will also output a series of interger numbers that indicate the following: -1 = The average monthly temperature is too extreme for the adaptive model. 0 = The input conditions are too cold for occupants. 1 = The input conditions are comfortable for occupants. 2 = The input conditions are too hot for occupants. Lastly, this component outputs the percent of time comfortable, hot, cold and monthly extreme as well as a lit of numbers indicating the upper temperature of comfort and lower temperature of comfort. The adaptive comfort model was created in response to the shortcomings of the PMV model that

Adaptive_Comfort_Chart

79

Ladybug Primer became apparent when it was applied to buildings wi thout 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. T his situation held true so

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/ long as the monthly mean temperature remained above 10 C and below 33.5 C.


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. prevailingOutdoorTemp [Required]

A number representing the prevailing outdoor temperature in degrees Celcius. For the ASHRAE standard, this is the average monthly outdoor temperature and, for the European standard, this is a running mean outdoor temperature calculated from the conditions of the last week. For this reason, this input can also accept the direct output of dryBulbTemperature from the 'Import EPW' component if houlry values for the full year are connected for the other inputs of this component. This input from the 'Import EPW' component is recommended.


80

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


81

Ladybug Primer current version of this component accepts "and" and "or" operators. To visualize the hourly data, only lowercase English letters should be used as variables, and each letter alphabetically corresponds to each of the lists (in their respective order): "a" always represents the 1st list plugged into annualHourlyData, "b" always represents the 2nd list plugged into annualHourlyData , "c" always represents the 3rd list plugged into annualHourlyData_, etc. For example, if you want to plot the data for the time period when temperature is between 18C and 23C, and humidity is less than 80%, the conditional statement should be written as “18
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. runIt [Required]

Set to "True" to run the component and generate an Adaptive comfort chart.

Outputs readMe!

... comfPercentOfTime

The percent of the input data for which the occupants are comfortable. Comfortable conditions are when the indoor temperature is within the comfort range determined by the prevailing outdoor temperature. percentHotCold

A list of 2 numerical values indicating the following: 0) The percent of the input data for which the occupants are too hot. 1) The percent of the input data for which the occupants are too cold.


82

Ladybug Primer comfortableOrNot

A stream of 0's and 1's (or "False" and "True" values) indicating whether occupants are comfortable under the input conditions given the fact that these occupants tend to adapt themselves to the prevailing mean monthly temperature. 0 indicates that a person is not comfortable while 1 indicates that a person is comfortable. conditionOfPerson

A stream of interger values from -1 to +1 that correspond to each hour of the input data and indicate the following: -1 = The input conditions are too cold for occupants. 0 = The input conditions are comfortable for occupants. +1 = The input conditions are too hot for occupants. degreesFromTarget

A stream of temperature values in degrees Celcius indicating how far from the target temperature the conditions of the people are. Positive values indicate conditions hotter than the target temperature while negative values indicate degrees below the target temperture. chartCurvesAndTxt

The chart curves and text labels of the adaptive chart. adaptiveChartMesh

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

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

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


83

Ladybug Primer default, this ouput is hidden and, to see it, you should connect it to a Grasshopper preview component. hourPointColors

Colors that correspond to the chartHourPoints above and can be hooked up to the "Swatch" input of a Grasshopper Preview component that has the hour points above connected as geometry. By default, points are colored red if they lie inside comfort polygon and are colored blue if they do not meet such comfort criteria. In the event that you have hooked up annualHourlyData_ this output will be a grafted list of colors. The first list corresponds to the comfort conditions while the second list colors points based on the annualHourlyData. hourPointLegend

A legend that corresponds to the hour point colors above. In the event that annualHourlyData_ is connected, this output will be a grafted list of legends that each correspond to the grafted lists of colors. Check Hydra Example Files for Adaptive Comfort Chart


84

Ladybug Primer

Monthly Bar Chart

Use this component to make a bar chart in the Rhino scene of any monhtly or avrMonthyPerHour climate data or simulation data. _ This component can also plot daily or hourly data but, for visualizing this type of data, it is recommended that you use the "Ladybug_3D Chart" component. -

Inputs inputData [Required]

A list of input data to plot. This should usually be data out of the 'Ladybug_Average

Monthly_Bar_Chart

85

Ladybug Primer Data' component or monthly data from an energy simulation but can also be hourly or daily data from the 'Ladybug_Import EPW.' However, it is recommended that you use the 'Ladybug_3D Chart' component component for daily or hourly data as this is usually a bit clearer. comfortModel [Optional]

An optional interger interger to draw the comfort comfort model on the chart. Choose Choose from the following: 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 float value to represent represent the outdoor temperature at 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 t hen the exterior. However, However, by default, this is set to 23.5C for fully outdoor conditions. stackValues 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. 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. 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 text string to replace the default default title of the chart of the chart. chart. The default is set to pick out the location of the data connected to 'inputData.' altYAxisTitle altYAxisTitle [Optional]

An optional text text string to replace the default default Y-Axis Y-Axis label of the chart. This can also also be a

Monthly_Bar_Chart

86

Ladybug Primer list of 2 y-axis titles if there are two different types of data connected to _inputData. The default is set to pick out the t he names of the first (and possibly the second) list connected to the 'inputData.' basePoint [Default]

An optional point point with which which to locate the 3D chart chart in the Rhino Model. Model. The default is set 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.

Outputs readMe!

... dataMesh

A series of meshes that that represent the different different monthly (or daily) daily) input data. Multiple Multiple lists of meshes will be output for several input data streams. dataCurves

A list of curves that represent represent the different avrMonthyPerHour avrMonthyPerHour and and hourly input data. data. Multiple lists of curves will be output for several input data streams. dataCrvColors

A list of colors that correspond correspond to the dataCurves dataCurves above. Hook this this up to the 'swatch' input of the native Grasshopper 'Preview' component component and the curves above up to the 'geometry input to preview the curves with their repective color. graphAxes

Monthly_Bar_Chart

87

Ladybug Primer A list of curves representing representing the axes of the chart. chart. graphLabels

A list of text meshes representing representing the time periods periods corresponding corresponding to the input data title

A title for the chart. By default, default, this is just the location location of the data but you can 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 that tells what each connected connected data stram's color color is. Connect this 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

A series of points that mark mark where each of the bars bars or lines of the chart chart lie. You 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 that represent the comfort range in each month according according to the input comfortModel_. Check Hydra Example Files for Monthly Bar Chart

Monthly_Bar_Chart

88

Ladybug Primer

Psychrometric Chart

Use this component to draw a psychrometric chart in the Rhino scene and evaluate a set of temperatures and humidity ratios in terms of indoor comfort. Connected data can include either outdoor temperature and humidty ratios from f rom 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 that is used in comfort surveys. Each interger interger value of the scale indicates the following: -3:Cold, -2:Cool, -1:Slightly Cool, 0:Neutral, +1:Slightly

Psychrometric_Chart

89

Ladybug Primer Warm, +2:Warm, +3:Hot. The range of comfort is generally accepted as a PMV between -1 and +1 and this is what defines the range of the comfort polygon on the psychrometric chart. Accordingly, Accordingly, this component will also output the PMV of the occupant for the input conditions 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 documentation on the comfort models can be found here: https://code.google.com/p/cbe-comfort-tool/w https://code.google.c om/p/cbe-comfort-tool/wiki/ComfortModel iki/ComfortModelss Special thanks goes to the

as well as an estimated percentage of people dissatisfied (PPD) in the given conditions.

authors of the online CBE Thermal Comfort Tool Tool who first made the javascript models in order to power the tool: Hoyt Tyler, Tyler, Schiavon Stefano, Piccioli Alberto, Moon Dustin, and Steinfeld Kyle, 2013, CBE Thermal Comfort Tool. 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.energyy.gov/buildings http://apps1.eere.energ .gov/buildings/tools_directory/so /tools_directory/software.cfm/ID=123/page ftware.cfm/ID=123/pagename=alph name=alph a_list a_list -

Inputs dryBulbTemperature dryBulbTemperature [Required]

A number representing representing the dry bulb temperature temperature of the air in degrees degrees Celcius. This This input can also accept a list of temperatures representing conditions at different times or the direct output of dryBulbTemperature dryBulbTemperature from the Import EPW component. Indoor temperatures from Honeybee energy simulations are also possible inputs. Finally, Finally, this component can also acccept temperatures in Farenheit 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 representing the relative humidity humidity of the air in percentage. 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 representing the barometric pressure pressure in Pascals. Pascals. If no value is connected connected here, the default pressure will be 101325 Pa, which is air pressure at sea level. It is recommended that you connect the barometric pressure from the Import epw component here as the air pressure at sea level can cause some misleading results for

Psychrometric_Chart

90

Ladybug Primer cities at higher elevations. meanRadTemperature meanRadTemperature [Optional]

A number representing representing the mean radiant radiant temperature of the surrounding surrounding surfaces. This This value should be in degrees Celcius unless you have connected values in Farenheit to the dryBulbTemperature and you are seeing a chart in IP units. If no value is plugged in here, this component will assume that the mean radiant temperature is equal to 23 C. This input can also accept a list of temperatures and this will produce several comfort polygons (one for each mean radiant temperature). windSpeed [Optional]

A number representing representing the wind speed speed of the air in meters per second. 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 conditions and this will produce several comfort polygons (one for each wind speed). metabolicRate [Optional]

A number representing representing the metabolic rate of the human subject subject in met. This input can 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, 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 representing the clothing level level of the human subject subject in clo. If no value 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 in the section above and you wish to merge all of the computed comfort polygons into one. Psychrometric_Chart

91

Ladybug Primer 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 create hourPointColors that correspond to the hours of the data (e.g. windSpeed). You can connect up several different annualHourly data here.

Psychrometric_Chart

92

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


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

Outputs readMe!

... totalComfortPercent

The percent of the input data that are inside all comfort and passive strategy polygons. totalComfortOrNot

A list of 0's and 1's indicating, for each hour of the input data, if the hour is inside a

Psychrometric_Chart

93

Ladybug Primer comfort or strategy polygon (1) or not(0). strategyNames

A list of names for the comfort polygons and strategeis that corresponds to the numbers in the following outputs. strategyPercentOfTime

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

A list of 0's and 1's indicating, for each hour of the input temperature and humidity ratio, if the hour is inside a given comfort or passive strategy polygon (1) or not(0). If there are multiple comfort polyogns or passive strategies connected to the passiveStrategy_ input, this output will be a grafted list for each polygon. Each list here corresponds to the names in the "strategyNames" output above. chartCurvesAndTxt

The chart curves and text labels of the psychrometric chart. psychChartMesh

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

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

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

Psychrometric_Chart

94

Ladybug Primer A brep representing the area of the chart made comfortable by the passive strategies. If multiple strategies have been hooked up to the passiveStrategy_ input, multiple polygons will be output here. chartHourPoints

Points representing each of the hours of input temperature and humidity ratio. By 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

Psychrometric_Chart

95

Ladybug Primer

GenCumulativeSkyMtx

This component uses Radiance's gendaymtx function to calculate the sky's radiation for each hour of the year. This is a necessary pre-step before doing radiation analysis with Rhino geometry or generating a radiation rose. The first time you use this component, you will need to be connected to the internet so that the component can download the "gendaymtx.exe" function to your system. Gendaymtx is written by Ian Ashdown and Greg Ward. For more information, check the Radiance manual at: http://www.radianceonline.org/learning/documentation/manual-pages/pdfs/gendaymtx.pdf -

Inputs

GenCumulativeSkyMtx

96

Ladybug Primer epwFile [Required]

The output of the Ladybug Open EPW component or the file path location of the epw weather file on your system. skyDensity [Default]

Set to 0 to generate a Tregenza sky, which will divide up the sky dome with a coarse density of 145 sky patches. Set to 1 to generate a Reinhart sky, which will divide up the sky dome using a very fine density of 580 sky patches. Note that, while the Reinhart sky is more accurate, it will result in considerably longer calculation times. Accordingly, the default is set to 0 for a Tregenza sky. 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

GenCumulativeSkyMtx

97

Ladybug Primer

selectSkyMtx

Use this component to select a specific sky matrix (skyMxt) for an hour of the year or for an analysis period. -

Inputs cumulativeSkyMtx [Required]

The output from a GenCumulativeSkyMtx component. HOY [Optional]

selectSkyMtx

98

Ladybug Primer An hour of the year for which you would like to select a sky. This must be a value between 1 and 8760. 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

selectSkyMtx

99

Ladybug Primer

Colored Sky Visualizer

Use this component to visualize a Perez sky as a colored mesh in the Rhino scene using the weather file location, a time and date, and an estimate of turbidity (or amount of particulates in the atmosphere. -


Input a vector to be used as a true North direction for the sky dome or a number between 0 and 360 that represents the degrees off from the y-axis to make North. The


100

Ladybug Primer default North direction is set to the Y-axis (0 degrees). location [Required]

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. domeOrRect [Optional]


101

Ladybug Primer Set to "True" to generate a sky color mesh that is in the shape of a dome and set to "False" to generate a sky as a flat rectangular mesh. The default is set to "True" to generate the sky as a dome.

Outputs readMe!

... coloredMesh

A colored mesh of the sky. meshLabels

Time and date lables for the sky mesh. skyColorRGB

The RGB colors that correspond to the vertices of the mesh above. skyColorXYZ

The XYZ colors that correspond to the vertices of the mesh above. Check Hydra Example Files for Colored Sky Visualizer


102

Ladybug Primer

Outdoor Solar Temperature Adjustor

Use this component to adjust an existing Mean Radiant Temperature for shortwave solar radiation. This adjusted mean radiant temperature can then be used in comfort studies. Note that this component assumes that you have already accounted for longwave radiation in the form of the _meanRadTemperature input. If you do not hook up a _meanRadTemperature, this component will assume that the surrounding radiant temperature is the same as the air temperature, which is a decent assumption for someone standing in an unobstructed field. However, the more obstacles that surround the person (and the more "context" that you add), the more important it is to derive a starting mean radiant temperature from a Honeybee Energy simulation. Also note that this component is not meant to account for shortwave radiation passing through glass.

This component uses Radiance functions in order to


103

Ladybug Primer determine the amount of direct and diffuse solar radiation falling on a comfort mannequin. The portion reflected off of the ground to the comfort mannequin is derived from these values of direct and diffuse radiation. Lastly, the formulas to translate this radiation into an effective radiant field and into a solar-adjusted mean radiant temperature come from this paper: Arens, Edward; Huang, Li; Hoyt, Tyler; Zhou, Xin; Shiavon, Stefano. (2014). Modeling the comfort effects of short-wave solar radiation indoors. Indoor Environmental Quality (IEQ). http://escholarship.org/uc/item/89m1h2dg#page-4 -


The location output from the 'Ladybug_Import epw' component. cumSkyMtxOrDirNormRad [Required]

Either the output from a GenCumulativeSkyMtx component (for high-resolution analysis) or the directNormallRadiation ouput from the 'Ladybug_Import epw' component (for simple, low-resolution analsysis). meanRadTemperature [Required]

A number or list of numbers representing the mean radiant temperature of the surrounding surfaces in degrees Celcius. This number will be modified to account for solar radiation. This input can be air temperature data from the 'Importepw' component and will follow the assumption that the surrounding mean radiant temperature is the same as the air temperature. This assumption is ok for a person in an outdoor open field. However, the more obstacles that surround the person (and the more 'contextShading ' that you add), the

more important it is to derive a starting mean radiant temperature from a Honeybee Energy simulation. bodyPosture [Optional]

An interger between 0 and 5 to set the posture of the comfort mannequin, which can have a large effect on the radiation for a given sun position. 0 = Standing, 1 = Sitting, 2 = Lying Down, 3 = Low-Res Standing, 4 = Low-Res Sitting, and 5 = Low-Res Lying Down. The default is set to 1 for sitting. rotationAngle [Optional]

An optional rotation angle in degrees. Use this number to adjust the angle of the comfort mannequin in space. The angle of the mannequin in relation to the sun can have a large effect on the amount of radiation that falls on it and thus largely affect the resulting mean radiant temperature. Outdoor_Solar_Temperature_Adjustor

104

Ladybug Primer bodyLocation [Optional]

An optional point that sets the position of the comfort mannequin in space. Use this to move the comfort mannequin around in relation to contextShading_ connected below. Note that this point should be the center of gravity of your person. The default is set to a person just above the Rhino origin. contextShading [Optional]

Optional breps or meshes that represent shading or opaque solar obstructions around the mannequin. If you are using this component for indoor studies, windows or any transparent materials should not be included in this geometry. You should factor the transmissivity of these materials in with the windowTransmissivity_ input. Also, note that, if you have a lot of this context geometry, you should make sure that you input a starting _meanRadTemperature that accounts for the temperature of all the temperture of these shading surfaces. north [Optional]

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


105

Ladybug Primer outdoor conditions. analysisPeriodOrHOY [Optional]

An optional analysis period from the 'Analysis Period component' or an hour of the year between 1 and 8760 for which you want to conduct the analysis. If no value is connected here, the component will run for noon on the winter solstice. 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. parallel [Optional]

Set to 'True' to run the component using multiple CPUs. This can dramatically decrease calculation time but can interfere with other intense computational processes that might be running on your machine. For this reason, the default is set to 'True.' runIt [Required]

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


106

Ladybug Primer The estimated solar adjusted mean radiant temperature for each hour of the analysis period. This is essentially the change in mean radiant temperature above added to the hourly _meanRadTemperature input. This is in degreed Celcius and can be plugged into any comfort components for comfort studies. mannequinMesh

A colored mesh of a comfort mannequin showing the amount of radiation falling over the mannequin's body. legend

A legend that corresponds to the colors on the mannequinMesh and shows the relative W/m2. legendBasePt

The input data normalized by the floor area of it corresponding zone. meshFaceResult

If 'tempOrRad' is set to True, this will be the estimated solar adjusted radiant temperature for each mesh face of the mannequin in degrees Celcius. This radiant temperature is averaged over the the entire analysis period. if 'tempOrRad' is set to False, this will be the total radiation on each mesh face over the analysis period. meshFaceArea

The areas of each mesh face of the mannequin in square Rhino model units. This list corresponds to the meshFaceRadTemp list above and can be used to help inform statistical analysis of the radiant assymmetry over the mannequin. Check Hydra Example Files for Outdoor Solar Temperature Adjustor


107

Ladybug Primer

Radiation Calla Lily

Use this component to draw Radiation Calla Lily or Dome, which shows you how radiation would fall on an object from all directions for a given sky. It is useful for finding the best direction with which to orient solar panels and gives a sense of the consequences of

The Calla Lily/Dome can be understood in three different ways: _ 1) The Calla Lily/Dome a 3D representation of all possible radiation roses for a given sky since it includes all vertical angles from 0 to 90. 2) The Calla Lily/Dome is the reciprocal of the Tergenza Sky Dome since the Cala Dome essentially shows you how the radiation from the sky will fall onto a hemispherical object. 3) The Calla Lily/Dome is a smart radiation analysis of a hemisphere. Your results would effectively be the same if you made a deviating from such an orientation.


108

Ladybug Primer hemisphere in Rhino and ran it through the "Radiation Analysis" component but, with this component, you will get a smoother color gradient and the component will automatically output the point (or vector) with the most radiation. -

Inputs selectedSkyMtx [Required]

The output from the selectSkyMtx component. horAngleStep [Default]

An angle in degrees between 0 and 360 that represents the step for horizontal rotation. Smaller numbers will yeild a finer and smoother mesh with smoother colors. The number input here should be smaller than 360 and divisible by 360. The default is set to 10 degrees. verAngleStep [Default]

Angle in degrees step between 0 and 90 that represents the step for vertical rotation. Smaller numbers will yeild a finer and smoother mesh with smoother colors. The number input here should be smaller than 90 and divisible by 90. The default is set to 10 degrees. centerPoint [Default]

Input a point to locate the center point of the Calla Lily Graph horScale [Default]

Input a number here to change horizontal (XY) scale of the graph. The default value is set to 1. Note that, for the dome representation, this input will change the scale of the entire dome (both horizontal and vertical). verScale [Default]

Input a number here to change vertical (Z) scale of the graph. The default value is set to 1. Note that, for the dome representation, this input will have no effect. domeOrLily [Optional]

Set to "True" to have the component create a radiation dome and set to "False" to have it generate a Lily. The default is set to "False" for a Lily. The difference between the Dome and the Lily is that, for the Lily, the Z scale is essentially the same as the color scale, which is redundant but also beautiful and potentially useful if you have to present


109

Ladybug Primer For the Dome, the vertical angles of rotation serve to define the Z scale. In this sense, the normal to the dome at any given point is the angle at which the radiation study is being run. This gives a geometric intuitive sense of how you should orient panels to capture or avoid the most sun. data with a Black/White printer or to someone who is color blind.

legendPar [Optional]


Set to "True" to run the component and generate a radiation Calla Lily. bakeIt [Optional]

Set to "True" to bake the Calla Lily into the Rhino scene.

Outputs readMe!

... radiationLilyMesh

A colored mesh representing radiation of the Calla Lily or Dome. baseCrvs

A set of guide curves for the Calla Lily. legend

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

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

Information for each test point of the Calla Lily mesh. "HRA" stands for "Horizontal Rotation Angle" while "VRA" stand for "Vertical Rotation Angle." HRA varies from 0 to 360 while VRA varies from 0 to 90.


110

Ladybug Primer values

The radiation values for each test points (or mesh faces) of the Calla Lily in kWh/m2. maxRadPt

The point on the Cala Lilly with the greatest amount of solar radiation. This is useful for understanding the best direction to orient solar panels. maxRadVector

The vector that should be used to orient solar panels such that they recieve the greatest possible solar radiation. maxRadInfo

Information about the test point with the greates amount of radiation in the Calla Lily. "HRA" stands for "Horizontal Rotation Angle" while "VRA" stand for "Vertical Rotation Angle." HRA varies from 0 to 360 while VRA varies from 0 to 90. Check Hydra Example Files for Radiation Calla Lily


111

Ladybug Primer

Radiation Rose

Use this component to make a radiation rose in the Rhino scene. Radiation roses give a sense of how much radiation comes from the different cardinal directions, which will give an initial idea of where glazing should be minimized, shading applied, or solar collectors placed. -



Radiation_Rose

112

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

113

Ladybug Primer one of the total radiation. runIt [Required]

Set to "True" to run the component and generate a radiation rose. bakeIt [Optional]

Set to "True" to bake the radiation rose into the Rhino scene.

Outputs readMe!

... radiationArrowsMesh

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

A set of guide curves that mark the directions of radiation analysis. legend

A legend of the radiation rose. Connect this output to a grasshopper "Geo" component in order to preview the legend separately in the Rhino scene. legendBasePts

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

The end points of the rose arrows. radRoseValues

The radiation values in kWh/m2 for each rose arrow. Check Hydra Example Files for Radiation Rose

Radiation_Rose

114

Ladybug Primer

Sky Dome

This component allows you to visualize a selected sky matrix from the selectSkyMxt component in order to see the patches of the sky dome where radiation is coming from. The component will produce 3 sky domes by default: a dome showing just the diffuse radiation, a dome showing just the direct radiation, and a dome showing the total radiation. -



Sky_Dome

115

Ladybug Primer 0 and 360 that represents the degrees off from the y-axis to make North. The default North direction is set to the Y-axis (0 degrees). 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. 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. runIt [Required]

Set to "True" to run the component and generate a sky dome. bakeIt [Optional]

Set to "True" to bake the sky dome into the Rhino scene.

Outputs readMe!

... skyPatchesMesh

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

Sky_Dome

116

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

A legend for the sky dome. Connect this output to a grasshopper "Geo" component in order to preview the legend separately in the Rhino scene. legendBasePts

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

Sky_Dome

117

Ladybug Primer

SunPath

Use this component to make a 3D sun-path (aka. sun plot) in the Rhino scene. The component also outputs sun vectors that can be used for sunlight hours analysis or shading design with the other Ladybug components. The sun-path function used here is a Python version of the RADIANCE sun-path script by Greg Ward. The RADIANCE source code can be accessed at: http://www.radiance-online.org/download-install/CVS%20source%20code -


SunPath

118

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

SunPath

119

Ladybug Primer sunScale [Default]

Input a number here to change the scale of the sun spheres located along the sun path. The default is set to 1. 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
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 [Optional]

Set to 'True' to have the sunPath display in solar time and set to 'False' to have it display in standard time. The default is set to 'False.' Note that this input only changes the way in which the supath curves are drawn currently and does not yet change the position of the sun based on the input hour. bakeIt [Optional]

SunPath

120

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

Outputs readMe!

... sunVectors

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

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

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

A colored mesh of spheres representing sun positions. Colors indicate annualHourlyData and will be yellow if no data is hooked up to annualHourlyData . sunPathCrvs

A set of guide curves that mark the path of the sun across the sky dome. legend

A legend for the sun path. Connect this output to a grasshopper "Geo" component in 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

SunPath

121

Ladybug Primer Point for the placement of the title, which can be used to move the title in relation to the sun path with the native Grasshopper "Move" component. sunPathCenPts

The center point of the sun path (or sun paths if multiple annualHourlyData_ streams are connected). Use this to move sun paths around in the Rhino scene with the grasshopper "move" component. sunPositions

Point(s) idicating the location on the sun path of each sun position. sunPositionsInfo

Detailied information for each sun position on the sun path including date and time. sunPositionsHOY

The hour of the year for each sun position on the sun path. selHourlyData

The annualHourlyData for each sun position on the sun path. Note that this data has the following removed from it: 1) Any parts of the annualHourlyData that happen when the sun is down, 2) annualHourlyData that is not apart of the analysisPeriod and, 3) annualHourlyData_ that does not fit the conditional statement. Check Hydra Example Files for SunPath

SunPath

122

Ladybug Primer

Wind Boundary Profile

Use this component to visualize a wind profile curve for a given terrain type. Wind speed increases as one leaves the ground and wind profiles are a means of visualizing this change in wind speed with height. - More information on the power law of the wind profile can be found here: http://en.wikipedia.org/wiki/Wind_profile_power_law -




123

Ladybug Primer 0 and 360 that represents the degrees off from the y-axis to make North. The default North direction is set to the Y-axis (0 degrees). windSpeed_tenMeters [Required]

The wind speed from the import EPW component or a number representing the wind speed at 10 meters off the ground. If this value is input without a corresponding wind direction below, the profile will be drawn with the average of the speed input here. If corresponding values are connected to the windDirection, the speed on the profile will be the average speed of the prevailing wind direction. windDirection [Optional]

An optional number representing the degrees from north of the wind direction. This can also be the windDirection output from the import EPW component. This direction will be used to orient the wind profile in 3 dimensions to the direction of the prevailing wind. terrainType [Optional]

An interger from 0 to 3 that sets the terrain class associated with the output windSpeedAtHeight. Interger values represent the following terrain classes: 0 = Urban: large city centres, 50% of buildings above 21m over a distance of at least 2000m upwind. 1 = Suburban: suburbs, wooded areas. 2 = Country: open, with scattered objects generally less than 10m high. 3 = Water: Flat, unobstructed areas exposed to wind flowing over a large water body (no more than 500m inland). epwTerrain [Optional]

An optional interger from 0 to 3 that sets the terrain class associated with the output windSpeedAtHeight. The default is set to 2 for flat clear land, which is typical for most EPW files that are recorded at airports. Interger values represent the following terrain classes: 0 = Urban: large city centres, 50% of buildings above 21m over a distance of at least 2000m upwind. 1 = Suburban: suburbs, wooded areas. 2 = Country: open, with scattered objects generally less than 10m high. 3 = Water: Flat, unobstructed areas exposed to wind flowing over a large water body (no more than 500m inland). HOY [Optional]

Use this input to select out specific indices of a list of values connected for wind speed and wind direction. If you have connected hourly EPW data, this is the equivalent of a "HOY" input and you can use the "LadybugDOY_HOY" component to select out a specific hour and date. Note that this overrides the analysisPeriod input below. analysisPeriod [Optional]


124

Ladybug Primer If you have connected data from an EPW component, plug in an analysis period from the Ladybug_Analysis Period component to calculate data for just a portion of the year. The default is Jan 1st 00:00 - Dec 31st 24:00, the entire year. 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
An optional point that can be used to change the base point at shich the wind profile curves are generated. By default, the wond profile curves generate at the Rhino model origin. windVectorScale [Optional]

An optional number that can be used to change the scale of the wind vectors in relation to the height of the wind profile curve. The default is set to 5 so that it is easier to see how the wind speed is changing with height. windProfileHeight [Optional]

An optional number in rc model units that can be used to change the height of the wind profile curve. By default, the height of the curve is set to 30 meters (or the equivalent distance in your Rhino model units). You may want to move this number higher or lower depending on the wind effects that you are interested in. Wind_Boundary_Profile

125

Ladybug Primer distBetweenVec [Optional]

An optional number in rhino model units that represents the distance between wind vectors in the profile curve. The default is set to 2 meters (or the equivalent distance in your rc model units). windArrowStyle [Optional]

An optional integer to set the style of the wind vectors. The default is set to 1 for colored arrows. Choose from the following options: 0 = No Wind Arrows - use this option if you do not want to gerenate arrows. 1 = 3D Colored Wind Arrows - use this option to generate arrows as a colored 3D mesh (arrows will be colored based on the magnitude of their wind speed). 2 = High-Res 3D Colored Wind Arrows - use this option to create color arrows just like Option 1 but with a circular cross section and smooth edges. 3 = Colored Line Wind Arrows - use this option to generate arrows as lines with colored tips. 4 = Black Line Wind Arrows - use this option to generate arrows as lines with black tips. legendPar [Optional]

Optional legend parameters from the Ladybug Legend Parameters component. bakeIt [Optional]

Set to "True" to bake the wind boundary profile into the Rhino scene.

Outputs readMe!

... windSpeeds

The wind speeds that correspond to the wind vectors in the wind profile visualization. windVectors

The wind vectors that correspond to those in the wind profile visualization. Note that the magnitude of these vectors will be scaled based on the windVectorScale_ input. vectorAnchorPts

Anchor points for each of the vectors above, which correspond to the height above the ground for each of the vectors. Connect this along with the output above to a Grasshopper "Vector Display" component to see the vectors as a grasshopper vector


126

Ladybug Primer display (as opposed to the vector mesh below). windVectorMesh

A mesh displaying the wind vectors that were used to make the profile curve. windProfileCurve

A curve outlining the wind speed as it changes with height. This may also be a list of wind profile curves if multiple "HOY " inputs are connected or "averageData " is set to False." profileAxes

Script variable WindBoundaryProfile axesText

The meshes of the axes text (labelling wind speeds and heights). legend

A legend of the wind profile curves. Connect this output to a grasshopper "Geo" component in order to preview the legend separately in the rc scene. legendBasePt

The legend base point(s), which can be used to move the legend in relation to the wind profile with the grasshopper "move" component. Check Hydra Example Files for Wind Boundary Profile


127

Ladybug Primer

Wind Rose

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

Inputs north [Default]

Input a vector to be used as a true North direction for the wind rose or a number between 0 and 360 that represents the degrees off from the y-axis to make North. The default North direction is set to the Y-axis (0 degrees).

Wind_Rose

128

Ladybug Primer hourlyWindDirection [Required]

The list of hourly wind direction data from the Import epw component. hourlyWindSpeed [Required]

The list of hourly wind speed data from the Import epw component. 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
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]

Input a point here to change the location of the wind rose in the Rhino scene. The default is set to the Rhino model origin (0,0,0). maxFrequency [Optional]

Wind_Rose

129

Ladybug Primer An optional number between 1 and 100 that represents the maximum percentage of hours that the outer-most ring of the wind rose represents. By default, this value is set by the wind direction with the largest number of hours (the highest frequency) but you may want to change this if you have several wind roses that you want to compare to each other. For example, if you have wind roses for different months or seasons, which each have different maximum frequencies. scale [Default]

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


Set this value to "True" to run the component and generate a wind rose in the Rhino scene. bakeIt [Optional]

Set this value to "True" to bake the wind rose into the Rhino scene.

Outputs readMe!

... calmRoseMesh

A mesh in the center of the wind rose representing the relative number of hours where the wind speed is around 0 m/s. windRoseMesh

A mesh representing the wind speed from different directions for all hours analyzed. windRoseCrvs

A set of guide curves that mark the number of hours corresponding to the windRoseMesh. windRoseCenPts

Wind_Rose

130

Ladybug Primer The center point(s) of wind rose(s). Use this to move the wind roses in relation to one another using the grasshopper "move" component. legend

A legend of the wind rose. Connect this output to a grasshopper "Geo" component in 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. Check Hydra Example Files for Wind Rose

Wind_Rose

131

Ladybug Primer

Import Ground Temp

Use this component to visualise ground temperatures throughout the year at specific depths. Please note that epw files usually only provide ground temperature data at depths 0.5 meters, 2 meters and 4 meters thus data has been interpolated for all other depths. In particular this interpolation assumes that ground temperatures do not vary over the seasons once the depth has reach 9 meters below the ground surface. -


Import_Ground_Temp

132

Ladybug Primer An .epw file path on your system as a string visualisedata_Season []

Set to true to visualise the ground temperature data as an average for every season visualisedata_Month []

Set to true to visualise the ground temperature data for every month

Outputs readMe!

... groundtemp1st

In every epw file there are monthly ground temperatures at 3 different depths this is the 1st groundtemp2nd

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

Import_Ground_Temp

133

Ladybug Primer This output draws the text of the graph it doesn't need to be connected to anything Legend

Script variable Importgroundtemp Check Hydra Example Files for Import Ground Temp

Import_Ground_Temp

134

Ladybug Primer

Component list: Radiation_Analysis Sunlight_Hours_Analysis Bounce_from_Surface View_Analysis View_From_Sun view_Rose Comfort_Shade_Benefit_Evaluator ShadingDesigner SolarEnvelope SolarFan DC_to_AC_derate_factor Photovoltaics _Performance_Metrics Photovoltaics_Surface Sunpath_Shading Tilt_And_Orientation_Factor Forward_Raytracing SolarEnvelopeBasic SolarFanBasic

3 | EnvironmentalAnalysis

135

Ladybug Primer

Radiation Analysis

This component allows you to calculate the radiation fallin on input _geometry using a sky matrix from the selectSkyMxt component. This type of radiation sutdy is useful for building surfaces such as windows, where you might be interested in solar heat gain, or solar panels, where you might be interested in the energy that can be collected. This component is also good for surfaces representing outdoor spaces (such as parks or seating areas) where radiation could affect thermal comfort or vegetation growth. No reflection of sunlight is included in the radiation analysis with this component and it should therefore be used neither for interior daylight studies nor for complex geometries nor for surfaces with high a reflectivity. For these situations where the relfection of light is important, the Honeybee daylight components should be used instead of this one. Radiation_Analysis

136

Ladybug Primer


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 radiation mesh of this component is offset to the wrong side of test _geometry, you should use the "Flip" Rhino command on the test _geometry before inputting it to this component. orientationStudyP [Optional]

Optional output from the "Orientation Study Parameter" component. You can use an Orientation Study input here to answer questions like "What orientation of my building will give me the highest or lowest radiation gain for my analysis period?" An Orientation Study will automatically rotate your input _geometry around several times and record the radiation results each time in order to output a list of values for totalRadiation and a grafted data stream for radiationResult. selectedSkyMtx [Required]

Radiation_Analysis

137

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

Set to True to bake the analysis results into the Rhino scene. 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!

... contextMesh

An uncolored mesh representing the context_ geometry that was input to this component. Connect this output to a "Mesh" grasshopper component to preview this output seperately from the others of this component. Note that this mesh is generated before the analysis is run, allowing you to be sure that the right geometry will be run Radiation_Analysis

138

Ladybug Primer through the analysis before running this component. analysisMesh

An uncolored mesh representing the test _geometry that will be analyzed. Connect this output to a "Mesh" grasshopper component to preview this output seperately from the others of this component. Note that this mesh is generated before the analysis is run, allowing you to be sure that the right geometry will be run through the analysis before running this component. testPts

The grid of test points on the test _geometry that will be used to perform the radiation analysis. Note that these points are generated before the analysis is run, allowing you to preview the resolution of the result before you run the component. testVec

Vectors for each of the test points on the test _geometry, which indicate the direction for which radiation analysis is performed. Hook this and the test points up to a Grasshopper "Vector Display" component to see how analysis is performed on the test _geometry. radiationResult

The amount of radiation in kWh/m2 falling on the input test _geometry at each of the test points. radiationMesh

A colored mesh of the test _geometry representing the radiation in kWh/m2 falling on this input _geometry for the selected sky. radiationLegend

A legend for the radiation study showing radiation values that correspond to the colors of the radiationMesh. Connect this output to a grasshopper "Geo" component in order to preview the legend separately in the Rhino scene. legendBasePt

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

The total radiation in kWh falling on the input test _geometry. This is computed through Radiation_Analysis

139

Ladybug Primer a mass addition of results at each of the test points in kWh/m2 multiplied by the area of the face that the test point is representing. intersectionMtx

A python list that includes the relation between each test point and all the sky patchs on the sky dome. After running a basic radiation study, you can connect this output to the Ladybug "Real Time Radiation Analysis" component to scroll through the radiation falling on your test geometry on an hour-by-hour, day-by-day, or month-by-month basis in real time. Check Hydra Example Files for Radiation Analysis

Radiation_Analysis

140

Ladybug Primer

Sunlight Hours Analysis

This component calculates the number of hours of direct sunlight received by input geometry using sun vectors from the sunPath component. This component can be used to evaluate the number of hours of sunlight received by vegetation in a park or the hours where direct sunlight might make a certain outdoor space comfortable or uncomfortable. It can also be used for coarsely-gridded shadow studies in the Rhino scene . For finer and more detailed shadow studies with simple input geometry, the Ladybug ShadowStudy component can be used. For detailed shadow studies with complex geometry, the Honeybee daylight tools are recommended. -

Inputs Sunlight_Hours_Analysis

141

Ladybug Primer 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 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 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. sunVectors [Required]

Sun vectors from the sunPath component, which will be used to determine the number of hours of direct sunlight received by the test _geometry. timeStep [Default]

The number of timesteps per hour used by the sunPath component that generated the sun vectors. This number should be smaller than 60 and divisible by 60. The default is Sunlight_Hours_Analysis

142

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

Set to "True" to bake the analysis results into the Rhino scene. 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. Input here must be a string without special characters. If "bakeIt_" is set to "True", the result will be baked into a layer with this project name.

Outputs readMe!

...


143

Ladybug Primer contextMesh

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


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

144

Ladybug Primer legendBasePt

The legend base point, which can be used to move the legend in relation to the sunlight hours mesh with the grasshopper "move" component. totalSunlightHours

The average number of hours of direct sunlight received by the test _geometry. sunIsVisible

A grafted data stream for each test point with a "1" for each hour of the sunVectors that the sun is visible and a "0" for each hour of the sunVectors when the sun is blocked. Check Hydra Example Files for Sunlight Hours Analysis


145

Ladybug Primer

Bounce from Surface

Use this component to get a sense of how direct sunlight is reflected off of an initial sourceSrf and subsequently to a set of context geometries by tracing sun rays forwards through this geometry. Examples where this component might be useful include the evaluation of the diffusion of light by a light shelf, or testing to see whether a parabolic building geometry (like a Ghery building) might focus sunlight to dangerous levels at certain times of the year. Note that this component assumes that all sun light is reflected off of these geometries specularly (as if they were a mirror) and, for more detailed raytrace analysis, the Honeybee daylight components should be used. -

Inputs Bounce_from_Surface

146

Ladybug Primer sourceSrfs [Required]

A brep or mesh representing a surface that you are interested in seeing direct sunlight bounce off of. You can also put in lists of breps or meshes. These surfaces will be used to generate the initial sun rays in a grid-like pattern. Note that, for curved surfaces, smooth meshes of the geometry will be more accurate than inputing a Brep. gridSizeOrPoints [Required]

A number in Rhino model units that represents the average size of a grid cell to generate the points, or list of points itself. Note that, if you put in meshes for the input above, the _gridSize number option of this input will not work as this component will use the vertices of the mesh to generate the sun rays. sunVectors [Required]

A sun vector from the sunPath component or a list of sun vectors to be forward raytraced. context [Optional]

Breps or meshes of conext geometry, which will reflect the sun rays after they bounce off of the _sourceSrfs. Note that, for curved surfaces, smooth meshes of the geometry will be more accurate than inputing a Brep. numOfBounce [Default]

An interger representing the number of ray bounces to trace the sun rays forward. lastBounceLen [Default]

A number representing the length of the sun ray after the last bounce. If left empty, this length will be the diagonal of the bounding box surrounding all input geometries. firstBounceLen [Optional]

A number representing the length of the sun ray before the first bounce. If left empty, this length will be the diagonal of the bounding box surrounding all input geometries.

Outputs rays

The sun rays traced forward through the geometry. bouncePts

Bounce_from_Surface

147

Ladybug Primer The generated base points on the _sourceSrfs to which the sun rays will be directed. The preview of this output is set to be hidden by default. Connect to a Grasshopper "Point" component to visualize. Check Hydra Example Files for Bounce from Surface

Bounce_from_Surface

148

Ladybug Primer

View Analysis

Use this component to evaluate the visibility of input _geometry from a set of key viewing points. For example, this component can be used to evaluate the visibility of an 3D architectural feature from a set of key viewing points along a nearby street or park where people congregate. Another example would be evaluating the visibility of park vegetation geometry from a set of key sun position points from the sunPath component. Yet another example would be evaluating the "visibility" of an outdoor overhead radiative heater from a set of key "viewing" points located over a human body standing beneath it. This component outputs a percentage of viewpoints seen by the input _geometry. In the three examples here, this would be the percentage of the 3D architectural feature seen from the street, the

View_Analysis

149

Ladybug Primer percentage of sunlit hours received by the vegetation, or the percentage of the human body warmed by the heater. This component will evaluate view from the test points objectively in all directions. -

Inputs geometry [Required]

Geometry for which visibility analysis will be conducted. Geometry must be either a Brep, a Mesh, or a list of Breps or Meshes. context [Optional]

Context geometry that could block the view from the _viewTypeOrPoints to the test _geometry. Conext geometry must be either a Brep, a Mesh, or a list of Breps or Meshes. gridSize [Default]

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]

View_Analysis

150

Ladybug Primer An integer representing the type of view analysis that you would like to conduct or a list of points to which you would like to test the view. For integer options, choose from the following options: 0 - Horizontal Radial - The percentage of the 360 horizontal view band visible from each test point. Use this to study horizontal views from interior spaces to the outdoors. 1 - Horizontal 60 Degree Cone of Vision - The percentage of the 360 horizontal view band bounded on top and bottom by a 30 degree offset from the horizontal (derived from the human cone of vision). Use this to study views from interior spaces to the outdoors. Note that this will discount the _geometry from the calculation and only look at _context that blocks the scene. 2 - Spherical - The percentage of the sphere surrounding each of the test points that is not blocked by context geometry. Note that this will discount the _geometry from the calculation and only look at _context that blocks the scene. 3 - Skyview - The percentage of the sky that is visible from the input _geometry. viewPtsWeights [Optional]

A list of numbers that align with the test points to assign weights of importance to the several _viewTypeOrPoints that have been connected. Weighted values should be between 0 and 1 and should be closer to 1 if a certain point is more important. The default value for all points is 0, which means they all have an equal importance. This input could be useful in cases such as the radiative heater example where points on the human body with exposed skin could be weighted at a higher value. legendPar [Optional]

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]

Set to 'True' to bake the analysis results into the Rhino scene.

Outputs readMe!

View_Analysis

151

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


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

View_Analysis

152

Ladybug Primer A legend for the visibility analysis showing the percentage of visible points that correspond to the colors of the viewStudyMesh. Connect this output to a grasshopper "Geo" component in order to preview the legend separately in the Rhino scene. legendBasePt

The legend base point, which can be used to move the legend in relation to the view study mesh with the grasshopper "move" component. averageView

The average percentage of the _viewTypeOrPoints seen by all of the test _geometry. ptIsVisible

A grafted data stream for each _geometry test point with a "1" for each _viewPoint that is visible by the test point and a "0" for each _viewPoint that is blocked. Check Hydra Example Files for View Analysis

View_Analysis

153

Ladybug Primer

View From Sun

Use this component to open a new viewport in Rhino that shows the view from the sun. This is useful for understanding what parts of Rhino geometry are shaded at a particular hour of the day. -

Inputs sunVector [Required]

A sun vector from which the the Rhino view will be generated. Use the Ladybug sunPath component to generate sunVectors.

View_From_Sun

154

Ladybug Primer cenPt [Default]

The target point of the camera for the Rhino view that will be generated. This point should be close to Rhino geometry that you are interested in viewing from the sun. If no point is progived, the Rhino origin will be used (0,0,0). sunViewPt [Optional]

An optional point for the camera position (or sun position). Use this to move the camera closer to the geometry you would like to view if the initial view is too far away.. width [Optional]

An optional interger that represents the width (in pixels) of the Rhino viewport that will be generated. height [Optional]

An optional interger that represents the height (in pixels) of the Rhino viewport that will be generated. dispMode [Optional]

An optional text input for the display mode of the Rhino viewport that will be generated. For example: Wireframe, Shaded, Rendered, etc.

Outputs readMe!

... Check Hydra Example Files for View From Sun

View_From_Sun

155

Ladybug Primer

view Rose

Use this component to see the area visible from a given viewpoint across a 2D plane of vision. The component will create a circular surface in this plane of vision that is interrupted by context geometry to show the places that can be seen through this context geometry. -

Inputs context [Required]

Breps or Meshes representing context geometry that can block the view around a given viewPoint.

view_Rose

156

Ladybug Primer plane [Default]

Test Plane radius [Required]

A radius to make the view rose in Rhino model units. Note that, if the view rose is not extending past the _context geometry, you should increase this value.

Outputs readMe!

... viewRose

A surface representing the visible area from the viewpoint past the _context geometry. blocked

A set of curves representing the views blocked by the _context geometry from the viewpoint . visibleAngle

The total angle of visibility from the viewpoint in the plane of visibility. Check Hydra Example Files for view Rose

view_Rose

157

Ladybug Primer

Comfort Shade Benefit Evaluator

This is a component for visualizing the desirability of shade in terms of comfort temperature by using solar vectors, a series of hourly temperatures (usually outdoor temperatures), and an assumed balance temperature. The balance temperature represents the median temperture that people find comfortable, which can vary from climate to climate but is usually somewhere around 20C. Solar vectors for hours when the temperature is above the balance point contribute positively to shade desirability while solar vectors for hours when the temperature is below the balance point contribute negatively. The component outputs a colored mesh of the shade illustrating the net effect of shading each mesh face. A higher saturation of blue indicates that shading the cell is very desirable. A higher saturation of red indicates that shading the cell is harmful (blocking more winter sun than summer sun). Comfort_Shade_Benefit_Evaluator

158

Ladybug Primer Desaturated cells indicate that shading the cell will have relatively little effect on outdoor comfort or building performance. The units for shade desirability are net temperture degreedays helped per unit area of shade if the test cell is blue. If the test cell is red, the units are net heating degree-days harmed per unit area of shade. The method used by this component is based off of the Shaderade method developed by Christoph Reinhart, Jon Sargent, Jeffrey Niemasz. This component uses Shaderade's method for evaluating shade and window geometry in terms of solar vectors but substitutes Shaderade's energy simulation for an evaluation of heating and temperture degree-days about a balance temperature. A special thanks goes to them and their research. A paper detailing the Shaderade method is available at: http://www.gsd.harvard.edu/research/gsdsquare/Publications/Shaderade_BS2011.pdf The heating/temperture degree-day calculation used here works by first getting the percentage of sun blocked by the test cell for each hour of the year using the Shaderade method. Next, this percentage for each hour is multiplied by the temperature above or below the balance point for each hour to get a "degree-hour" for each hour of the year for a cell. Then, all the temperture-degree hours (above the balance point) and heating degree-hours (below the balance point) are summed to give the total heating or temperture degree-hours helped or harmed respectively. This number is divided by 24 hours of a day to give degree-days. These degree days are normalized by the area of the cell to make the metric consistent across cells of different area. Lastly, the negative heating degree-days are added to the positive temperture degree-days to give a net effect for the cell. -


The location output from the importEPW or constructLocation component. This is essentially a list of text summarizing a location on the earth. temperatures [Required]

A stream of 8760 temperature values (including a header) representing the temperature at each hour of the year that will be used to evaluate shade benefit. This can be the dryBulbTemperature from the 'Import EPW' component, the univeralThermalClimateIndex (UTCI) output from the 'Outdoor Comfort Calculator' component, or the standardEffectiveTemperature (SET) output from the 'PMV Comfort Calculator' component. If you are using this component to evaluate shade for a passive building with no heating/cooling, this input can also be the indoor temperature of the zone to be shaded. balanceTemperature [Optional]


159

Ladybug Primer An estimated balance temperature representing median temperture that people find comfortable, which can vary from climate to climate. The default is set to 17.5C, which is the median outdoor comfort temperature (UTCI) that defines the conditions of no thermal stress (9 < UTCI <26). temperatureOffest [Optional]

An number represeting the offset from the balanceTemperature_ in degrees Celcius at which point the shade importance begins to have an effect. The default is set to 8.5 C, which is the range of outdoor comfort temperature (UTCI) that defines the conditions of no thermal stress (9 < UTCI <26). testShades [Required]

A Brep representing the shade to be evaluated for its benefit. testRegion [Required]

A brep representing an outdoor area for which shading is being considered or the window of a building that would be affected by the shade. Note that only breps with a single surface are supported now and volumetric breps will be included at a later point. gridSize [Optional]

The length of each of the shade's test cells in model units. Please note that, as this value gets lower, simulation times will increase exponentially even though this will give a higher resolution of shade benefit. context [Optional]

Script variable ShadeBenefit north [Optional]

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


160

Ladybug Primer a resolution to produce a meaningful reault in all cases. delNonIntersect [Optional]

Set to "True" to delete mesh cells with no intersection with sun vectors. Mesh cells where shading will have little effect because an equal amount of warm and cool temperature vectors will still be left in white. 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. runIt [Required]

Set to 'True' to run the simulation.

Outputs readMe!

... sunVectors

The sun vectors that were used to evaluate the shade (note that these will increase as the sky desnity increases). regionTestPts

Points across the test region surface from which sun vectors will be projected shadeMesh

A colored mesh of the _testShades showing where shading is helpful (in satuated blue), harmful (in saturated red), or does not make much of a difference (white or desaturated colors). legend


161

Ladybug Primer Legend showing the numeric values of degree-days that correspond to the colors in the shade mesh. legendBasePoint

Script variable Shade Benefit shadeHelpfulness

The cumulative temperture degree-days/square Rhino model unit helped by shading the given cell. (C-day/m2)*if your model units are meters. shadeHarmfulness

The cumulative heating degree-days/square Rhino model unit harmed by shading the given cell. (C-day/m2)*if your model units are meters. Note that these values are all negative due to the fact that the shade is harmful. shadeNetEffect

The sum of the helpfulness and harmfulness for each cell. This will be negative if shading the cell has a net harmful effect and positive if the shade has a net helpful effect. Check Hydra Example Files for Comfort Shade Benefit Evaluator


162

Ladybug Primer

ShadingDesigner

Use this component to generate shading breps for any glazed surface or list of glazed surfaces. The component supports two methods for shading generation. The first is a simple depth method, which will generate an overhang of the speficied depth (or multiple overhangs if the _numOfShds is increased). The second method is to input a set of solar vectors from the Sunpath component that should be blocked by the shade. -

Inputs glzSrf [Required]

ShadingDesigner

163

Ladybug Primer A Surface or Brep representing a window to be used for shading design. This can also be a list of Surfaces of Breps. depthOrVector [Required]

A number representing the depth of the shade to be generated or a sun vector to be shaded from the glzSrf. You can also input lists of depths, which will assign different depths based on cardinal direction. For example, inputing 4 values f or depths will assign each value of the list as follows: item 0 = north depth, item 1 = west depth, item 2 = south depth, item 3 = east depth. Lists of vectors to be shaded can also be input and shades can be joined together with the mergeVectors input. numOfShds [Required]

The number of shades to generated for each glazed surface. distBetween [Required]

An alternate option to _numOfShds where the input here is the distance in Rhino units between each shade. runIt [Required]

Set to 'True' to run the component and generate shades. optionalShdSrf [Optional]

An optional shade surface representing a 2D area under consideration for shading. This input can only be used with the sun vector method. optionalPlanes [Optional]

An optional plane (or list of planes) representing a 2D area under consideration for shading. This input can only be used with the sun vector method. mergeVectors [Optional]

Set to 'True' to merge all the shades generated from a list of sun vectors into a single shade. This input can only be used with the sun vector method. horOrVertical [Default]

Set to 'True' to generate horizontal shades or 'False' to generate vertical shades. You can also input lists of horOrVertical input, which will assign different orientations based on cardinal direction.

ShadingDesigner

164

Ladybug Primer shdAngle [Default]

A number between -90 and 90 that represents an angle in degrees to rotate the shades. The default is set to '0' for no rotation. If you have vertical shades, use this to rotate them towards the South by a certain value in degrees. If applied to windows facing East or West, tilting the shades like this will let in more winter sun than summer sun. If you have horizontal shades, use this input to angle shades downward. You can also put in lists of angles to assign different shade angles to different cardinal directions. north [Optional]

Input a vector to be used as a true North direction or a number between 0 and 360 that represents the degrees off from the y-axis to make North. The default North direction is set to the Y-axis (0 degrees).

Outputs readMe!

... shadingSrfs

Shading surfaces that were generated based on the inputs. Check Hydra Example Files for ShadingDesigner

ShadingDesigner

165

Ladybug Primer

SolarEnvelope

Use this component to generate a solar envelope for a given test surface, set of solar vectors, and context geometry that you want to ensure solar access to. Solar envelopes are typically used to illustrate the volume that can be built within in order to ensure that a new development does not shade the surrounding properties for a given set of sun vectors. -

Inputs baseSrf [Required]

A surface representing the area for which you want to create the solar envelope.

SolarEnvelope

166

Ladybug Primer obstacleCrvs [Required]

List of curves indicating the top borders of our surroundings that are taken into account in calculating the solar collection. 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.

SolarEnvelope

167

Ladybug Primer envelopeBrep

The closed volume in which you can build above which the building will have direct solar access to the input sunVectors. Check Hydra Example Files for SolarEnvelope

SolarEnvelope

168

Ladybug Primer

SolarFan

Use this component to generate a solar fan for a given test surface and set of solar vectors. Solar fans essentially illustrate the volume that should be clear of shading in order to provide solar access to a test surface for a given set of sun vectors. Solar fans are typically used to ensure solar access for park vegetation in the midst of large developments constructed around it. It can be also used to ensure solar access for windows that might want to use the sun for heating for ceratin hours of the year. -


SolarFan

169

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

Outputs readMe!

... solarFan

Brep representing a solar fan that should be clear of shading in order to ensure solar access to the _baseSrf for the given _sunVectors. Check Hydra Example Files for SolarFan

SolarFan

170

Ladybug Primer

DC to AC derate factor

Use this component to calculate overall DC to AC derate factor for Photovoltaics Surface's "DCtoACderateFactor_" input. Overall DC to AC derate factor corresponds to various locations and instances in a PV system where power is lost from DC system nameplate to AC power. - Component first calculates PVWatts v5 Total losses, then converts them to PVWatts v1 overall DC to AC derate factor. Based on PVWatts v5 Manual: http://www.nrel.gov/docs/fy14osti/62641.pdf - If nothing supplied to the inputs, default value of 0.85 will be used. -

Inputs


171

Ladybug Primer annualShading [Optional]

Losses due to buildings, structures, trees, mountains or other objects that prevent solar radiation from reaching the cells. Input range: 0 to 100(%), 0 being unshaded, and 100 being totally shaded PV module. - If not supplied default value of 0(%) will be used. age [Optional]

Losses over time due to weathering of the PV modules. The loss in performance is typically 1% per year. Example: for the 20th year of operation, an age loss of 19% would be appropriate. Input range: 0 (new module) to 100%(theoretically: 101 year old module) - If not supplied default value of 0(%) will be used. snow [Optional]

Losses due to snow covering the array. The default value is zero, assuming either that there is never snow on the array, or that the array is kept clear of snow. Input range: 0 (there is never snow on the array, or the array is kept clear of snow) to 100%(an array is theoretically always covered with snow) - If not supplied default value of 0(%) will be used. wiring [Optional]

Resistive losses in the DC and AC wires connecting modules, inverters, and other parts of the system. Input range: 0 to 100(%) - If not supplied default value of 2(%) will be used. soiling [Optional]

Losses due to dust, dirt, leaves, other wildlife droppings, snow, and other foreign matter on the surface of the PV module that prevent solar radiation from reaching the cells. Soiling is location- and weather-dependent. There are greater soiling losses in hightraffic, high-pollution areas with infrequent rain. Input range: 0 to 100(%) - If not supplied default value of 2(%) will be used. mismatch [Optional]

Electrical losses due to slight differences caused by manufacturing imperfections between modules in the array that cause the modules to have slightly different currentvoltage characteristics. Input range: 0 to 100(%) - If not supplied default value of 2(%) will be used. availability [Optional]

Losses due to scheduled and unscheduled system shutdown for maintenance, grid DC_to_AC_derate_factor

172

Ladybug Primer outages, and other operational factors. Input range: 0 to 100% - If not supplied default value of 3(%) will be used. connections [Optional]

Resistive losses in electrical connectors in the system. Input range 0 to 100(%) - If not supplied default value of 0.5(%) will be used. nameplateRating [Optional]

Losses due to accuracy of the manufacturer's nameplate rating. Field measurements of the electrical characteristics of photovoltaic modules in the array may show that they differ from their nameplate rating. Example: a nameplate rating loss of 5% indicates that testing yielded power measurements at STC that were 5% less than the manufacturer's nameplate rating. Input range 0 to 100(%) - If not supplied default value of 1(%) will be used. lightInducedDegradation [Optional]

Effect of the reduction in the array's power during the first few months of its operation caused by light-induced degradation of photovoltaic cells. Input range 0 to 100(%) - If not supplied default value of 1.5(%) will be used.

Outputs readMe!

... totalLosses

PVWatts v5 representation of DCtoACderateFactor factor. In percent (%). DCtoACderateFactor

Factor which accounts for various locations and instances in a PV system where power is lost from DC system nameplate to AC power. Unitless. Check Hydra Example Files for DC to AC derate factor


173

Ladybug Primer

Photovoltaics Performance Metrics

Use this component to calculate various Photovoltaics performance metrics -

Inputs PVsurface [Required]

Input planar Grasshopper/Rhino Surface (not a polysurface) on which the PV modules will be applied. If you have a polysurface, explode it (using "Deconstruct Brep" component) and then feed its Faces(F) output to _PVsurface. Surface normal should be faced towards the sun.


174

Ladybug Primer Or create the Surface based on initial PV system size by using "PV SWH system size" component. PVsurfacePercent [Optional]

The percentage of surface which will be used for PV modules (range 0-100). - Some countries and states, have local codes which limit the portion of the roof, which can be covered by crystalline silicon modules. For example, this may include having setbacks(distances) of approximatelly 90cm from side and top edges of a roof, as a fire safety regulation. - If not supplied, default value of 100 (all surface area will be covered in PV modules) is used. PVmoduleSettings [Optional]

Script variable PhotovoltaicsPerformanceMetrics ACenergyPerHour [Required]

Import "ACenergyPerYear" output data from "Photovoltaics surface" component. In kWh. totalRadiationPerHour [Required]

Import "totalRadiationPerHour" output data from "Photovoltaics surface" component. In kWh/m2. cellTemperaturePerHour [Required]

Import "cellTemperaturePerHour" output data from "Photovoltaics surface" component. In °C. ACenergyDemandPerHour [Optional]

Required electrical energy used for any kind of load: heating, cooling, electric lights, solar water heating circulation pump etc. For example, any of the Honeybee's "Read EP Result" outputs can be inputted in here. Either separately or summed. - If nothing inputted, this input will be neglected (there is no required electrical energy). In kWh. energyCostPerKWh [Optional]

The cost of one kilowatt hour in any currency unit (dollar, euro, yuan...) - If not supplied, 0.15 $/kWh will be used as default value. embodiedEnergyPerM2 [Optional]

Energy necessary for an entire product life-cycle of PV module per square meter. In Photovoltaics_Performance_Metrics

175

Ladybug Primer MJ/m2 (megajoules per square meter). - If not supplied default value of 4410 (MJ/m2) will be used. embodiedCO2PerM2 [Optional]

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

Life expectancy of a PV module. In years. - If not supplied default value of 30 (years) will be used. gridEfficiency [Optional]

An average primary energy to electricity conversion efficiency. - If not supplied default value of 29 (%) will be used. optimal [Optional]

Set to "True" to calculate optimal PVsurface area. An optimal PVsurface area will cover 100% of the of the annual electricity load ("ACenergyDemandPerHour_"). runIt [Required]

...

Outputs readMe!

... optimalSystemSize

Optimal PV system size (optimal total size of the PV array) for a given PVsurface's tilt, array and "ACenergyDemandPerHour ". Minimum system size is 0.01 kW. Input it to "systemSize" input of "PV SWH system size" component to see how much area it would require. - To calculate it, set the "optimal_" input to "True". - In thermal kiloWatts (kWt). CUFperYear

Capacity Utilization Factor (or Capacity Factor or sometimes evan called Plant Load Factor (PLF)) - ratio of the annual AC power output and maximum possible output under ideal conditions if the sun shone throughout the day and throughout the year. It is Photovoltaics_Performance_Metrics

176

Ladybug Primer sometimes used by investors or developers for Financial and Maintenance analysis of the PV systems, instead of "basicPRperYear". - In percent (%). basicPRperYear

Basic Performance Ratio - ratio of the actual and theoretically possible annual energy output. It is worldwide accepted standard metric for measuring the performance of the PV system, therefor it is used for Maintenance analysis of PV systems. Used for Maintenance analysis of PV systems. - basicPR is more precise than upper "CUF" and should be used instead of it, unless "CUF" is specifically required. - In percent(%). temperatureCorrectedPRperMonth

Temperature corrected Performance Ratio - ratio of the actual and theoretically possible energy output for each month during a year, corrected for PV module's Cell temperature. Mid-day hours (solarRadiation > 0.6 kWh/m2) only taken into account. Used for Maintenance analysis of PV systems. - In percent(%). temperatureCorrectedPRperYear

Temperature corrected Performance Ratio - ratio of the actual and theoretically possible annual energy output, corrected for PV module's Cell temperature. Mid-day hours (solarRadiation > 0.6 kWh/m2) only taken into account. Used for Maintenance analysis of PV systems. - It is more precise than upper "basicPR" and should be used instead of it, unless "basicPR" is specifically required. - In percent(%). energyOffsetPerMonth

Percentage of the electricity demand covered by Photovoltaics system for each month during a year. - It is used for Financial and Maintenance analysis of the PV system. - In percent(%). energyOffsetPerYear

Percentage of the total annual electricity demand covered by Photovoltaics system for a whole year. - It is used for Financial and Maintenance analysis of the PV system. - In percent(%). energyValue

Total Energy value for the whole year in currency unit (dollars, euros, yuans...) - It is used for Financial analysis of the PV system. Yield


177

Ladybug Primer Ratio of annual AC power output and nameplate DC power rating. It is used for Financial analysis of the PV systems. - In hours (h). EROI

Energy Return On Investment - a comparison of the generated electricity to the amount of primary energy used throughout the PV module's product life-cycle. - It is used for Financial analysis of the PV system. - Unitless. embodiedEnergy

Total energy necessary for an entire product life-cycle of PV modules. - It used for the Life Cycle analysis of the PV system. - In GJ (gigajoules). embodiedCO2

Total carbon emissions produced during PV module's life-cycle. - It used for the Life Cycle analysis of the PV system. - In tCO2 (tons of CO2). CO2emissionRate

An index which shows how effective a PV system is in terms of global warming. It is used in comparison with other fuels and technologies (Hydroelectricity(15), Wind(21), Nuclear(60), Geothermal power(91), Natural gas(577), Oil(893), Coal(955) ...) - It is part of the Life Cycle analysis of the PV system. - In gCO2/kWh. EPBT

Energy PayBack Time - time it takes for PV modules to produce all the energy used through-out its product life-cycle. After that period, they start producing zero-emissions energy. - It is used for Life Cycle analysis of the PV system. - In years. Check Hydra Example Files for Photovoltaics Performance Metrics


178

Ladybug Primer

Photovoltaics Surface

Use this component to calculate amount of electrical energy that can be produced by a surface if a certain percentage of it is covered with Photovoltaics. Component based on NREL PVWatts v1 fixed tilt calculator for crystalline silicon (c-Si) photovoltaics. - Sources: http://www.nrel.gov/docs/fy14osti/60272.pdf https://pvpmc.sandia.gov -


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


179

Ladybug Primer STAT Weather Files" component. PVsurface [Required]

Input planar Grasshopper/Rhino Surface (not a polysurface) on which the PV modules will be applied. If you have a polysurface, explode it (using "Deconstruct Brep" component) and then feed its Faces(F) output to _PVsurface. Surface normal should be faced towards the sun. Or create the Surface based on initial PV system size by using "PV SWH system size" component. PVsurfacePercent [Optional]

The percentage of surface which will be used for PV modules (range 0-100). - Some countries and states, have local codes which limit the portion of the roof, which can be covered by crystalline silicon modules. For example, this may include having setbacks(distances) of approximatelly 90cm from side and top edges of a roof, as a fire safety regulation. - If not supplied, default value of 100 (all surface area will be covered in PV modules) is used. - In percent (%). DCtoACderateFactor [Optional]

Factor which accounts for various locations and instances in a PV system where power is lost from DC system nameplate to AC power. It ranges from 0 to 1. It can be calculated with Ladybug's "DC to AC derate factor" component. - If not supplied, default value of 0.85 will be used. PVmoduleSettings [Optional]

A list of PV module settings. Use the "Photovoltaics module" component to generate them. - If not supplied, the following PV module settings will be used by default: moduleType: Close (flush) roof mount moduleEfficiency: 15 % temperatureCoefficient: -0.5 %/°C moduleActiveAreaPercent: 90 % north [Optional]

Input a vector to be used as a true North direction, or a number between 0 and 360 that represents the clockwise degrees off from the Y-axis. - If not supplied, default North direction will be set to the Y-axis (0 degrees). albedo [Optional]


180

Ladybug Primer A list of 8767 (with header) or 8760 (without the header) albedo values for each hour during a year. Albedo (or Reflection coefficient) is an average ratio of the global incident solar radiation reflected from the area surrounding the PV surface. It ranges from 0 to 1. - It depends on the time of the year/day, surface type, temperature, vegetation, presence of water, ice and snow etc. - If no list supplied, default value of 0.20 will be used, corrected(increased) for the presence of snow (if any). - Unitless. 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="" to="" of="" lists="" (in="" their="" respective="" order):="" "a"="" always="" represents="" 1st="" list,="" "b"="" 2nd="" etc.="" -="" For="" example,="" if="" you="" have="" an="" dryBulbTemperature="" connected="" first="" windSpeed="" second="" list="" (both="" annualHourlyData_="" input),="" want="" plot="" data="" for="" time="" period="" when="" temperature="" is="" between="" 18°C="" 23°C,="" larger="" than="" 3m="" s,="" written="" "183" (without the quotation marks). runIt [Required]

...

Outputs readMe!

... ACenergyPerHour

AC power output for each hour during a year. - In kWh. ACenergyPerYear


181

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

An average AC power output per day for a whole year. - In kWh/day. DCenergyPerHour

DC power output of the PV array for each hour during a year. - In kWh. totalRadiationPerHour

Total Incident POA (Plane of array) irradiance for each hour during a year. - In kWh/m2. moduleTemperaturePerHour

Module's back surface temperature for each hour during year. - In °C. cellTemperaturePerHour

Cell temperature for each hour during year. - In °C. PVsurfaceTiltAngle

The angle from horizontal of the inclination of the PVsurface. Example: 0 = horizontal, 90 = vertical. It ranges from 0-180. - In degrees. PVsurfaceAzimuthAngle

The orientation angle (clockwise from the true north) of the PVsurface normal vector. It ranges from 0-360. - In degrees. systemSize

DC rating of the PV system. - In kW. Check Hydra Example Files for Photovoltaics Surface


182

Ladybug Primer

Sunpath Shading

This component calculates the shading of: Photovoltaic modules Solar Water Heating collectors any other purpose (shading of points) - Use "annualShading", "Sep21toMar21Shading" and "Mar21toSep21Shading" outputs for Photovoltaic modules shading. Use "beamIndexPerHour" and "skyViewFactor" outputs for Solar Water Heating collectors shading, or any other purpose. - "annualShading" output is based on "Using sun path charts to estimate the effects of shading on PV arrays", University of Oregon, Frank Vignola:

Sunpath_Shading

183

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


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. Leafless being a period from 21st September to 21st March in the northern hemisphere, and from 21st March to 21st September in the in the southern hemisphere. - Input polysurfaces, surfaces, or meshes. coniferousAllyearIndex [Optional]

All year round transmission index for coniferous(evergreen) context trees. It ranges from

Sunpath_Shading

184

Ladybug Primer 0 to 1.0. 0 represents deciduous trees which do not allow solar radiation to pass through them (100% shading). 1 represents all solar radiation passing through deciduous trees, like the trees do not exist (0% shading). - If not supplied default value of 0.30 (equals 70% shading) will be used. - Unitless. deciduousInleafIndex [Optional]

Deciduous context trees transmission index for in-leaf period. In-leaf being a period from 21st March to 21st September in the northern hemisphere, and from 21st September to 21st March in the southern hemisphere. It ranges from 0 to 1.0. 0 represents deciduous trees which do not allow solar radiation to pass through them (100% shading). 1 represents all solar radiation passing through deciduous trees, like the trees do not exist (0% shading). - If not supplied default value of 0.23 (equals 77% shading) will be used. - Unitless. deciduousLeaflessIndex [Optional]

Deciduous context trees transmission index for leaf-less period. Leaf-less being a period from 21st September to 21st March in the northern hemisphere, and from 21st March to 21st September in the in the southern hemisphere. It ranges from 0 to 1.0. 0 represents deciduous trees which do not allow solar radiation to pass through them (100% shading). 1 represents all solar radiation passing through deciduous trees, like the trees do not exist (0% shading). - If not supplied default value of 0.64 (equals 36% shading) will be used. - Unitless. leaflessPeriod [Optional]

Define the leafless period for deciduous trees using Ladybug's "Analysis Period" component. IMPORTANT! This input affects only the skyViewFactor, beamIndexPerHour, shadedSolarRadiationPerHour output. Due to limitations of the used sunpath diagram, it does not affect the Sep21toMar21Shading, Mar21toSep21Shading, annualShading outputs, where default leafless periods (see the line bellow) will always be used. - If not supplied the following default periods will be used: from 21st September to 21st March in the northern hemisphere, and from 21st March to 21st September in the in the southern hemisphere. ACenergyPerHour [Optional]

This input is necessaty only if you are calculating the shading of the PV modules. If that is so, input the "ACenergyPerHour" output data from "Photovoltaics surface" component. - If you are calculating shading analysis for "Solar water heating surface" component (instead of "Photovoltaics surface" component), leave this input empty. - If you are calculating shading analysis for any other purpose (of point(s) for example)

Sunpath_Shading

185

Ladybug Primer leave this input empty too. north [Optional]


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 2 will be used. legendPar [Optional]

Sunpath_Shading

186

Ladybug Primer Optional legend parameters from the Ladybug "Legend Parameters" component. bakeIt [Optional]

Set to "True" to bake the Sunpath shading results into the Rhino scene. - If not supplied default value "False" will be used. runIt [Required]

...

Outputs readMe!

... skyViewFactor

Continuous Sky View Factor - portion of the visible sky (dome). It defines the shading of the parts of diffuse irradiance. It ranges from 0 to 1. 0 means that the sky dome is competely obstructed by obstacles and all incoming diffuse sky irradiance is blocked (100% shading). 1 means that sky dome is competely free of obstacles (0% shading). This output is similar to "skyView" output of Ladybug's "Shading Mask" component. Unlike "skyView" it takes into account transparency of trees. But it does not visually present the shading, which is what "Shading Mask" component does. - Use it as an input for Ladybug "Solar Water Heating System" or "Solar Water Heating System Detailed" component's "skyViewFactor_" input to account for diffuse irradiance shading of SWHsurface. - Unitless. beamIndexPerHour

Transmission index of beam (direct) irradiance for each hour during a year. It ranges from 0-1. Transmission index of 0 means 100% shading. Transmission index of 1 means 0% shading. It is calculated for each analysisGeometry vertex and then averaged. - Use it as an input for Ladybug "Solar Water Heating System" or "Solar Water Heating System Detailed" component's "beamIndexPerHour_" input to account for diffuse direct beam shading of SWH surface. - Unitless. shadedSolarRadiationPerHour

Total shaded incidence for each hour during a year. - In kW/m2. Sep21toMar21Shading

Sunpath_Shading

187

Ladybug Primer Weighted shading 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. energy. It is calculated for each each analysisGeometry analysisGeometry vertex and then averaged. averaged. It ranges from 0-100(%). - In percent(%). Mar21toSep21Shading

Weighted shading 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. energy. It is calculated for each analysisGeometry vertex and then averaged. It ranges from 0-100(%). - In percent(%). annualShading

Annual weighted weighted shading of of the active sun window window quadrants. To To calculate it, input input the hourly data to "ACenergyPerHour "ACenergyPerHour " input. Active sun window quadrants are only those which produce AC energy. 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 _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" "sunWindowCrvs" and "sunWindowMesh" geometry around in the Rhino scene with the grasshopper's "Move" component. - Connect this output to a Grasshopper's "Point" parameter in order to preview the "annalysisPts" geometry in the Rhino scene. sunWindowCrvs

Geometry of the sun window based on 3D polar sun path diagram. Perpendical curves represent solar time hours. Horizontal arc curves represent sun paths for: 21st December, 21st November/January, 21st October/February, 21st September/March, 21st August/April, 21st July/May, 21st June. The whole sunWindowCrvs geometry output is calculated for analysisGeometry area centroid. sunWindowMesh

Sunpath_Shading

188

Ladybug Primer Sun window mesh based on 3D polar sun path diagram. It is calculated for analysisGeometry 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. sunWindowMesh. Connect Connect this output to a Grasshopper's 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 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 percent per each sun window window active quadrant quadrant above the horizon. horizon. - Use grasshopper's "Text tag" component to visualize them. hoursPositions

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

Solar time hour strings. - Use grasshopper's "Text "Text tag" component to visualize them. Check Hydra Example Files for Sunpath Shading

Sunpath_Shading

189

Ladybug Primer

Tilt And Orientation Factor

This component calculates the Optimal Tilt, Optimal Orientation and TOF (Tilt and Orientation Factor) for PV modules or Solar water heating collectors. TOF is a solar radiation at the actual tilt and orientation divided by the solar radiation at the optimum tilt and orientation. -


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


190

Ladybug Primer STAT Weather Files" component. PV_SWHsurface [Required]

Input planar Grasshopper/Rhino Surface (not a polysurface) on which the PV modules/SWH collectors 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. collector. - If not supplied default value of 0(%) will be used. north [Optional]


A list of 8767 (with header) header) or 8760 (without (without the header) albedo albedo values for each hour 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, water, ice and snow etc. - If no list supplied, default value of 0.20 will be used, corrected(increased) 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. - CAUTION!!! Precision numbers (10 >) require stronger performance PCs. If your PC is somewhat "weaker", the precision of < 10 will be just fine. - If not supplied, default value of 2 will be used. scale [Optional]


191

Ladybug Primer Scale of the overall geometry. - If not supplied, default value of 1 will be used. origin [Optional]

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

Optional legend parameters from the Ladybug "Legend Parameters" component. bakeIt [Optional]

Set to "True" to bake the Tilt and orientation factor results into the Rhino scene. - If not supplied default value "False" will be used. runIt [Required]

...

Outputs readMe!

... TOF

Tilt 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 Washington require TSRF to be minimum 75% in order for the PV system to be applicable for incentive programs. - In percent(%). PVsurfaceTilt

Tilt Tilt angle of the inputted PV_SWHsurface. In degrees (°). PVsurfaceAzimuth


192

Ladybug Primer Orientation angle of the inputted PV_SWHsurface. In degrees (°). optimalTilt

Optimal tilt of the PV_SWHsurface for a given location. Optimal tilt being the one that receives the most annual solar radiation. In degrees (°). optimalAzimuth

Optimal orientation of the PV_SWHsurface for a given location. Optimal azimuth being the one that receives the most annual solar radiation. In degrees (°). optimalRoofPitch

Optimal steepness of the PV_SWHsurface for a given location. Optimal steepness being the one that receives the most annual solar radiation. In inches/inches optimalRadiation

Total solar radiation per square meter for a whole year received on a PV_SWHsurface of optimal tilt and azimuth, at given location. In kWh/m2 geometry

Geometry of the whole TOF mesh chart. Connect this output to a Grasshopper's "Geo" parameter in order to preview the "geometry" separately in the Rhino scene. originPt

The origin point of the "geometry" output. Use this point to move "geometry" output around in the Rhino scene with the grasshopper's "Move" component. analysisPt

A point indicating indicating inputted PV_SWHsurface's PV_SWHsurface's Tilt/Azimuth Tilt/Azimuth position position on the solar radiation radiation table. legend

A legend for the annual annual total solar radiation radiation (in kWh/m2). Connect 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. Tilt_And_Orientation_Factor

193

Ladybug Primer Check Hydra Example Files for Tilt And Orientation Factor


194

Ladybug Primer

Forward Raytracing

Use this component to get a sense of how sunlight is reflected by a set of context geometries by tracing sun rays forwards through this geometry. Examples where this component might be useful include the evaluation of the diffusion of light by a light shelf, or testing to see whether a parabolic building geometry (like a Ghery building) might focus sunlight to dangerous levels at certain times of the year. Note that this component assumes that all sun light is reflected off of these geometries specularly (as if they were a mirror) and, for more detailed raytrace analysis, the Honeybee daylight components should be used. -

Inputs

Forward_Raytracing

195

Ladybug Primer startPts [Required]

Points from which the sun rays will be cast towards the _context geometry. You may want to connect a grid of points here to mimic the fact that direct sun will be streaming evenly from the sky. startVectors [Required]

A sun vector from the sunPath component or a list of sun vectors to be forward raytraced. context [Required]

Breps or meshes of conext geometry that will reflect the sun rays. Note that, for curved surfaces, smooth meshes of the geometry will be more accurate than inputing a Brep. numOfBounce [Default]

An interger representing the number of ray bounces to trace the sun rays forward. lastBounceLen [Default]

A float number representing the length in Rhino model units of the light ray after the last bounce.

Outputs rays

A series of line curves representing light rays traced forward through the geometry. Check Hydra Example Files for Forward Raytracing

Forward_Raytracing

196

Ladybug Primer

SolarEnvelopeBasic

Use this component to generate a solar envelope for a closed boundary curve with minimum inputs. This component predefines monthly and hourly ranges in order to simplify the creation of useful envelope geometry. The solar envelope is used to ensure that its adjacent neighbors (defined as anything outside of the chosen boundary curve) will receive a specified minimum hours of direct solar access for each day in a specified month range of the year. Any geometry built within the solar envelope boundaries will therefore not cast any shadow on adjacent property for the given hour and month range. The start and end dates that determine the month range for solar access can be chosen from the following options: 0) Mar 21 - Jun 21 1) Mar 21 - Sep 21 2) Mar 21 - Dec 21 3) Jun 21 - Sep 21 4) Jun 21 - Dec 21 5) Sep 21 - Dec 21 The default SolarEnvelopeBasic

197

Ladybug Primer set to 4) June 21 to December 21. Reference: Niemasz, J., Sargent, J., Reinhart D.F., "Solar Zoning and Energy in Detached Residential Dwellings," Proceedings of SIMAUD 2011, Boston, April 2011. -

Inputs boundary [Required]

A closed boundary curve representing a piece of land (such as a property to be developed) for which solar access of the surrounding land is desired. location [Required]

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 SolarEnvelopeBasic

198

Ladybug Primer Where, in the North/South Hemispheres, these dates repsectively signify: Mar 21 = Vernal/Autumnal Equinox Jun 21 = Summer/Winter Solstice Sep 21 = Autumnal/Vernal Equinox Dec 21 = Winter/Summer Solstice

Outputs readMe!

... solarEnvelope

A Brep representing a solar envelope. This volume should be built within in order to ensure that the surrounding property is not shaded for the given number of hours. Check Hydra Example Files for SolarEnvelopeBasic

SolarEnvelopeBasic

199

Ladybug Primer

SolarFanBasic

Use this component to generate a solar fan with minimumal input data. This component predefines monthly and hourly ranges in order to simplify the creation of useful fan geometry. The solar fan is used to ensure that a given property within a boundary curve is guarenteed a specified minimum hours of direct solar access for each day in a specified month range of the year. Thus, context geometries surrounding this boundary curve that do not penetrate the solar fan will not cast shadows onto the boundary area for the specified hour and month range. The start and end dates that determine the month range for solar access can be chosen from the following options: 0) Mar 21 - Jun 21 1) Mar 21 - Sep 21 2) Mar 21 - Dec 21

SolarFanBasic

200

Ladybug Primer 3) Jun 21 - Sep 21 4) Jun 21 - Dec 21 5) Sep 21 - Dec 21 The default set to 3) June 21 to September 21. Note that extremely complicated concave shapes will take a long time to calculate a solar fan for. -

Inputs boundary [Required]

closed boundary curve representing a piece of land (such as a park) or a window for which solar access is desired. location [Required]

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 =

SolarFanBasic

201

Ladybug Primer Jun 21 - Dec 21

5 = Sep 21 - Dec 21 Where, in the North/South Hemispheres, these dates repsectively signify: Mar 21 = Vernal/Autumnal Equinox Jun 21 = Summer/Winter Solstice Sep 21 = Autumnal/Vernal Equinox Dec 21 = Winter/Summer Solstice

Outputs out

... solarFan

Brep representing a solar fan. This volume should be clear of shading in order to ensure solar access to the area inside the boundary curve for the given number of hours. Check Hydra Example Files for SolarFanBasic

SolarFanBasic

202

Ladybug Primer

Component list: Mesh-To-Hatch North Recolor_Mesh True_North Adaptive_Comfort_ Parameters Body_Characteristics Gradient_Library Legend_ Parameters PMV_Comfort_Parameters Passive_Strategy_List Real_Time_Radiation_Analysis Capture_View Orient _to_Camera Set_the_View fly C2F DOY_ HOY Day_Month_Hour F2C Activities_Met_List BTU2Wh CombineSolarEnvelopes Comfort_Mannequin Construct_Time Create_Legend L2G Orientation_Study_Parameters Passive_Strategy_Parameters Shading_Parameters_List Wh2BTU

4 | Extra

203

Ladybug Primer

Wh2kWh kWh2Wh ms2mph rIP2rSI uIP2uSI

4 | Extra

204

Ladybug Primer

Mesh-To-Hatch

Use this component to bake a clored mesh into the Rhino scene as a series of colored hatches. This is particularly useful if you are trying to export ladybug graphics from Rhino to vector-based programs like Inkscape or Illustrator. -

Inputs mesh [Required]

A colored mesh (or list of colored meshes) that you would like to bake into the Rhino scene as a series of colored hatches.

Mesh-To-Hatch

205

Ladybug Primer runIt [Required]

Set to 'True' to run to run the component and bake the mesh into the scene as a series of hatches.

Outputs readMe!

... Check Hydra Example Files for Mesh-To-Hatch

Mesh-To-Hatch

206

Ladybug Primer

North

Use this component to create a compass sign that indicates the direction of North in the Rhino scene. -

Inputs north [Default]

Input a vector to be used as a North direction or a number between 0 and 360 that represents the degrees off from the y-axis to make North. The default North direction is set to the Y-axis (0 degrees).

North

207

Ladybug Primer centerPt [Default]

Input a point here to change the location of the North sign in the Rhino scene. The default is set to the Rhino model origin (0,0,0). scale [Default]

Input a number here to change the scale of the sun path. The default is set to 1.

Outputs northSign

A set of surfaces and curves that indicate the direction of North in Rhino. Check Hydra Example Files for North

North

208

Ladybug Primer

Recolor Mesh

Use this component to re-color a mesh with new a numerical data set whose length corresponds to the number of faces in the _inputMesh. This component is useful if you have post-processed any of the numerical data out of the Ladybug components using Grasshopper math components. It is also necessary to view results from the Ladybug Real Time Radiation Analysis. -

Inputs analysisResult [Required]

Recolor_Mesh

209

Ladybug Primer A numerical data set whose length corresponds to the number of faces in the _inputMesh. This data will be used to re-color the _inputMesh. inputMesh [Required]

An already-colored mesh from one of the Ladybug components which you would like to re-color based on data in the _analysisResult. heightDomain [Optional]

Optional height domain to create a 3D mesh result. Use Construct Domain component to create a domain 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]

Set to "True" to bake the resulting mesh and legend into the Rhino scene. layerName [Optional]

If bakeIt_ is set to "True", input Text here corresponding to the Rhino layer onto which the resulting mesh and legend should be baked.

Outputs readMe!

... newMesh

Recolor_Mesh

210

Ladybug Primer A new mesh that has been re-colored based on the _analysisResult data. newLegend

A new legend that that corresponds to the colors of the newMesh. Connect this output to a grasshopper "Geo" component in order to preview this legend separately in the Rhino scene. legendBasePt

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

Script variable reColorMesh legendColors

Script variable reColorMesh Check Hydra Example Files for Recolor Mesh

Recolor_Mesh

211

Ladybug Primer

True North

Use this component to calculate Earth's true north from magnetic north. - If you are working with location plan generated by Google Maps or any other web mapping service, North will always be positioned in direction of Rhino's Y axis. In case you imported a location plan to Rhino, which has a North direction assigned in a form of magnetic North, then you need to correct that North direction for the influence of Earth's magnetic variation. Which is what this component does. - All credit goes to Christopher Weiss ([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 -

True_North

212

Ladybug Primer


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

213

Ladybug Primer magneticFieldVec

Earth's magnetic field vector at chosen location. Vector's intensity represents the strength in nanoTeslas (nT). Check Hydra Example Files for True North

True_North

214

Ladybug Primer

Adaptive Comfort Parameters

Use this component to set Adaptive comfort parameters for the Adaptive Comfort Calculator or the Adaptive Comfort Chart. Parameters include the ability to use either US (ASHRAE) or European (EN) standards as well as set the acceptability threshold for the percent of the occupants that are comfortable

This component also includes the ability to set a custom correlation between outdoor temperature and indoor desired temperature using a 'levelOfConditioning' variable and research that is not an official part of the ASHRAE or EN standards but is endorsed by many of the scientists who helped create these standards. Detailed information on all of these parameters is described in this (which varies for different building types between the two standards).

book: Fergus Nicol, Michael Humphreys, Susan Roaf. Adaptive Thermal Comfort: Principles

Adaptive_Comfort_Parameters

215

Ladybug Primer and Practice. Routledge, 2012. ( https://books.google.com/books? id=vE7FBQAAQBAJ&dq=adaptive+thermal+comfort ) Users are also encouraged to use the

'Ladybug_Adaptive Comfort Chart' component or the Center for the Built Environment's (CBE) comfort tool to help visualize the differences between these parameters: Special thanks goes to the authors of the online CBE Thermal Comfort Tool who first coded the avascript: Hoyt Tyler, Schiavon Stefano, Piccioli Alberto, Moon Dustin, and Steinfeld Kyle. http://cbe.berkeley.edu/comforttool/ -

Inputs ASHRAEorEN [Optional]

Set to 'True' to have the Adpative components use the US (ASHRAE 55 2013) adaptive standard and set to 'False' to have the Adaptive components use the European (EN15251) standard. The default is set to use the US (ASHRAE 55 2013) standard. Note that changing the standard will also change some of the inputs below. The ASHRAE standard will use the average monthly temperature by default and the European standard will use a running mean temperature by default. Also, the European standard uses building classes instead of 80 / 90 percent acceptability. eightyOrNinetyComf [Optional]

Set to 'True' to have the comfort standard be 80 percent of occupants comfortable and set to 'False' to have the comfort standard be 90 percent of all occupants comfortable. The default is set to 'False' for 90 percent, which is what most members of the building industry seem to aim for in today's world. However some projects will occasionally use 80% as this was originally the benchmark that engineers set around the dawn of air conditioning. avgMonthOrRunMean [Optional]

Set to 'True' to have the Adpative components compute the prevailing outdoor temperature from the average monthly temperature (the official method used by the US's ASHRAE 55 2013) and set to 'False' compute the prevailing outdoor temperature from a weighted running mean of the last week (the official method used by Europe's EN-15251). The default is set to align with the chosen comfort standard above (either ASHRAE 55 2013 or EN-15251) but this option is included to allow users to explore differences and variations between the two standards. levelOfConditioning [Optional]

An optional number between 0 and 1 that represents how 'air conditioned' a space is. By default, this value is always set to 0 because both the ASHRAE 55 2013 and EN Adaptive_Comfort_Parameters

216

Ladybug Primer 15251 standards are strictly meant to be used for buildings without any installed air conditioning whatsoever. However, the researchers who developed the original Adaptive models also surveyed many people in conditioned buildings to show that the adaptive model did not contradict the PMV model when it was applied to buildings that resembled the conditioned climate chamber used to validate the PMV model. From these surveys of fully-conditioned buildings, researchers produced a correlation between prevailing outdoor temperature and desired indoor temperature that had a much shallower slope than that for fully naturally-ventilated buildings. This input allows you to use this fully conditioned correlation (by setting this input to 1) or create any custom correlation in between these two (arguably representative of mixed-mode or hybrid AC/naturally

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

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

Adaptive_Comfort_Parameters

217

Ladybug Primer

Body Characteristics

Use this component to calculate the Basal Metabolic Rate, Body Mass Index indices and to create the "bodyCharacterstics_" input for the "Thermal comfort indices" component. - Basal Metabolic Rate formula by Mifflin-St. Jeor. Body Mass Index formula by Adolphe Quetelet. Formulas from: "Comparison of predictive equations for resting Metabolic rate in healthy nonobese and obese adults: a systematic review", Frankenfield, Roth-Yousey, Compher, American Dietetic Association, 2005.: https://www.andeal.org/files/Docs/Frankenfield_et_al_2005%5B1%5D.pdf -

Inputs


218

Ladybug Primer age [Optional]

An age of the person. - If not supplied, default value of 35 will be used. - In years. sex [Optional]

Person's sex. - 1 or "male" 2 or "female". - If not supplied, "male" will be used as a default value. height [Optional]

Person's height. - If not supplied default value of 175 cm will be used. - In centimetres. weight [Optional]

Person's weight. - If not supplied default value of 75 kg will be used. - In kilograms. bodyPosition [Optional]

Position of person's body. - 1 or "sitting" for sitting position. 2 or "standing" for standing position. 3 or "crouching" for crouching position. - If not supplied, 2 (standing) will be used as a default value. clothingInsulation [Optional]

Clothing insulation of a person in "clo" units. It ranges from 0 (nude person) to 4 (polar outfit). Overall clo value can be determined by adding individual clo values for each type of clothes, based on a clo values table ( http://www.engineeringtoolbox.com/cloclothing-thermal-insulation-d_732.html ) A more simplified approch would be: - 0.20 very light summer clothes (shorts/skirt, t-shirt, slippers, no socks) 0.55 - summer clothes (light trousers, short sleeves or blouse) 1 - street-business suit or Typical indoor winter clothing 1.5 - suit and cotton coat 2 - winter suit and coat 2.58 - firefighting clothes 4 heavy polar outfit (fur pants, coat, hood, gloves...) - If not supplied it will be caclulated for each hour based on air temperature, with minimal 0.5 and maximal 4.1 clo values. In clo. clothingAlbedo [Optional]

Average clothing and skin albedo of a person. Ranges from 0 to 100%. In theory clothes-skin albedo of 0 would absorb, while 100% will reflect all solar radiation. Some of the examples: - light colored (white and bright clothes) - 57 % dark colored (black and gray clothes) - 21 % medium colored (any clothes colors between upper two) - 37 % protective polyethylene/aluminium suits - 95 % - If not supplied 37% (medium colored) will be used as a default. - In percent.


219

Ladybug Primer acclimated [Optional]

Determine whether the test person had previously experienced heat/cold stress. "acclimated" or True if person in subject is acclimatized, "unacclimated" or False if it's not. - If no value is supplied, True (acclimated) will be used by default. 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


220

Ladybug Primer Basal Metabolic Rate - represents the minimum daily amount of energy needed to keep your body functioning, including breathing and keeping your heart beating, without lossing weight. It does not include the the calories you burn from normal daily activities or exercise. To account for daily activities and exercises, this BMR value needs to be multiplied with: - 1.2 - Light or no exercise and desk job 1.375 - Light exercise or sports 1-3 days a week 1.55 - Moderate exercise or sports 3-5 days a week 1.725 - Hard exercise or sports 6-7 days a week 1.9 - Hard daily exercise or sports and physical job Once the person knows the number of daily calories needed to maintain its weight, it can easily calculate the number of calories it needs to eat in order to gain or lose weight. In calories/day. BMI

Body Mass Index - is the ratio of the persons weight to square of height. It is generally used as a method of screening for weight category. In kg/m2. BMILevel

Level of BMI for adult (18 years and older) males and females: for males: BMI < 17.5 - Anorexia 17.5 < BMI < 20.7 - Underweight 20.7 < BMI < 26.4 - Normal weight 26.4 < BMI < 27.8 - Marginally overweight 27.8 < BMI < 31.1 Overweight 31.1 < BMI < 40 - Obese BMI > 40 - Extreme obesity for females: BMI < 17.5 - Anorexia 17.5 < BMI < 19.1 - Underweight 19.1 < BMI < 25.8 - Normal weight 25.8 < BMI < 27.3 - Marginally overweight 27.3 < BMI < 32.3 Overweight 32.3< BMI < 40 - Obese BMI > 40 - Extreme obesity - In calories/day. bodyCharacteristics

A list of inputted values (age, sex, height, weight, bodyPosition, clothingInsulation, acclimated, metabolicRate, activityDuration). - Use it for the "Thermal comfort indices" component's "bodyCharacteristics_" input. Check Hydra Example Files for Body Characteristics


221

Ladybug Primer

Gradient Library

Use this component to access a library of typical gradients useful throughout Ladybug. The output from this component should be plugged into the customColors input of the "Ladybug_Legend Parameters" component. For an image of each of the gardients in the library, check here: https://github.com/mostaphaRoudsari/ladybug/blob/master/resources/gradients.jpg -

Inputs gradIndex [Required]

Gradient_Library

222

Ladybug Primer An index refering to one of the following possible gradients: 0 - Orignal Ladybug 1 Nuanced Ladybug 2 - Multi-colored Ladybug 3 - View Analysis 1 4 - View Analysis 2 (Red,Green,Blue) 5 - Sunlight Hours 6 - Ecotect 7 - Thermal Comfort Percentage 8 Thermal Comfort Colors 9 - Thermal Comfort Colors (UTCI) 10 - Hot Hours 11 - Cold Hours 12 - Shade Benefit/Harm 13 - Thermal Comfort Colors v2 (UTCI) 14 - Shade Harm 15 - Shade Benefit 16 - Black to White 17 - CFD Colors 1 18 - CFD Colors 2 19 Energy Balance 20 - THERM 21 - Cloud Cover

Outputs customColors

A series of colors to be plugged into the "Ladybug_Legend Parameters" component. Check Hydra Example Files for Gradient Library

Gradient_Library

223

Ladybug Primer

Legend Parameters

Use this component to change the colors, numerical range, and/or number of divisions of any Ladybug legend along with the corresponding colored mesh that the legend refers to. This component can also move a legend and change its scale. Any Ladybug component that outputs a colored mesh and a legend will have an input that can accept Legend Parameters from this component. This component particularly helpful in making the colors of Ladybug graphics consistent for a presentation or for synchonizing the numerical range and colors between Ladybug graphics. -

Inputs

Legend_Parameters

224

Ladybug Primer lowBound [Optional]

A number representing the lower boundary of the legend's numerical range. The default is set to the lowest value of the data stream that the legend refers to. highBound [Optional]

A number representing the higher boundary of the legend's numerical range. The default is set to the highest value of the data stream that the legend refers to. numSegments [Optional]

An interger representing the number of steps between the high and low boundary of the legend. The default is set to 11 and any custom values put in here should always be greater than or equal to 2. customColors [Optional]

A list of colors that will be used to re-color the legend and the corresponding colored mesh(es). The number of colors input here should match the numSegments_ value input above. An easy way to generate a list of colors to input here is with the Grasshopper "Gradient" component and a Grasshopper "Series" component connected to the Gradient component's "t" input. A bunch of Grasshopper "Swatch" components is another way to generate a list of custom colors. The default colors are a gradient spectrum from blue to yellow to red. legendLocation [Optional]

Input a point here to change the location of the legend in the Rhino scene. The default is usually set to the right of the legend's corresponding Ladybug graphic. legendScale [Optional]

Input a number here to change the scale of the legend in relation to its corresponding Ladybug graphic. The default is set to 1. font [Optional]

An optional text string that sets the font of the text. Examples include "Arial", "Times New Roman" or "Courier" (all without quotations). The text input here can be any font that is on your computer but the font must be of an Editable file type (as seen in the font folder off of your control panel). Font files that are Print and Preview will not work. If you wish to use a Bolded version of the font, include a ", Bold" at the end of the font name (example: "Arial, Bold").

Legend_Parameters

225

Ladybug Primer fontSize [Optional]

An optional number to set the size of the text in Rhino model units. decimalPlaces [Optional]

An interger representing the number of decimal places to make the legend values. The default is set to 2 decimal places. removeLessThan [Optional]

Set to 'True' to have the "<=" and ">=" symbols removed from the legend. The default is set to 'False' to have these symbols included.

Outputs legendPar

A list of legend parameters to be plugged into any of the Ladybug components with a legend. Check Hydra Example Files for Legend Parameters

Legend_Parameters

226

Ladybug Primer

PMV Comfort Parameters

Use this component to set PMV comfort parameters for the PMV comfort calculator or the Psychrometric Chart. Parameters include whether comfort is defined by 80 or 90 percent of the occupants comfortable as well as maximum and minimum acceptable humidity ratios. Note that the applied science and engineering community differs widely on its i nderstanding of these parameters. The air conditioning industy set out with the goal of satisfying 80% of the

occupants (assuming they all had similar clothing and metabolic rates) but many today set 90% as their benchmark. Also note that, if you try to restrict everyone's clothing and


227

Ladybug Primer metabolic rate as the PMV model assumed, you can never make 100% of the people comfortable. _ Further note that cultures differ widely in terms of their treatment of humidity at cooler temperatures and lack of humidity. -

Inputs PPDComfortThreshold [Optional]

A number between 5 and 100 that represents the percent of people dissatisfied (PPD) at which point a given set of conditions are outside of a comfortable range. The default is set to 10 percent, which is the typical criteria for both US and European (ISO) standards. However, both of these standards allow an expanded range for infrequenltyoccupied buildings (20% in the US and 15% in Europe) and the European standard requires 6% for 'Class I' buildings. Note that, if you try to restrict everyone's clothing and metabolic rate as the PMV model assumes, you can never make 100% of the people comfortable. This is why the smallest acceptable input here is 5%. humidRatioUpBound [Optional]

An optional number between 0.012 and 0.030 that limits the maximum humidity ratio acceptable for comfort. In many cultures and to many people, humidity in conditions of no thermal stress is not considered a source of discomfort and, accordingly, this component does not set an upper limit on humidity by default. However, for some people, stickyness from humidity in cool conditons is considered uncomfortable and, if you want to account for such a situation, you may want to set an upper limit on the acceptable humidity ratio here. The ASHRAE 55 PMV comfort standard recommends a maximum humidity of 0.012 kg water/kg air. humidRatioLowBound [Optional]

An optional number between 0.000 and 0.005 that limits the minimum humidity ratio acceptable for comfort. In many cultures, a lack of humidity is not considred uncomfortable since people compensate for its effects by using chap stick and lotions. Accordingly, this component does not set a lower limit on humidity by default. However, in some more tropical where people are not accustomed to very dry environments, chaping of lips and drying of skin can occur more easily and, if you want to account for such a situation, you may want to set a lower limit on the acceptable humidity ratio here. The ASHRAE 55 PMV comfort recommends no lower limit on humidity.

Outputs comfortPar


228

Ladybug Primer Comfort parameters that you can plug into either the "Ladybug_PMV Comfort Calculator" or the "Ladybug_Psychrometric Chart." Check Hydra Example Files for PMV Comfort Parameters


229

Ladybug Primer

Passive Strategy List

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

Inputs Check Hydra Example Files for Passive Strategy List

Passive_Strategy_List

230

Ladybug Primer

Real Time Radiation Analysis

Use this component to scroll through the results of a Ladybug Radiation Analysis on an hour-by-hour, day-by-day, or month-by-month basis in real time! The component uses a sky matrix (SkyMxt) from the selectSkyMxt component and the intersection matrix (intersectionMxt) from the Radiation Analysis component to calculate real time radiation results. Once the correct inputs have been hooked up to this component, you should use the inputs of the connected selectSkyMxt component to scroll through results. -

Inputs selectedSkyMatrix [Required]


231

Ladybug Primer The output from a Ladybug selectedSkyMtx component. This matrix basically carries all of the radiation values that define a sky and includes a radiation value for each sky patch on the sky dome. You should use the selectSkyMxt component connected here to scroll through radiation results. intersectionMatrix [Required]

The intersectionMxt output from a Ladybug Radiation Analysis component that has been run for test geometry. This matrix is basically a python list that includes the relation between each test point in the Radiation Analysis and all the sky patchs on the sky dome.

Outputs radiationResult

New radiation values for each test point in the original Radiation Analysis. Values indicate radiation for the the connected sky matrix. To visualize these new radiation values in the Rhino scene, connect these values to the Ladybug Re-Color Mesh component to re-color the mesh from the original Radiation Analysis with these new values. Check Hydra Example Files for Real Time Radiation Analysis


232

Ladybug Primer

Capture View

Use this component to capture Rhino views and save them to your hard drive as as a .png files. This is particularly useful if you are trying to create animations of Grasshopper geometry and want to automate the capturing of views. Note that your images will have a Rhino world axes icon in the lower left of the image unless you go to Options > Grid > and uncheck "Show world axes icon" in Rhino. -

Inputs fileName [Required]

Capture_View

233

Ladybug Primer The file name that you would like the image to be saved as. Note that, for animations, you want to make sure that each saved images has a different filename otherwise the previous image will be overwritten by each successive image. folder [Optional]

The folder into which you would like to write the image file. This should be a complete file path to the folder. If no folder is provided, the images will be written to C:/Ladybug/Capturedviews/. viewNames [Optional]

The Rhino viewport name which you would like to take a snapshot of. Acceptable inputs include "Perspective", "Top", "Bottom", "Left", "Right", "Front", "Back" or any view name that you have already saved within the Rhino file (note that you do not need to input quotations). If no text is input here, the default will be an image of the active viewport (or the last viewport in which you navigated). imageWidth [Optional]

The width of the image that you would like to take in pixels. If no value is provided here, the component will set the width to that of the active Rhino viewport on your screen. imageHeight [Optional]

The height of the image that you would like to take in pixels. If no value is provided here, the component will set the height to that of the active Rhino viewport on your screen. displayMode [Optional]

The display mode of the viewport that you would like to take an image of. Acceptable inputs include "Wireframe", "Shaded", "Rendered", "Ghosted", "X-Ray", "Technical", "Atristic", and "Pen". If no text is input here, the default will be the displaymode of the active viewport (or the last viewport in which you navigated). keepAspectR [Optional]

Set to "True" to keep the aspect ratio of the viewport in the images that you save. By default, this is set to "False" if you have connected an imageHeight_ but will override this input to ensure correct aspect ratio if set to "True". capture [Required]

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

Capture_View

234

Ladybug Primer

Outputs imagePath

The filepath of the image taken with this component. Check Hydra Example Files for Capture View

Capture_View

235

Ladybug Primer

Orient to Camera

Use this component to generate a plane that is oriented perpendicular to the active Rhino viewport camera direction and centered at an input initPosition point. This is useful for orienting geometry Grasshopper to the Rhino viewport camera, which may help in presenting certain Ladybug visualizations in Rhino. Connect a Grasshopper "Timer" component to the refresh input of this component in order to

get a real time update of the oriented plane based on the Rhino viewport camera direction. -

Inputs initPosition [Required]

Orient_to_Camera

236

Ladybug Primer A point or list of points that will act as the origin9s0 of the plane(s) that will be generated. refresh [Optional]

Connect either a Grasshopper "button" component that will allow you to refresh the plane orientation upon hitting the button or a Grasshopper "Timer" component to see the plane update in real time as you navigate through the Rhino viewport.

Outputs orientedToCam

A plane (or list of planes) for each _initPosition connected. All planes are oriented perpendicular to the active Rhino viewport camera direction and are centered at initPosition points. Check Hydra Example Files for Orient to Camera

Orient_to_Camera

237

Ladybug Primer

Set the View

Use this component to set the camera location and direction for the Rhino "Perspective" viewport. Here is the video that shows how it works: http://www.youtube.com/watch? v=7Mmhz867zY8 -

Inputs cameraLocation [Required]

A point representing the location of the viewport camera.

Set_the_View

238

Ladybug Primer cameraDirection [Required]

A vector that represents the direction that the viewport camera should face. uvLookAround [Optional]

Optional UV coordinates to tilt the viewport camera off from from the input _cameraDirection. Values for UV coordinates must be between -1 and 1 and these correspond to a tilt of 180 degrees in either direction. It is recommended that you use a Grasshopper sliderMD comonent for input. lensLength [Optional]

An optional float number that sets the lens length of the viewport camera.

Outputs Check Hydra Example Files for Set the View

Set_the_View

239

Ladybug Primer

fly

Use Fly to cycle through all connected sliders. If no slider is connects it will cycle through all the sliders in the document! Fly is originally posted as a code snippet by David Rutten. The code has been modified by James Ramsedn and Mostapha Sadeghipour Roudsari. -

Inputs inputSliders [Required]

fly

240

Ladybug Primer Script Variable _inputSliders fly [Required]

Script Variable _fly

Outputs Vviiiiiiiiiizzz

Output parameter Vviiiiiiiiiizzz Check Hydra Example Files for fly

fly

241

Ladybug Primer

C2F

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

Inputs C [Required]

A temperature or list of temperatures in Celcius.

Outputs

C2F

242

Ladybug Primer F

The input temperatures converted to Fahrenheit. Check Hydra Example Files for C2F

C2F

243

Ladybug Primer

DOY_HOY

Use this component to calculate the day of the year and hour of the year from an input date with a day of the month, month of the year and hour of the day. -

Inputs days [Default]

A number (or list of numbers) between 1 and 31 that represents the day(s) of the month. months [Default]

DOY_HOY

244

Ladybug Primer A number (or list of numbers) between 1 and 12 that represents the month(s) of the year. hours [Default]

A number (or list of numbers) between 1 and 24 that represents the hour(s) of the day.

Outputs HOY

The hour of the year on which the input date and time fall. DOY

The day of the year on which the input date falls. date

The input information written out as a full date and time text string. Check Hydra Example Files for DOY_HOY

DOY_HOY

245

Ladybug Primer

Day_Month_Hour

Use this component to calculate date information from an hour of the year. Date information includes the day of the month, the month of the year and the hour of the day. -

Inputs HOY [Required]

Hour of the year

Outputs Day_Month_Hour

246

Ladybug Primer day

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

The month of the year on which the input HOY falls. hour

The hour of the day on which the input HOY falls. date

The input information written out as a full date and time text string. Check Hydra Example Files for Day_Month_Hour

Day_Month_Hour

247

Ladybug Primer

F2C

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

Inputs F [Required]

A temperature or list of temperatures in Fahrenheit.

Outputs

F2C

248

Ladybug Primer C

The input temperatures converted to Celcius. Check Hydra Example Files for F2C

F2C

249

Ladybug Primer

Activities Met List

Provides a list of available activites and outputs the metabolic rate of that activity for use in the Ladybug PMV comfort calculator.

Inputs Check Hydra Example Files for Activities Met List

Activities_Met_List

250

Ladybug Primer

BTU2Wh

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

Inputs BTU [Required]

An energy value or list of energy values in BTU, kBTU, BTU/ft2, or kBTU/ft2. Note that, for the component to recognize flux (division by ft2), the input must have a Ladybug header.

BTU2Wh

251

Ladybug Primer

Outputs Wh

The input enervy values converted to Wh, kWh, Wh/m2, or kWh/m2 (depeding on input). Check Hydra Example Files for BTU2Wh

BTU2Wh

252

Ladybug Primer


Use this component to combine two or more solar envelopes from Ladybug_SolarEnvelope component -


A surface representing the area for which you want to create the solar envelope (could also be a closed planer curve). Must be the same as the _BaseSrf connected to the solar Envelope component.


253

Ladybug Primer envelopePts [Required]

A list of 3d points representing the heights to which the solar envelope reaches. Use the envelopePts output from the solar envelope component. HighestEnv [Optional]

if HighestEnv_ is True we'll take the highest points and if it's False we'll take the lowest ones. Default value is True gridSize [Required]

A numeric value inidcating the gird size of the analysis in Rhino model units. Muse be the same as the gridSize_ value connected to the solar Envelope component.

Outputs newEnvPoints

A list of 3d points representing the heights to which the solar envelope reaches. Plug into a native GH 'Delunay Mesh' component to visualize the full solar envelope. envelopeBrep

Brep representing the envelope. Check Hydra Example Files for CombineSolarEnvelopes


254

Ladybug Primer

Comfort Mannequin

Use this component to color a mannequin based on their relation to a comfort temperature. t emperature. -

Inputs ambientTemperature ambientTemperature [Required]

The temperture around the mannequin, which can be either UTCI (outdoor comfort), Standard Effective Temperature (PMV comfort), or Operative Temperature (Adaptive Comfort).

Comfort_Mannequin

255

Ladybug Primer targetTemperature 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 posture of the comfort mannequin, mannequin, which can can have a large effect 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 rotation angle in degrees. degrees. Use this number number to adjust the angle 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 point that sets the position position of the comfort mannequin mannequin in space. Use Use this to move the comfort mannequin around in relation to contextShading_ contextShading_ connected below. The default is set to the Rhino origin. legendPar [Optional]


Outputs mannequinMesh

A colored mesh of a comfort comfort mannequin showing showing the amount amount of radiation falling falling over the mannequin's body. legend

A legend that corresponds corresponds to the colors on the mannequinMesh mannequinMesh and shows the relative relative W/m2.

Comfort_Mannequin

256

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

Comfort_Mannequin

257

Ladybug Primer

Construct Time

Use this component to construct a specific hour from corresponding time in hours, minutes and seconds. The output can be plugged into the analysisPeriod analysisPeriod or sunPath components. -

Inputs hour [Default]

A number between 1 and 23 representing representing the hour of the day. day. minutes [Default]

Construct_Time

258

Ladybug Primer A number between 1 and 60 representing representing the minute of the hour. hour. seconds [Default]

A number between 1 and 60 representing representing the second of the minute. minute.

Outputs hour

An output hour that an be plugged into into the analysisPeriod analysisPeriod or sunPath components. components. Check Hydra Example Files for Construct Time

Construct_Time

259

Ladybug Primer

Create Legend

Use this component to create a custom legend for any set of data or to create a more flexible legend for any ladybug component with a legend. Specifically, this component outputs data that can be plugged into the grasshopper "Text Tag 3D" component so that the legend text can be baked into the Rhino scene as actual text instead of surfaces representing text. -

Inputs valuesOrRange [Required]

Create_Legend

260

Ladybug Primer The list of numerical data that the legend refers to (or just the minimum and maximum numerical values of this data). If the original numerical data is hooked up, the legend's maximum and minimum values will be set by the max and min of the data set. legendBasePt [Optional]

An optional point to set the location of the legend. This can be the output legendBasePt of any of the Ladybug components that have a legend. If a point is hooked up here and another point is hooked up at a legendPar component that is connected to this one, the point on the legendPar component will override the input point here. legendTitle [Optional]

A text string representing a legend title. Legends are usually titled with the units of the data. If no text is provided here, the default title will read "unkown units." legendSize [Optional]

The initial size of a single colored cell of the legend mesh, which determines the size of the whole legend. This should be a numerical value corresponding to the length of a legend cell in Rhino model units. The default is set to 10 Rhino units. legendPar [Optional]


Outputs legendMesh

A colored mesh that corresponds to the input _valuesOrRange. Connect this output to a grasshopper "Mesh" component in order to preview this separately in the Rhino scene. legendTextSrf

A list of surfaces representing the text labels of the legend. These surfaces will reflect the font and size input to the legendPar. legendBasePt

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

The base points that correspond to the title text and numerical value text of the legend. Create_Legend

261

Ladybug Primer Plug this into the "Location" input of the grasshopper "Text Tag 3D" component in order to display as text in Rhino. legendTextValues

The text strings that correspond to the title and numerical values of the legend. Plug this into the "Text" input of the grasshopper "Text Tag 3D" component in order to display as text in Rhino. recommendedTextSize

Values representing recommended text sizes that correspond to the title and numerical values of the legend. These values are generated based on the legend size and scale. Plug this into the "Size" input of the grasshopper "Text Tag 3D" component in order to display as text in Rhino. Check Hydra Example Files for Create Legend

Create_Legend

262

Ladybug Primer

L2G

Use this component to convert the liquid volume from Liters to U.S. Gallons (not Imperial Gallons). -

Inputs L [Required]

A value or list of values in Liters.

Outputs L2G

263

Ladybug Primer G

Input volume converted to U.S. Gallons. Check Hydra Example Files for L2G

L2G

264

Ladybug Primer

Orientation Study Parameters

Use this component with the Ladybug "Radiation Analysis", "Sunlight Hours Analysis", or "View Analysis" component to set up the parameters for an Orientation Study. You can use an Orientation Study to answer questions like "What orientation of my building will give me the highest or lowest radiation gain for my analysis period?" Another question might be "What direction should I orient my static solar panel to get the maximum radiation during my analysis period?" An Orientation Study will automatically rotate your geometry around several times based on the inputs made to this component and the results will be recorded in the corresponding Analysis component that this one is hooked up to. -

Inputs Orientation_Study_Parameters

265

Ladybug Primer divisionAngle [Required]

A number between 0 and 180 that represents the degrees to rotate the geometry for each step of the Orientation Study. totalAngle [Required]

A number between 0 and 360 that represents the degrees of the total rotation that the geometry will undergo over the course of the Orientation Study. This _totalAngle should be larger than the _divisionAngle and divisible by the _divisionAngle. 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

Orientation_Study_Parameters

266

Ladybug Primer

Passive Strategy Parameters

Use this component to adjust the assumptions of the passive strategies that can be overalid on the Ladybug the Psychrometric Chart. The default assumptions of each of the strategies are as follows: Evaporative Cooling - This polygon represents the conditions under which direct evaporative cooling would be helpful. As such, it takes as its upper limit the line of constant enthalpy from the edge of the comfort polygon and includes all warm temperatures below it. If the user has set a minimum humidity tolerance, the polygon will also include the points beneath the comfort polygon as it is assumed that the evaporation of water will both humidify and cool the air. Nothe that this direct evaporative cooling polygon is slightly

Thermal Mass + Night Flush - The polygon represents the conditions under which shaded, night-flushed thermal mass can keep different than 2-stage evaporative cooling.


267

Ladybug Primer occupants cool. By default, this polygon assumes that temperatures can get as high as 16.7 C above the max temperature of the comfort polygon as long temperatures 12 hours before the hot period are 2.8 C lower than the max temperture of the comfort polygon. This parameter component can be used to adjust these two numbers. The thermal mass polygon is limited in terms of humidity in that it obeys any limits on absolute humidity that the comfort polygon dies. Occupant Use of Fans - This polygon is made by assuming that a wind speed of 1.5 m/s is the maximum speed tolerable before it starts blowing papers and becomes annoying to occupants. This strategy parameters component can be used to adjust this maximum acceptable wind speed. As such, the polygon is determined by running a PMV model with this wind speed and the input rad temp, met rate and clo level of the psych chart. This component obeys any limits on humidity that the comfort polygon does. Note that this polygon assumes that you are already naturally ventilating and that your natural ventilation

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

period is defined by your comfort polygon.

Inputs maxTempAboveComf [Optional]

An optional number in degrees C representing the maximum daily temperature above the comfort range which can still be counted in the Thermal Mass + Night Flush polygon. The default is set to 16.7 C above the highest comfort temperature. minNightDiffBelowComf [Optional]

An optional number in degrees C representing the minimum temperature below the maximum comfort temperature that the outdoor temperature must drop at night in order to count towards the Thermal Mass + Night Flush polygon. The default is set to 2.8 C. maxComfortableAirSpeed [Optional]

An optional number in m/s that represents the maximum winds speed tolerable before it starts blowing papers and becomes annoying to occupants. This is used to shape the


268

Ladybug Primer "Occupant Use of Fans" Polygon and the default is set ot 1.5 m/s. lowestBldgBalancePt [Optional]

An optional number representing the building balance point, which will be used to shape the "Internal Heat Gain" strategy polygon. The default is set to 12.8 C and it is assumed that, above this outdoor temperature, the building is free-running and occupants are able to open windows as they wish. Note that this default balance temperature of 12.8 is fairly low and assumes a large number of inside heat sources or people as well as in insulated envelope.

Outputs strategyPar

Passive strategy parameters that can be plugged into the "Ladybug_Psychrometric Chart" to adjust the assumptions of the passive strategy polygons. Check Hydra Example Files for Passive Strategy Parameters


269

Ladybug Primer

Shading Parameters List

Use this component to generate shading depths, numbers of shades, horizontal or vertical boolean values, and shade angles for different cardinal directions to be plugged into the "Ladybug_Shading Designer" component or the "Honeybee_EnergyPlus Window Shade Generator". -

Inputs northShdParam [Default]

Shading parameter for north-facing glazing.


270

Ladybug Primer westShdParam [Default]

Shading parameter for west-facing glazing. southShdParam [Default]

Shading parameter for south-facing glazing. eastShdParam [Default]

Shading parameter for east-facing glazing.

Outputs shdParamList

A list of shading parameters for different cardinal directions to be plugged into either the input of the "ShadingDesigner" component or the "HoneybeeEnergyPlus Window Shade Generator". Depending on the type of values that you input, these can go into either of these inputs: _depth, _numOfShds, _distBetween, _horOrVertical , shdAngle.

Check Hydra Example Files for Shading Parameters List


271

Ladybug Primer

Wh2BTU

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

Inputs Wh [Required]

An energy value or list of energy values in Wh, kWh, Wh/m2, kWh/m2. Note that, for the component to recognize flux (division by m2), the input must have a Ladybug header.

Wh2BTU

272

Ladybug Primer

Outputs BTU

The input enervy values converted to BTU, kBTU, BTU/ft2, or kBTU/ft2 (depeding on input). Check Hydra Example Files for Wh2BTU

Wh2BTU

273

Ladybug Primer

Wh2kWh

Use this component to convert energy values in W to kW, W/m2 to kW/m2, Wh to kWh, Wh/m2 to kWh/m2, BTU to kBTU, or BTU/ft2 to kBTU/ft2. -

Inputs Wh [Required]

An energy value or list of energy values in W, W/m2, Wh, Wh/m2, BTU, or BTU/ft2.

Outputs Wh2kWh

274

Ladybug Primer kWh

The input enervy values converted to BTU, kBTU, BTU/ft2, or kBTU/ft2 (depeding on input). Check Hydra Example Files for Wh2kWh

Wh2kWh

275

Ladybug Primer

kWh2Wh

Use this component to convert energy values in kW to W, kW/m2 to W/m2, kWh to Wh, kWh/m2 to Wh/m2, kBTU to BTU, or kBTU/ft2 to BTU/ft2. -

Inputs kWh [Required]

An energy value or list of energy values in Wh, kWh, Wh/m2, kWh/m2. Note that, for the component to recognize flux (division by m2), the input must have a Ladybug header.

kWh2Wh

276

Ladybug Primer

Outputs Wh

The input enervy values converted to BTU, kBTU, BTU/ft2, or kBTU/ft2 (depeding on input). Check Hydra Example Files for kWh2Wh

kWh2Wh

277

Ladybug Primer

ms2mph

Convert from m/s to mile/h -

Inputs ms []

Input wind speed in meters per second

Outputs

ms2mph

278

Ladybug Primer mph

Output wind speed in miles per hour Check Hydra Example Files for ms2mph

ms2mph

279

Ladybug Primer

rIP2rSI

Use this component to convert R-Values in IP (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 rIP2rSI

280

Ladybug Primer R_SI

The R-Value in SI (K·m2/W). Check Hydra Example Files for rIP2rSI

rIP2rSI

281

Ladybug Primer

uIP2uSI

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]

An R-Values in IP (h·ft2·°F/BTU).

Outputs uIP2uSI

282

Ladybug Primer U_SI

The R-Value in SI (K·m2/W). Check Hydra Example Files for uIP2uSI

uIP2uSI

283

Ladybug Primer

Component list: Export_Ladybug Update_Ladybug

5 | Developers

284

Ladybug Primer

Export Ladybug

Code Developers of Ladybug and Honeybee can use this component to export Ladybug/Honeybee user objects and source code that they create to the Github folder on their computer. This eases and automates the steps before commiting new components to the Github. This component was written thanks to Giulio Piacentino a really helpful example. -

Inputs components [Required]

Export_Ladybug

285

Ladybug Primer Any output from a new Ladybug (or Honeybee) component that you wish to export. Right now, only one component can be connected at a time but you can input a "*" (without quotation marsk) to search all changed Ladybug components on a grasshopper canvas. targetFolder [Required]

A file path on your system which you would like to export the user object and source code to. For most code developers, this file path will lead to their Github folder for Ladybug (or Honeybee), which is usually installed in "My Documents" by default. Exported source code will be saved at .\src and exported userObjects will be saved at .\userObjects in this _targetFolder. export [Required]

Set to "True" to export Ladybug (or Honeybee) components to the _targerFolder.

Outputs readMe!

... Check Hydra Example Files for Export Ladybug

Export_Ladybug

286

Ladybug Primer

Update Ladybug

Code Developers and Beta Testers of new Ladybug components can use this component to remove old Ladybug components, add new Ladybug components, and update existing Ladybug components from a synced Github folder on their computer. This component can also update outdated Ladybug components in an old Grasshopper file so long as the updates to the components do not involve new inputs or outputs. -

Inputs sourceDirectory [Optional]

Update_Ladybug

287

Ladybug Primer An optional address to a folder on your computer that contains the updated Ladybug userObjects. If no input is provided here, the component will download the latest version from GitHUB. updateThisFile [Required]

Set to "True" if you want this component to search through the current Grasshopper file and update Ladybug components that have changed. updateAllUObjects [Required]

Set to "True" to sync all the Ladybug and Honeybee userObjects in your Grasshopper folder with the GitHUB.

Outputs readMe!

... Check Hydra Example Files for Update Ladybug

Update_Ladybug

288

Ladybug Primer

Component list: Bioclimatic_Chart Shadow_Study PV_SWH_System_Size Photovoltaics_Module Cold_Water_Temperature Commercial_Public_Apartment_Hot_Water Residential_Hot_Water Solar_Water_Heating_Performance_Metrics Solar_Water_Heating_Surface Solar_ Water_Heating_System Solar_Water_Heating_System_Detailed Shading_Mask Shading_Mask_II

6 | WIP

289

Ladybug Primer

Bioclimatic Chart

This is the Bioclimactic Chart. It is based in the originally proposed chart by V. Olgyay and then in the chart presented in the book "Sun, Climate and Architecture" by Brown. Use this component to draw a Bioclimatic chart in the Rhino scene and evaluate a set of temperatures and humidity ratios in terms of indoor comfort. Connected data can include either outdoor temperature and humidty ratios from imported EPW weather data, indoor temperature and humidity ratios from an energy simulation, or indivdual numerical inputs of temperature and humidity. The input data will be plotted alongside polygons on the chart representing comfort as well as polygons representing the efects of passive building strategies on comfort. References:

Bioclimatic_Chart

290

Ladybug Primer

1. Olgyay, V., 1963. Design with Climate. Bioclimatic Approach to Architectural Regional 2. Givoni B., 1976. Man, Climate and Architecture. Applied Science Publishers, Ltd., Lon 3. Murray M. and Givoni B., 1979. Architectural Design Based on Climate in Watson D. (ed 4. Yezioro, A. & E. Shaviv. 1996. A Knowledge Based CAD System for Determining Thermal C 5. Brown G.Z. and DeKay M., 2001. Sun, WInd & Light. Architectural Design Strategies (2n

-


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 as 2 to 4 clo. passiveStrategy [Optional]

Bioclimatic_Chart

291

Ladybug Primer An optional text input of passive strategies to be laid over the Bioclimatic chart as polygons. Text inputs include "Passive Solar Heating", "Evaporative Cooling", "Thermal Mass + Night Vent" and "Natural Ventilation". NOT WORKING RIGHT NOW!! cullMesh [Optional]

Set to "True" to cull the colored mesh to where they have climatic data on them. See chartMesh output. Deafult "False" calculateCharts [Optional]

Set to "True" to calculate and show a column type graph showing the percentage of time each strategy is capable of providing comfort conditions. See resultsChart output. Deafult "False" analysisPeriodWinter [Optional]

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]


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

Outputs Bioclimatic_Chart

292

Ladybug Primer readMe!

... comfortResults

The number of hours and percent of the input data that are inside all comfort and passive strategy polygons. totalComfortOrNot

A list of 0's and 1's indicating, for each hour of the input data, if the hour is inside a comfort and/or strategy polygon (1) or not(0). strategyOrNot

A list of 0's and 1's indicating, for each hour of the input temperature and humidity ratio, if the hour is inside (1) or not(0), for each passive strategy and comfort polygons. If there are multiple comfort polyogns or passive strategies connected to the passiveStrategy_ input, this output will be a grafted list for each polygon. chartGridAndTxt

The grid and text labels of the Bioclimatic chart. chartMesh

A colored mesh showing the number of input hours happen in each part of the Bioclimatic chart. legendChartMesh

Script variable BioclimacticChart chartHourPoints

Points representing each of the hours of input temperature and humidity ratio. By default, this ouput is hidden and, to see it, you should connect it to a Grasshopper preview component. hourPointColorsByComfort

Color the chartHourPoints above according to Comfort results. They can be hooked up to the "Swatch" input of a Grasshopper Preview component that has the hour points above connected as geometry. By default, points are colored red if they lie inside comfort or strategy polygons and are colored blue if they do not meet such comfort

Bioclimatic_Chart

293

Ladybug Primer criteria. hourPointColorsByMonth

Colors that the chartHourPoints above according to each month. They can be hooked up to the "Swatch" input of a Grasshopper Preview component that has the hour points above connected as geometry. By default, points are colored red if they lie inside comfort or strategy polygons and are colored blue if they do not meet such comfort criteria. min_maxPoints

Plot each month's Minimal/Maximal values for Temperature and Relative Humidity. By 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

Bioclimatic_Chart

294

Ladybug Primer

Shadow Study

Use this component to generate outline curves representing shadows cast by input _geometry for a given _sunVector. Note that, to see shadows cast onto a ground, a surface representing the ground plane must be included in the input _geometry. Also, please note that, for a list of input _geometry that is larger than 4 or 5 breps, the calculation time of this component can be very long. Please keep the input geometry to small lists or be prepared to wait a long time. WARNING: This component is a proof of concept that will not work in every situation. It is not ideal for analyzing curved surfaces and it is not able to calculate shadows for geometries that are intersecting each other. -

Inputs Shadow_Study

295

Ladybug Primer geometry [Required]

Breps representig test geometries that will cast shadows on each other. sunVector [Required]

A sun vector from the Ladybug sunPath component.

Outputs readMe!

... shadow

Outline curves representing the shadows cast by the individual input Breps on other input Breps. Note that, if all input _geometry is planar, this output can be hooked up to a Grasshopper "Brep" component to give Breps representing shadows cast. shade

Outline curves representing the the parts of individual input Breps that are not in the sun. In other words, this is the self-shaded part of the Breps. Note that, if all input _geometry is planar, this output can be hooked up to a Grasshopper "Brep" component to give Breps representing self-shaded areas. Check Hydra Example Files for Shadow Study

Shadow_Study

296

Ladybug Primer

PV SWH System Size

Use this component to generate the PVsurface or SWHsurface for "Photovoltaics surface" or "Solar Water Heating surface" components, based on initial PV or SWH system sizes. -


The output from the "importEPW" or "constructLocation" component. This is essentially a list of text summarizing a location on the earth.

PV_SWH_System_Size

297

Ladybug Primer PVmoduleSettings [Required]

A list of PV module settings. Use the "Photovoltaics Module" component to generate them. SWHsystemSettings [Required]

A list of all SWH system settings. Use the "Solar Water Heating System" or "Solar Water Heating System Detailed" components to generate them. systemSize [Optional]

1) In case of PV array: DC (Direct current) power rating of the photovoltaic array in kilowatts (kW) at standard test conditions (STC). 2) In case of SWH array: Capacity of the collectors array in thermal kilowatts (kw) at global or local testing conditions (ISO 9806, EN 12975, ASHRAE 93 ...) - If not supplied, 4 kW will be used as a default. - In kiloWatts (kW) or thermal kiloWatts (kWt). arrayTiltAngle [Optional]

An angle from horizontal of the inclination of the PV/SWH array plane. Example: 0 = horizontal, 90 = vertical. (range 0-180) - To get the maximal amount of energy, input the "optimalTilt" output from "Tilt And Orientation Factor"'s component. - If not supplied, location's latitude will be used as default value. - In degrees (°). arrayAzimuthAngle [Optional]

The orientation angle (clockwise from the true north) of the PV/SWH array plane's normal vector. (range 0-360) - To get the maximal amount of energy, input the "optimalAzimuth" output from "Tilt And Orientation Factor"'s component. - If not supplied, the following values will be used as default: 180 (due south) for northern hemisphere, 0 (due north) for southern hemisphere. - In degrees(°). tiltedArrayHeight [Optional]

The height of the array, measured in the tilted plane. It is depends on the height/width of the PV module/SWH collector. It also depends on the way modules/collectors are positioned in PV/SWH array (vertically or horizontally). It can vary from 1 to 2.3 meters x number of modules/collectors in a single PV/SWH column. - If not supplied, default value of 1.6 meters (with a single PV module/SWH collector per row) will be used. - In meters. numberOfRows [Optional]

Number of rows to which PV or SWH array will be divided to. - If not supplied, 1 will be PV_SWH_System_Size

298

Ladybug Primer used as a default value (PV/SWH array will have only 1 row). skewRowsDistance [Optional]

Distance in meters by which PV/SWH rows will be skewed. Use positive distance to skew the rows to the left. And negative distance to skew the rows to the right. - It requires the "numberOfRows_" to be larger than 1 in order to be able to skew the rows. - If not supplied, 0 will be used as a default (no rows skewing). minimalSpacingPeriod [Optional]

Analysis period for which the minimal spacing distance between PV modules/SWH collector rows will derived of. In general this analysis period is taken from 9 to 15 hour on a day at which sun is at its lowest position during a year. That is 21th December in Northern and 21th June in Southern hemisphere (winter and summer solstice). However, this may not be economical for locations with higher latitudes due to low electricity generation during December/June. - So the following "minimalSpacingPeriod_" should be used based on location's latitude: latitude <= 44: 21. December (northern hemisphere) / 21. June (southern hemisphere). 9-15hours latitude 44 - 53: 15. November or 15. January (northern hemisphere) / 15. May or 15. July (southern hemisphere). 9-15hours latitude 53 - 57: 15. October or 15. February (northern hemisphere) / 15. April or 15. August (southern hemisphere). 9-15hours latitude > 57: 15. September or 15. March (for both northern and southern hemisphere). 9-15hours - It requires the "numberOfRows_" to be larger than 1 in order visualize the minimal spacing between rows. - If not supplied, it will be calculated based on upper mentioned criteria. baseSurface [Optional]

Surface on which PV/SWH array will be laid onto. This can be a surface of an angled or flat roof. Or an angled or flat terrain. A facade of a building etc. - If not supplied, a regular horizontal surface in Rhino's XY plane will be used, as a default. arrayOriginPt [Optional]

UV coordinate of baseSurface_ at which PV_SWH array will start. It ranges from 0 to 1.0 for both U and V coordinate. Use grasshopper's "Construct Point" or "MD slider" components to input it. - If not supplied, (0.5,0,0) will be used as a default value. arrayOriginCorner [Optional]

Corner at which the PV/SWH array begins: - 0 - center bottom 1 - left bottom 2 - right PV_SWH_System_Size

299

Ladybug Primer bottom - If not supplied, 0 will be used as a default (bottom center). north [Optional]

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 "Domestic hot water" or "Hot water" components to calculate it. - The purpose of this input is to divide the energy loads to each PV/SWH array rows. If not inputted, "energyLoadPerRowPerHour" output will not be calculated.

Outputs readMe!

... PV_SWHsurface

Surfaces on which PV modules/SWH collectors will be laid on. PV_SWHsurfacesArea

Total area of the PV_SWHsurfaces. - In Rhino documents units (meters, centimeters, feets...). minimalSpacingDate

Exact date taken from "minimalSpacingPeriod_" input for which minimal spacing between rows has been calculated. arrayOriginPt

Origin point of the PV / SWH array. energyLoadPerRowPerHour

"energyLoadPerHour_" input's data divided to rows. PV_SWH_System_Size

300

Ladybug Primer Check Hydra Example Files for PV SWH System Size

PV_SWH_System_Size

301

Ladybug Primer

Photovoltaics Module

Use this component to define the Photovoltaics module settings. - If nothing inputed, the following PV module settings will be used by default: moduleType: Close (flush) roof mount moduleEfficiency: 15% temperatureCoefficient: -0.5 %/°C moduleActiveAreaPercent: 90% -

Inputs


302

Ladybug Primer moduleType [Optional]

Module type and mounting configuration: - 0 = Glass/cell/polymer sheet, Insulated back (pv curtain wall, pv skylights) 1 = Glass/cell/glass, Close (flush) roof mount (pv array mounted parallel and relatively close to the plane of the roof (between 5 and 15 centimenters)) 2 = Glass/cell/polymer sheet, Open rack (ground mount array, flat/sloped roof array that is tilted, pole-mount solar panels, solar carports, solar canopies) 3 = Glass/cell/glass, Open rack (the same as upper "2" type, just with a glass on the back part of the module). - If not supplied, default type: "Glass/cell/glass, Close (flush) roof mount" (1) is used. moduleEfficiency [Optional]

The ratio of electrical energy output from the PV module to input solar energy from the sun. Current typical module efficiencies for crystalline silicon modules range from 1420% - If not defined, default value of 15(%) will be used. - In percent (%). temperatureCoefficient [Optional]

A coefficient which accounts for the percentage the solar module's DC output power decrease/increase for every degree Celsius the solar cells temperature rises above/below 25°C. - In general it ranges from -0.44 to -0.5 for crystaline silicon modules. - If not supplied, -0.5 will be used as a default. - In %/°C. moduleActiveAreaPercent [Optional]

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

Outputs readMe!

... PVmoduleSettings

A list of PV module settings. Plug it to "Photovoltaics surface" component's "PVmoduleSettings_" input. Check Hydra Example Files for Photovoltaics Module


303

Ladybug Primer

Cold Water Temperature

Use this component to calculate the cold (inlet, mains) water temperature, if water pipes are burried undeground. Sources: http://www.energy.ca.gov/2013publications/CEC-400-2013003/CEC-400-2013-003-CMF-REV.pdf http://www.nrel.gov/docs/fy04osti/35917.pdf http://www.retscreen.net/download.php/ang/120/0/Textbook_SWH.pdf -

Inputs method [Optional]

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


304

Ladybug Primer Jaeger (used by DOE-2) 1 - Christensen and Burch (used by EnergyPlus) 2 - used by RETScreen - If not supplied, method "1" (Christensen and Burch) will be used by default. 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


305

Ladybug Primer Average January cold water temperature for picked pipesDepth and soilThermalDiffusivity . Use it for "SWHsystem" component's "avrJanuaryColdWaterTemperature_" input. - In °C. avrColdWaterTemperaturePerYear

Average annual cold water temperature for picked pipesDepth and soilThermalDiffusivity . - In °C. Check Hydra Example Files for Cold Water Temperature


306

Ladybug Primer

Commercial Public Apartment Hot Water

Use this component to calculate domestic hot water consumption for each hour during a year, for Commercial, Public and Apartment buildings. The following types of buildings are supported: office apartment house or multifamily building hotel/motel restaurants, cafeterias drive-ins, grilles, luncheonettes, sandwich, snack shops primary school


307

Ladybug Primer junior and senior high school men's dormitory women's dormitory hospital nursing home factory - Component based on paper: ASHRAE 2003 Applications Handbook (SI), Chapter 49, Service water heating: https://cours.etsmtl.ca/mec735/Documents/Notes_de_cours/2012/Hiver_2012/Service_ Water_heating_ASHRAE.pdf -


Input .epw file path by using grasshopper's "File Path" component. buildingType [Required]

Choose the building type for which hot water consumption will be calculated: - 0 - office 1 - apartment house, with 20 or less apartments 2 - apartment house, from 21 to 49 apartments 3 - apartment house, from 50 to 74 apartments 4 - apartment house, from 75 to 99 apartments 5 - apartment house, from 100 to 199 apartments 6 - apartment house, more than 200 apartments 7 - hotel/motel with 20 or less rooms 8 - hotel/motel from 21 to 60 rooms 9 - hotel/motel from 61 to 99 rooms 10 - hotel/motel more than 100 rooms 11 - (full meal) restaurants, cafeterias 12 - drive-ins, grilles, luncheonettes, sandwich, snack shops 13 - primary school 14 - junior and senior high school 15 men's dormitory 16 - women's dormitory 17 - hospital 18 - nursing home 19 - factory numberOfUnits [Required]

Number of units for upper chosen "_buildingType". Represents the number of: apartment units: apartment houses occupants: offices, elementary, junior, senior high schools, dormitories , hospitals, factories meals per day: (full meal) restaurants, cafeterias; drive-ins, grilles, luncheonettes, sandwich, snack shops beds: nursing homes litersPerUnitPerDay [Optional]

Number of liters for a single unit and day, based on _buidlingType - office - 3.8 l/day/occupant apartment house, with 20 or less apartments - 170 l/day/apartment apartment house, from 21 to 49 apartments - 159.2 l/day/apartment apartment house, Commercial_Public_Apartment_Hot_Water

308

Ladybug Primer from 50 to 74 apartments - 151.6 l/day/apartment apartment house, from 75 to 99 apartments - 144 l/day/apartment apartment house, from 100 to 199 apartments - 140.2 l/day/apartment apartment house, more than 200 apartments - 132.7 l/day/apartment hotel/motel with 20 or less rooms - 98 l/day/room hotel/motel from 21 to 59 rooms - 75.8 l/day/room hotel/motel from 60 to 99 rooms - 53.1 l/day/room hotel/motel more than 100 rooms - 37.9 l/day/room (full meal) restaurants, cafeterias - 9.1 l/day/meal drive-in, grille, luncheonette, sandwich, snack shop - 2.6 l/day/meal primary school - 2.3 l/day/pupil junior and senior high school - 6.8 l/day/pupil men's dormitory - 49.7 l/day/student women's dormitory - 46.6 l/day/student hospital - 160 l/day/patient nursing home - 69.7 l/day/bed factory - 45 l/day/worker - If not supplied, it will be picked based on chosen "_buildingType" and "_numberOfUnits" inputs. occupancyStartingHour [Optional]

An hour (from 1 to 24) during a day at which the occupancy of the chosen _buildingType starts: - office - 9 apartment house 7 hotel/motel 7 (full meal) restaurant, cafeteria - 7 drive-in, grill, luncheonette, sandwich, snack shop - 7 primary school - 9 junior and senior high school - 9 men's dormitory - 8 women's dormitory - 8 hospital - 1 nursing home - 1 factory - 1 - If not supplied, it will be picked based on chosen "_buildingType" input. occupancyDuration [Optional]

Number of adults (14 years and older) in household. - office - 9 apartment house - 15 hotel/motel - 8 (full meal) restaurant, cafeteria - 12 drive-in, grill, luncheonette, sandwich, snack shop - 17 primary school - 7 junior and senior high school - 7 men's dormitory - 15 women's dormitory - 15 hospital - 24 nursing home - 24 factory - 24 - If not supplied, it will be picked based on chosen "_buildingType" input. firstWeekStartDay [Optional]

Week day on which a year starts (1 - Monday, 2 - Tuesday, 3 - Wednesday...) - If not supplied, default value: 1 will be used (year starts on Monday, 1st January). weekendDays [Optional]

Define a list of two weekend (nonworking) days. Through out the World, countries have different days as their weekend days: - Thursday and Friday (4,5) Friday and Saturday (5,6) Saturday and Sunday (6,7) - If not supplied, Saturday and Sunday (6,7) will be taken as a default weekend days. holidayDays [Optional]

List of days (1 to 365) which are holiday (nonworking) days. - If not supplied, no holiday Commercial_Public_Apartment_Hot_Water

309

Ladybug Primer days will be used, with exception of "school" (_buildingType: 13 and 14) where summer, winter and spring/autumn holidays will be applied. For northern hemisphere, USA school holidays schedules have been taken as a default. For southern hemisphere, Australian school holidays schedule have been taken as a default. deliveryWaterTemperature [Optional]

Required water temperature. In Celsius It is recommended for delivery water temperature to not be lower than 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). hotWaterPerYear

Domestic hot water consumption for a whole year. - In L (Liters). averageDailyHotWaterPerYear


310

Ladybug Primer Average daily hot water consumption for a whole year. - In L/day (Liters/day). maximumDailyConsumption

Maximal hot water consumption per day during a year. - In (L/day) Liters/day. maximumConsumptionDay

Day with maximal hot water consumption. minimumDailyConsumption

Minimal hot water consumption per day during a year. - In (L/day) Liters/day. minimumConsumptionDay

Day with minimal hot water consumption. Check Hydra Example Files for Commercial Public Apartment Hot Water


311

Ladybug Primer

Residential Hot Water

Use this component to calculate domestic hot water consumption for each hour during a year, for a single family household (house). - Component based on paper: "Modeling patterns of hot water use in households", Ernest Orlando Lawrence Berkeley National Laboratory; Lutz, Liu, McMahon, Dunham, Shown, McGrue; Nov 1996: http://ees.lbl.gov/sites/all/files/modeling_patterns_of_hot_water_use_in_households_lbl37805_rev.pdf -



312

Ladybug Primer 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. Residential_Hot_Water

313

Ladybug Primer firstWeekStartDay [Optional]

A day of week on which a year starts (1 - Monday, 2 - Tuesday, 3 - Wednesday...) - If not supplied, default value: 1 will be used (year starts on Monday, 1st January). weekendDays [Optional]

Define a list of two weekend (nonworking) days. Through out the World, countries have different days as their weekend days: - Thursday and Friday (4,5) Friday and Saturday (5,6) Saturday and Sunday (6,7) - If not supplied, Saturday and Sunday (6,7) will be taken as a default weekend days. holidayDays [Optional]

List of days (1 to 365) which are holiday (nonworking) days. - Here is an example holiday days list for August: 213, 214, 215, 216, 217, 218, 219, 220, 221, 222, 223, 224, 225, 226, 227, 228, 229, 230, 231, 232, 233, 234, 235, 236, 237, 238, 239, 240, 241, 242, 243 - If not supplied, no holiday days will be used. 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!

...


314

Ladybug Primer heatingLoadPerHour

Thermal energy (or electrical energy) required to heat the domestic hot water consumption for each hour during a year. - In kWh. hotWaterPerHour

Domestic hot water consumption for each hour during a year. - In L/h (Liters/hour). hotWaterPerYear

Domestic hot water consumption for a whole year. - In L (Liters). averageDailyHotWaterPerYear

Average daily hot water consumption for a whole year. - In L/day (Liters/day). maximumDailyConsumption

Maximal hot water consumption per day during a year. - In (L/day) Liters/day. maximumConsumptionDay

Day with maximal hot water consumption. minimumDailyConsumption

Minimal hot water consumption per day during a year. - In (L/day) Liters/day. minimumConsumptionDay

Day with minimal hot water consumption. Check Hydra Example Files for Residential Hot Water


315

Ladybug Primer

Solar Water Heating Performance Metrics

Use this component to calculate various Solar water heating performance metrics. Also use it to calculate the optimal SWH system size and tank storage volume. -

Inputs SWHsurface [Required]

Use the same "_SWHsurface" you supplied to the "Solar Water Heating Surface" component.

Solar_Water_Heating_Performance_Metrics

316

Ladybug Primer SWHsurfacePercent [Optional]

The percentage of surface which will be used for SWH collectors (range 0-100). - There are no general rules or codes which would limit the percentage of the roof(surface) covered with SWH collectors. - If not supplied, default value of 100 (all surface area will be covered in SWH collectors) is used. - In percent (%). SWHsystemSettings [Optional]

A list of all Solar water heating system settings. Use the same "SWHsystemSettings_" you supplied to the "Solar Water Heating Surface" component. - If not supplied, the following swh system settings will be used by default: glazed flat plate collectors active closed loop pipe length: 20 meters unshaded heatingLoadPerHour [Required]

Use the same "_heatingLoadHour" you supplied to the "Solar Water Heating Surface" component. - In kWh. heatFromTankPerHour [Required]

Import "heatFromTankPerHour" output data from "Solar water heating surface" 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 Solar_Water_Heating_Performance_Metrics

317

Ladybug Primer supplied default value of 1135 (MJ/m2) for unglazed or glazed flat plate collector will be used. - In MJ/m2 (megajoules per square meter). tankEmbodiedEnergyPerL [Optional]

Energy necessary for product life-cycle of storage tank per liter. - If not supplied default value of 20 (MJ/l) will be used. - In MJ/l (megajoules per liter). collectorEmbodiedCO2PerM2 [Optional]

Carbon emissions produced during SWH collector's life-cycle per square meter.. - If not supplied default value of 65.5 (kg CO2/m2) for unglazed or glazed flat plate collector will be used. - In kg CO2/m2 (kilogram of CO2 per square meter). tankEmbodiedCO2PerL [Optional]

Carbon emissions produced during storage tank's life-cycle per liter. - If not supplied default value of 0.14 (kg CO2/l) for unglazed or glazed flat plate collector will be used. In kg CO2/l (kilogram of CO2 per liter). collectorLifetime [Optional]

Life expectancy of a SWH collector. - If not supplied default value of 15 (years) will be used. - In years. tankLifetime [Optional]

Life expectancy of a storage tank. - If not supplied default value of 10 (years) will be used. - In years. optimal [Optional]

Set to "True" to calculate optimal system size and tank storage volume. - Larger system sizes and tank volumes produce more energy, therefor cover more initial heating load, which results in less usage of auxiliary energy. However, the larger the system size and tank volume, more embodied energy is spent. In order to find an optimal system size (total size of all collectors) and storage tank volume, life-cycle energy analysis is used to acheive the maximal net energy saving of the swh system. The net energy saving of swh system is the energy saving in kWh remained after an annualized embodied energy (of collectors or storage tank) has been deducted from the operating energy saving of swh system. This method of optimization is superior in comparison with other simulation-based methods due to consideration of all energy performance stages (production, operation, maintenance...). - This optimization method can be used to account for capital costs, instead of embodied energy. This would account only for


318

Ladybug Primer operation performance stage. In this case capital costs of collector/per square meter, and tank/per liter would need to be inputted into: "collectorEmbodiedEnergyPerM2" and "tankEmbodiedEnergyPerL" inputs. - Optimization analysis based on the law of diminishing marginal utility: "A simplified method for optimal design of solar water heating systems based on life-cycle energy analysis", Renewable Energy journal, Yan, Wang, Ma, Shi, Vol 74, Feb 2015 www.sciencedirect.com/science/article/pii/S0960148114004807 runIt [Required]

...

Outputs readMe!

... optimalSystemSize

Optimal SWH system size (optimal total size of SWH collector's array) for a given SWHsurface's tilt, array and "heatingLoadHour". Minimum SWH system size is 0.15 kWt. Input it to "systemSize " input of "PV SWH system size" component to see how much area it would require. - To calculate it, set the "optimal_" input to "True". - In thermal kiloWatts (kWt). optimalTankSize

Solar water heating storage tank optimal size (volume). Minimum size is 100 liters. To calculate it, set the "optimal_" input to "True". - In liters. SEF

Solar Energy Factor - ratio of total energy provided by the swh system to auxiliary plus parasitic (circulation pump) energy for a whole year. - Unitless. SolarFractionPerMonth

Solar Fraction (or Solar Savings Fraction) - percentage of the heating load requirement that is provided by a swh system for each month during a year. It ranges from 0 to 100%. - In percent (%). SolarFractionPerYear

Solar Fraction (or Solar Savings Fraction) - percentage of the total heating load


319

Ladybug Primer requirement that is provided by a swh system for a whole year. It ranges from 0 to 100%. - In percent (%). energyValue

Total Energy value generated by SWH system for a whole year in currency unit (dollars, euros, yuans...) EROI

Energy Return On Investment - a comparison of the generated electricity to the amount of primary energy used throughout the SWH collector's product life-cycle. - Unitless. embodiedEnergy

Total energy necessary for an entire product life-cycle of SWH collectors and storage tank. - In GJ (gigajoules). embodiedCO2

Total carbon emissions produced during SWH collector and storage tank life-cycle. - In tCO2 (tons of CO2). CO2emissionRate

Also called Embodied GHG emissions or GHGEmissions. An index which shows how effective a SWH system is in terms of global warming. It is used in comparison with other fuels and technologies (Hydroelectricity(15), Wind(21), Nuclear(60), Geothermal power(91), Natural gas(577), Oil(893), Coal(955) ...) - In gCO2/kWh. EPBT

Energy PayBack Time - time it takes for SWH system to produce all the energy used through-out its collector's product life-cycle. - In years. Check Hydra Example Files for Solar Water Heating Performance Metrics


320

Ladybug Primer

Solar Water Heating Surface

Use this component to calculate amount of thermal energy that can be produced by a surface if a certain percentage of it is covered with Solar water heating liquid collectors. The thermal energy can then be used for domestic hot water, space heating or space cooling. Component based on: "Solar Engineering of Thermal Processes", John Wiley and Sons, J. Duffie, W. Beckman, 4th ed., 2013. "Technical Manual for the SAM Solar Water Heating Model", NREL, N. DiOrio, C. Christensen, J. Burch, A. Dobos, 2014. "A simplified method for optimal design of solar water heating systems based on life-cycle energy analysis", Renewable Energy journal, Yan, Wang, Ma, Shi, Vol 74, Feb 2015 http://www.wiley.com/WileyCDA/WileyTitle/productCd-0470873663.html


321

Ladybug Primer https://sam.nrel.gov/system/tdf/SimpleSolarWaterHeatingModel_SAM_0.pdf? file=1&type=node&id=69521 http://www.sciencedirect.com/science/article/pii/S0960148114004807 -


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 Solar_Water_Heating_Surface

322

Ladybug Primer 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="" to="" of="" lists="" (in="" their="" respective="" order):="" "a"="" always="" represents="" 1st="" list,="" "b"="" 2nd="" etc.="" -="" For="" example,="" if="" you="" have="" an="" dryBulbTemperature="" connected="" first="" windSpeed="" second="" list="" (both="" annualHourlyData_="" input),="" want="" plot="" data="" for="" time="" period="" when="" temperature="" is="" between="" 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.


323

Ladybug Primer runIt [Required]

...

Outputs readMe!

... heatFromTankPerHour

Thermal energy provided by the storage tank per each hour during a year. - In kWh. heatFromTankPerYear

Total thermal energy provided by the storage tank for a whole year. - In kWh. avrDailyheatFromTankPerYear

An average thermal energy provided by the storage tank per day for a whole year. - In kWh/day. heatFromAuxiliaryHeaterPerHour

Thermal energy provided and Electrical energy spent by an auxiliary heater per each hour during a year. Electric auxiliary heater used. - In kWh. dischargedHeatPerHour

Discharged surplus energy ("heat dump") per each hour during a year. It can be used to heat a pool, hot tub, greenhouse or as snow-melt system (by using radiant floor tubing bellow sidewalks, or radiatior beneath the entrance stairs). - In kWh. pumpEnergyPerHour

Electrical energy spent by the circulation pump(s) per hour during a year. - In kWh. tankWaterTemperaturePerHour

Tank water temperature per each hour during a year. - In °C. SWHsurfaceTiltAngle

The angle from horizontal of the inclination of the SWHsurface. Example: 0 = horizontal, 90 = vertical. It ranges from 0-180. - In degrees.


324

Ladybug Primer SWHsurfaceAzimuthAngle

The orientation angle (clockwise from the true north) of the SWHsurface normal vector. It ranges from 0-360. - In degrees. systemSize

Rated SWH system size. - In kWt. Check Hydra Example Files for Solar Water Heating Surface


325

Ladybug Primer

Solar Water Heating System

Use this component to define Solar water heating system settings. - If nothing inputed, the following swh system will be used by default: glazed flat plate collectors active closed loop 1 story unshaded -

Inputs Solar_Water_Heating_System

326

Ladybug Primer collectorType [Optional]

Type of the collector. The following ones can be used: - 0 - unglazed flat plate Least expensive. Mostly used for single home domestic how water heating and for heating swimming pools. More cost efficient in tropical and subtropical environments. They can also be used in moderate climates for seasonal usage. Can output water temperatures up to 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 mildwarm climates. Does not require electricity to operate. Is used for domestic hot water heating and space heating of a single home. If positioned on a roof require putting a storage tank above the collector, and therefor impose the roof construction to be able to carry the weight of the storage tank. SWHsurface component supports passive swh systems with auxiliary heater. - 1 - active (pumped) swh system More expensive. More efficient in temperate and cold climates. Require electricity to operate and battery backup in case of power outage. Can be used for domestic hot water heating, space heating and space cooling of a single home, building or several buildings (central heating). More efficient in warm and mild-warm climates, where it rarely freezes - - If not supplied, active (pumped) loop will be used. openLoop [Optional]

Define whether the swh system has an open (indirect) or closed (indirect) solar loop. - 0 - closed (indirect) loop Usage of heatexchanger. Antifreeze is a working fluid. More expensive. More efficient in temperate and cold climates where freezing may occur. Also suitable for locations with hard water hardness (mineral content). - 1 - open (direct) loop No usage of heatexchangers. Water is the working fluid. Less expensive. More efficient in warm and mild-warm climates, where it rarely freezes (air temperature never drops below 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,


327

Ladybug Primer closed (indirect) loop will be used. numberOfStories [Optional]

Total number of stories plus basement (if there is a basement). This input is used to calculate the total piping length in the solar loop, based on an assumption that the storage tank will be located at the lowest story (basement or ground floor), and solar collectors are located at the roof. - Example 1: a house with a ground floor, first floor and a basement - has 3 stories total. Example 2: a house with a ground floor, first floor, second floor and without a basement - has 3 stories total. - If sollar collectors are used on a ground instead of roof, use the "Solar Water Heating System Detailed" component instead of this one to enter the exact pipe length of the solar loop. - - If not supplied, "1" story will be used as a default value (a house with only a ground floor, without a basement). skyViewFactor [Optional]

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

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


328

Ladybug Primer

Solar Water Heating System Detailed

Use this component to define a detailed Solar water heating system settings. - If nothing inputed, the following swh system will be used by default: glazed flat plate collectors active closed loop pipe length: 20 meters unshaded -

Inputs Solar_Water_Heating_System_Detailed

329

Ladybug Primer collectorOpticalEfficiency [Optional]

Fr(tau alpha) Collector's optical efficiency coefficient. Also called Collector heat removal factor. Varies based on collector's type. Some default values by type: - 0.87 - unglazed flat plate 0.70 - glazed flat plate 0.50 - evacuated tube - If not supplied, default value 0.70 (glazed flat plate) will be used. - Unitless. collectorThermalLoss [Optional]

(FrUL) Collector's thermal loss coefficient. Varies based on collector's type. Some default values by type: - 21 - unglazed flat plate 4 - glazed flat plate 1.5 - evacuated tube - If not supplied, default value 4 (glazed flat plate) will be used. - In W/m2/°C. collectorActiveAreaPercent [Optional]

Percentage of the collector's area excluding collector framing, lateral insulation, or gaps between evacuated tubes... Also called aperture area. It ranges from 70 to 95% depending on the type of collector. - If not supplied, default value of 90(%) will be used. - In percent. workingFluidHeatCapacity [Optional]

Specific heat of the working fluid. - If swh system is intended to be used in a nonfreezing or light freezing climate (tropical and subtropical regions), then water should be used as a working fluid. The specific heat of water is: 4180 J/kg/°C. - If swh system is used in freezing climates (temperate, polar...), an antifreeze needs to be added to the water. In most cases this is Propylen glycol, Ethylen glycol or Bio glycol added in certain percentages to the water. Depending on the freezing temperatures of the climates, there are the following specific heats of water-glycol mixtures: up to -10°C: waterpropylenglycol 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. IAMcoefficient [Optional]


330

Ladybug Primer Incidence angle modifier coefficient (bo) - Use this input to account for collector efficiency losses due to different angles of incidence. Depends on the type of collector, tilt angle... Some default values depending on the type of collector: - 0.1 - glazed flat plate 0.1 - unglazed flat plate -0.05 - evacuated tube - If not supplied, 0.1 (glazed flat plate) will be used. - Unitless. skyViewFactor [Optional]

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

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. avrJanuaryColdWaterTemperature [Optional]


331

Ladybug Primer Average January January cold water water inlet temperature. This 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 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 f or each story (basement is calculated as a story too) and additionally additionally 10 meters for the t he 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 pipes inner diameter, diameter, in in milimeters. Depends Depends on overall collector collector area, working working fluid type, piping length... - If not supplied, for active swh systems, it will be calculated as: √(4 flowRatePerM2 collectorActiveArea collectorActiveArea / flowSpeed / pi), with flowSpeed assumed to be 0.7 liters/sec. - For passive swh systems as: 1.5 times the value of upper formula. - In millimetres. pipeInsulationThickness [Optional]

Thickness of the pipes insulation, in milimeters. For pipes with insulation thermal conductivity lower than 0.04 W/(m*K), based on pipeDiameter, pipeDiameter, the following insulation


332

Ladybug Primer thicknesses can be used: - 20 mm - pipeDiameter 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 pipeDiameter and upper criteria. - In millimetres. pipeInsulationConductivity [Optional]

Pipe's insulation thermal conductivity 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) (Polyurethane) will be used as a default value. - In W/(m*°C). pumpPower [Optional]

Overall circulation pumps power. 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, (thermosyphon, ICS or batch systems), set the pumpPower to 0. - If not supplied, it will be calculated based on SWHsurface 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. 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 thickness ... - If not supplied, default value 0.30 will be used. In W/m2/°C. heightDiameterTankRatio heightDiameterTankRatio [Optional]


333

Ladybug Primer Storage tank height and diameter ratio. It mostly ranges from 1 to 3. This input is important for calculation of tank's area. - If not supplied 2.6 will be used. - Unitless. heatExchangerEffectiveness [Optional]

Depends on the type of heat exchanger: its transfer coefficient, surface, flow rates, working fluid... It mostly ranges from 0.6 to 0.9 for closed (indirect) loop swh systems. Accepted default default value can be 0.8. - Set 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 Solar water heating system system settings. Plug it to SWHsurface SWHsurface component's component's "SWHsystemSettings_" "SWHsystemSettings_" input. Check Hydra Example Files for Solar Water Heating System Detailed


334

Ladybug Primer

Shading Mask

Use this component to see the portion of the sky dome that is masked by context geometry around a given viewpoint. The component will generate separate meshs for the portions of the sky dome that are masked and visible. The component will also calculate the percentage of the sky that is masked by the context geometry and the percentage that is visible (the sky view factor). -

Inputs testPt [Required]

Shading_Mask

335

Ladybug Primer A view point for which which one wants to see see the portion of the sky masked masked by the context geometry surrounding this point. context [Required]

Context geometry surrounding the _testPt that could block the view to the sky. Geometry must be a Brep or list of Breps. skyDensity [Default]

An integer that is greater greater than or equal to 0, 0, which to sets the number number of times that the Tergenza sky patches are split. Set to 0 to view a sky mask with the typical Tregenza sky, which will divide up the sky with a coarse density of 145 sky patches. Set to 1 to view a sky mask of a Reinhart sky, which will divide up each of these Tergenza patches into 4 patches to make a sky with a total of 580 sky patches. Higher numbers input here will ensure a greater accuracy but will also take longer. longer. The default is set to t o 3 to give you a high accuracy. scale [Optional]

Scale of the sky dome

Outputs masked

A mesh of the portion of the sky dome masked by the _context geometry. geometry. visible

A mesh of the portion of the sky dome visible visible by the _testPt through the _context geometry. percMasked

The percentage of the sky masked by the _context geometry at the _testPt. skyView

The percentage of the sky visible by the _testPt through the _context geometry. geometry. Check Hydra Example Files for Shading Mask

Shading_Mask

336

Ladybug Primer

Shading Mask_II

Use this component to see the portion of the sky dome that is masked by context geometry around a given viewpoint. The component will generate separate meshs for the portions of the sky dome that are masked and visible. The component will also calculate the percentage of the sky that is masked by the context geometry and the percentage that is visible (the sky view factor). -

Inputs testPt [Required]

Shading_Mask_II

337

Ladybug Primer

Recommend Documents