In this tutorial you will learn how to prepare a Honeybee model room for a daylight simulation by assigning the material optical properties, creating a sensor grid and importing the relevant weather data. Daylight simulation can be performed in various ways in Grasshopper. There are five different daylight simulations explained in this tutorial:

• Daylight factor simulation
• Point-in-time simulation
• Annual daylight simulation
• Annual irradiance simulation
• Direct sun hours simulation

Honeybee Daylight Simulation 1/10

Design link copied

This example refers to a shoebox geometry of an apartment which is on the ground floor of a 2-storeys building. It has a rectangular plan of 10m*10m, and it has a height of 3m.

The apartment has an entrance from the road with an opaque wooden door and has also one operable window facing the street. The window is shaded with wooden horizontal louvres. On the left and right side there are adjacent apartments, but on the back side it is not neighbouring any other apartment or building.

The exterior walls are made of concrete in light grey colour. The slabs are also made of concrete, and they are painted in white colour on the bottom side (ceiling). On the top part (floor), they are covered by timber in a darker colour. The interior walls are made of plywood and covered also in white paint.

Abbreviations:

HB(Honeybee), LB (Ladybug), DF (Daylight Factor), CIE (International Commission of Illumination), CBDM (Climate Based Daylight Modelling).

Exercise file

As a starting point for the Daylight Analysis in this tutorial you will need to have a HB room set-up ready. You can download or create the Grasshopper script and Rhino file from the “Honeybee model set-up” tutorial or use your own design. 

Honeybee Daylight Simulation 2/10

Model preparation link copied

Each time you want to perform a daylight simulation in grasshopper, there are some basic set-up parts needed. First the material optical properties need to be assigned to the HB model. Then a sensor grid needs to be created and the weather data need to be imported. 

Optical material properties

Before following on with the Daylight analysis, you should make sure that the relevant material optical properties are assigned to the faces of your HB model. In the steps that follow you will learn how you can assign optical material properties to the HB model. To do so, first the radiance modifiers per material are created, then the modifier subsets are created per face from which the modifier set is created. Lastly, the modifier set is assigned to the HB model after which you can visualize and check the modifiers. 

For a more accurate Daylight simulation, you should assign the values of the optical properties for each material in the corresponding surfaces. Specifically, you should specify the reflectance and transmittance.

• Reflectance (for opaque materials), which is a percentage indicating the amount of light that is reflected by the surface when the light falls into it (the higher the reflectance, the more light is reflected).
• Transmittance (for transparent materials), which is a percentage indicating the amount of light that is transmitted through the window (the higher transmittance, the more light passes through the window.)

Radiance modifiers per material

For each material of your project, a different Radiance modifier needs to be created, gathering its optical properties in it. In the HB-Radiance Modifiers you can find the different material categories that you may use. For this tutorial we are only going to use the ‘basic’ modifier for Opaque and Glass materials, however for your specific project you might need other modifier types. 

Create glass modifier for each window material.

• Create a glass modifier

• Define glass material name using a panel and connect to the ‘_name_’ input.

• Define transmittance of window using a Number Slider and input to _trans

Create opaque modifier for each opaque material.

• Create an opaque modifier 

• Define opaque material name using a panel and connect to the ‘_name_’ input.

• Define reflectance of material using a Number Slider and input to _reflect.

Material properties

For more information on different material properties, a good database of materials and their reflectance values is available here

Modifier Subsets per face type

The second step for assigning the material optical properties to your HB model faces is creating the modifier subsets per face type. To assign the material properties to the corresponding HB faces:

• Create modifier subset for each face type:

1. Exterior
2. HB-Radiance
   Modifiers
   HB Exterior Modifier Subset
3. Subfaces
4. HB-Radiance
   Modifiers
   HB Subface Modifier Subset
5. Interior
6. HB-Radiance
   Modifiers
   HB Interior Modifier Subset
7. Shading
8. HB-Radiance
   Modifiers
   HB Shade Modifier Subset

• Connect the ‘modifier’ result of each Radiance material modifier to the corresponding face input of each Modifier subset. For this tutorial:

1. Connect the ‘Dark timber/carpet’ modifier to ‘_exposed_floor_’ (HB Exterior Modifier Subset) and ‘_interior_floor_’ (HB Interior Modifier Subset).
2. Connect the ‘Light Grey concrete’ modifier to ‘_exterior_wall_’ (HB Exterior Modifier Subset) and ‘_interior_shade_’ (HB Shade Modifier Subset).
3. Connect the ‘Glass_Window’ modifier to ‘_window_’ and ‘_operable_’ (HB Subface Modifier Subset), so as to apply to both operable and non-operable windows.
4. Connect the ‘Light timber’ modifier to ‘_exterior_door_’ (HB Subface Modifier Subset) and ‘_exterior_shade_’ (HB Shade Modifier Subset).
5. Connect the ‘White paint’ modifier to ‘_interior_wall_’, ‘_ceiling_’ (HB Interior Modifier Subset) and ‘_exterior_roof_’ (HB Exterior Modifier Subset).

Assign the Modifier Subsets to the HB Room

The third step for assigning the material optical properties to the HB model is to create a modifier set from the modifier subsets and then input the modifier set to the HB room. The HB room and HB model creation should already be created – or copied – from tutorial “Set-up Honeybee room”. 

• Create a modifier set.

• Connect the result of each Modifier Subset to the respective input of the Modifier Set
• Give a characteristic name for the Modifier Set you are creating using a panel. In our example, you can write “Room1_Materials” in the panel.

• Connect the ‘mod_set’ result of the HB ModifierSet component to the ‘_mod_set_’ input of the HB Room component.

Visualize & Check

Finally, you need to visualize the material optical properties of the faces to check if they are correctly assigned. In order to quickly check the attributes that are assigned to each face a HB label face component can be used that displays a label on each face in Rhino 

Sensor grid

As second step in the preparation of the HB model for a daylight simulation, a sensor grid has to be created for each room in the HB model. With the ‘HB Sensor Grid from Rooms’ component a grid is automatically created inside your room based on a given grid size and distance from the floor. The grid size refers to the size of sensor grid cells. The distance from floor refers to the vertical distance between the sensor grid points and the HB room floor. For this tutorial a grid size of 0.5 meters and a distance from the floor of 0.75 meters is used. Next, the created sensor grid should be assigned to the HB model with the ‘HB Assign Grid and Views’ component. 

• Create a grid from rooms component.

• Connect the ‘model’ result from the HB model component to the ‘_rooms’ input.
• Define grid size using a Number Slider and connect to the ‘_grid_size’ input.

• Define distance from floor using a Number Slider and connect to the ‘_dist_floor’ input 

• Create an HB Assign Grids and Views component.

• Connect the ‘model’ result from the HB model component to the ‘_model’ input.
• Connect the ‘grid’ result from the ‘HB Sensor Grid from Rooms’ component to the ‘grids_’ input.

Import the Weather data

Finally, it is important to import and load the weather data that correspond to the selected location to perform a daylight simulation. You can import and extract the respective EPW weather data by following the steps in the sections of the “Importing weather files in Ladybug” tutorial. The “Importing weather files in Ladybug” tutorial gives a detailed description on how to import and extract the EPW data for a specific location, specify a time period in a weather file. Additionally in the tutorial you learn to check the quality of the data by plotting the normal radiation graphs for the respective climatic data, as it is important to make sure that the EPW file we are using is of good quality and does not miss any data. In this tutorial the weather data will be extracted for the whole year.

A different type of weather object is needed depending on which daylight simulation you want to run. The Daylight Factor (DF) simulation does not need any weather input, the point in time simulation requires a specific sky condition (e.g. cloudy or sunny) based on the location and a weather data object is needed for the annual daylight, annual irradiance and direct sun hours simulations. To extract the location and wea object from a specific location, the epw file needs to be downloaded with a URL. From this the location can be extracted and the epw file can be converted into a wea object. 

Honeybee Daylight Simulation 3/10

Daylight Factor simulation link copied

The first way to perform a daylight simulation discussed in this tutorial is the Daylight Factor simulation. Here, you will learn what Daylight Factor is, how to create and run this simulation, how to visualize the results and what the guideline requirements are.

What is the Daylight Factor?

The Daylight Factor (DF) gives an indication of how a space performs in the ‘worst case scenario’ of overcast (i.e., very cloudy) sky conditions. Under such conditions, the DF is defined as the ratio between the indoor illuminance recorded at desk height inside a space and the outdoor horizontal illuminance under an unobstructed sky. It is therefore expressed as a percentage value.

The DF simulation uses a standard definition of such sky conditions, called the CIE Standard Overcast sky. This means that the simulation is invariant of the location of the building and the time period, so no weather data will be used as an input in this analysis.

The EN 17037 code for Daylight in Buildings gives requirements for the Daylight Factor. You can compare the acquired values with the acceptable Daylight Factor values related to the location of your project. If you are a TU Delft student, you can find it by logging in with your TU Delft account in the following page.

Create & Run Simulation

To create and run the Daylight Factor simulation you have to create a HB Daylight factor component and input the ‘model’ result of HB Assign Grids and Views. You should pay attention to this, because it would create an error if you connected the ‘model’ result directly from the HB model component! Then you need to create a HB Radiance Parameter component to define the performance settings of the simulation. The recipe type of the radiance parameter should be set to 0, for running a DF simulation. 

For the detail level use 2 (high detail) in this tutorial. For further information on which detail level of radiance parameters you should choose or how you can select customized values for the radiance parameters, check the “HB customized radiance parameters” tutorial.

Lastly, a False Start Toggle is needed to start the simulation. Pay attention to selecting the HB FalseStart toggle when working with simulations. This toggle automatically turns back to False when closing the GH file, to prevent errors when opening the file. 

• Create a HB Daylight Factor component.

• Connect the ‘model’ result from the HB Assign Grids and Views component to the ‘_model’ input. 
• Create a HB Radiance Parameter component.

• Set ‘_recipe_type’ of HB Radiance Parameter to 0 for a DF simulation using a Number Slider.

• Define ‘_detail_level_’ of analysis, use 2 (high level of detail) for this tutorial using Number Slider.

• Create a False Start Toggle component and connect it to the ‘_run’ input of the HB Daylight Factor component.

• Double-click the False Start Toggle component in order to set it to ‘True’ and run the simulation.

Visualize the results

For easier comprehension of the simulation, you can visualize the results. A very convenient way to visualize the results obtained from any type of Radiance simulation is to create a Spatial Heatmap. A Spatial Heatmap is a 2-dimensional representation of the data per grid point obtained through the simulation. In each point, the corresponding value is represented by a colour.

To create a spatial heatmap for the DF results you can use the LB Spatial Heatmap component and connect the results for the simulation to the values input. The component uses the mesh from the created grid result of ‘HB Sensor Grid from Rooms’ to visualize the results on. Be aware that to visualize any results, you must already have run the simulation. You can use a LB Legend Parameters component to adjust the legend according to your simulation. By browsing your mouse over the different inputs of the LB Legend Parameters component, you can see which are the parameters that you can set each time. Define the graph title and used measurement units in a panel and connect those to the LB Legend Parameters component. 

• Use a LB Spatial Heatmap component.

• Connect the ‘results’ from the HB Daylight Factor simulation component to the ‘_values’ input.
• Connect the ‘mesh’ result from the HB Sensor Grid from Rooms component to the ‘_mesh’ input.
• Adjust legend parameters with a LB Legend Parameters component. 

• Define the graph title ‘Daylight Factor’ in a panel, then connect it to the ‘global_title_’ input of the LB Spatial Heatmap component.

• Define the measurement units of the metrics to ‘%’ in a panel. Connect it to the ‘legend_title_’ input of the LB Spatial Heatmap component.

Honeybee Daylight Simulation 4/10

Point-in-time simulation link copied

The second simulation method explained in this tutorial is the Point-in-time simulation. In this section you will learn what a Point-in-time simulation is, how to create a sky for the simulation, how to create and run the simulation and finally, how to post-process and visualize the results.

What is a Point-in-Time simulation?

Point-in-time simulations belong to the Sunlight analyses category and are a fundamental companion to the Daylight Factor. As the Daylight Factor tests only cloudy conditions, it does not give any indication about excessive sunlight issues, which are important for a more comprehensive evaluation of a building, especially to assess the design of shading elements.

Unlike the Daylight factor, the Sunlight access depends, firstly, on the location where the building is placed, since it affects the climate characteristics such as the amount and the angle of sunlight, and, secondly, on the time period for which the simulation is held.

Create the Sky for the simulation

In the Point-in-time simulation it is important to first create the sky parameters for the simulation. The point-in-time Radiance standard CIE sky will be used and set to a sunny day without clouds. Regarding the time points for the analysis, it is typical to select a few specific dates and (solar) times, usually 9:00, 12:00 and 15:00 of the following days:

• 21st December (winter solstice), when the sun is at its lowest altitude.
• 21st March or 21st September (equinoxes), when day and night have the same duration.
• 21st June (summer solstice), when the sun is at its highest altitude.

In this tutorial, we are going to run the simulation for 12.00, 21st of December. However, in order to summarise the annual variation, it is advisable to run the simulation for all the 3 hours and the 3 different characteristic days. 

We also need to define the orientation of the façade. In this example, we are going to set the north vector along the positive direction of Y axis, facing the opposite direction of the aperture normal. Additionally, the CIE sky requires to set the type of the sky. By moving your mouse on top of the CIE sky component inputs which you will create below, you can see the integers related to each different type. In this example, set the type to 0 for a sunny sky with direct sun.

To create the CIE sky for a specific time & day:

• Create HB CIE Standard Sky component.

HB-Radiance

Light Sources

HB CIE Standard Sky

• Connect the ‘location’ result from the LB Import EPW component to the ‘_location’ input.
• Create a Unit Y component and connect the ‘unit vector’ result to the ‘north_’ input.

Vector

Vector

Unit Y

• Create a Number Slider and set it to 0 in order to set the Sky type.

Params

Input

Number Slider

 

Create & Run the Point-in-Time Simulation

After you have created the sky for the simulation, to create and run the Point-in-Time Simulation you have to create a HB Point-In-Time Grid-Based component and input the ‘model’ result of HB Assign Grids and Views. You should pay attention to this, because it would create an error if you connected the ‘model’ result directly from the HB model component! Next, set the metric which you want to be computed by the recipe. By moving your mouse on top of the ‘_metric_’ input, you can see the integers related to each different metric. For this example, set the slider to 1 to calculate the Irradiance. Then you need to create a HB Radiance Parameter component to define the performance settings of the simulation. The recipe type of the radiance parameter should be set to 0 for running a Point-in-Time simulation. 

For the detail level use 2 (high detail) in this tutorial. For further information on which detail level of radiance parameters you should choose or how you can select customized values for the radiance parameters, check the “HB customized radiance parameters” tutorial.

To create and run the Point-in-time simulation: 

• Create an HB Point-In-Time Grid-Based component.

• Connect the ‘model’ result from the HB Assign Grids and Views component to the ‘_model’ input. 
• Connect the ‘sky’ result from the HB CIE Standard Sky component to the ‘_sky’ input.
• Create a Number Slider in order to set the metric to 1.

• Create an HB Radiance Parameter component.

• Use a Number Slider and set the value to 0 to define the type of recipe.

• Use a Number Slider and set it to 2 to define the detail level of the analysis.

• Create a False Start Toggle component and connect it to the ‘_run’ input of the HB Point-In-Time Grid-Based component.

• Double-click the False Start Toggle component in order to set it to ‘True’ and run the simulation.

It is advisable to use the Point-in-Time simulations mainly for qualitative results. If you want to get absolute values for illuminance or irradiance, it is advisable to run simulations that cover larger time periods (or even annually) as discussed in the next sections.

Visualize the results

For easier comprehension of the simulation, you can visualize the results. A very convenient way to visualize the results obtained from any type of Radiance simulation is to create a Spatial Heatmap. A Spatial Heatmap is a 2-dimensional representation of the data per grid point obtained through the simulation. In each point, the corresponding value is represented by a colour.

To create a spatial heatmap for the Point-in-Time Irradiance results you can use the LB Spatial Heatmap component and connect the results for the simulation to the values input. The component uses the mesh from the created grid result of ‘HB Sensor Grid from Rooms’ to visualize the results on. Be aware that to visualize any results, you must already have run the simulation. You can use a LB Legend Parameters component to adjust the legend according to your simulation. By browsing your mouse over the different inputs of the LB Legend Parameters component, you can see which are the parameters that you can set each time. Define the graph title and used measurement units in a panel and connect those to the LB Legend Parameters component. 

• Use a LB Spatial Heatmap component.

• Connect the ‘results’ from the HB Point-In-Time Grid-Based component to the ‘_values’ input.
• Connect the ‘mesh’ result from the HB Sensor Grid from Rooms component to the ‘_mesh’ input.
• Adjust legend parameters with a LB Legend Parameters component. 

• Define the graph title ‘Point-in-time Irradiance’ in a panel, then connect it to the ‘global_title_’ input of the LB Spatial Heatmap component.

• Define the measurement units of the metrics to ‘W/m2’ in a panel. Connect it to the ‘legend_title_’ input of the LB Spatial Heatmap component.

Honeybee Daylight Simulation 5/10

Annual Daylight simulation link copied

The third simulation explained in this tutorial is the Annual Daylight simulation. You will learn how to create and run an Annual Daylight simulation, how to calculate the spatial daylight autonomy and how to visualize and post-process the results.

What is annual daylight

The Annual simulations refer to Daylight, including both the direct Sunlight but also the indirect Skylight conditions. They follow the ‘Daylight Coefficients’ method for performing the simulation and the most commonly used metrics related to them are:

• Daylight Autonomy (DA): Indicates the percentage of occupied hours in a year during which the indoor illuminance is over a certain threshold
• Spatial Daylight Autonomy(sDA): indicates the percentage of the analysis grid which satisfies DA requirements for more than 50% of the occupied time
• Useful Daylight Illuminance (UDI): indicates the percentage of the occupied hours in a year during which the indoor illuminance is within a range of values (e.g., 300 and 3000 lx)

Other indicators related to Useful Daylight Illuminance (UDI) are:

• UDI_low, which reflects the percentage of time that each sensor grid is below the lower threshold of the Useful Daylight Illuminance.
• UDI_up, which reflects the percentage of time that each sensor grid is above the upper threshold of the Useful Daylight Illuminance.

Create & Run the Annual Daylight Simulation

Starting with the creation of the Annual Daylight simulation, you need to create a HB Annual Daylight  component and input the ‘model’ result of HB Assign Grids and Views. You should pay attention to this, because it would create an error if you connected the ‘model’ result directly from the HB model component!   You also need to define the north of the location. In this tutorial, the north vector will be set along the positive direction of the Y axis, facing the opposite direction of the aperture normal. Then you need to create a HB Radiance Parameter component to define the performance settings of the simulation. The recipe type of the radiance parameter should be set to 2 for running an Annual Daylight simulation. 

For the detail level use 2 (high detail) this tutorial. For further information on which detail level of radiance parameters you should choose or how you can select customized values for the radiance parameters, check the “HB customized radiance parameters” tutorial.

To create and run the Annual Daylight Simulation:

• Create an HB Annual Daylight component.

• Connect the ‘wea’ result from the HB WEA from EPW to the ‘_wea’ input.
• Connect the ‘model’ result from the HB Assign Grids and Views component to the ‘_model’ input. 
• Create a Unit Y component and connect the ‘unit vector’ result to the ‘north_’ input.

• Create an HB Radiance Parameter component.

• Use a Number Slider and set it to 2 to define the type of recipe.

• Use a Number Slider and set it to 2 to define the detail level of the analysis. 

• Create a False Start Toggle component and connect it to the ‘_run’ input of the HB Annual Daylight component.

• Double-click the False Start Toggle component in order to set it to ‘True’ and run the simulation.

Annual Daylight Simulation

For each of the daylight simulations you can find additional information and default settings by hovering over the component.  

Spatial Daylight Autonomy

Following the previous step of running the Annual Daylight simulation you get results regarding values of the DA, cDA and UDI, as mentioned earlier. You can use the DA values obtained through the Annual Daylight simulation in order to calculate the Spatial Daylight Autonomy by following these steps:

Visualize the results

For easier comprehension of the simulation, you can visualize the results. A very convenient way to visualize the results obtained from any type of Radiance simulation is to create a Spatial Heatmap. A Spatial Heatmap is a 2-dimensional representation of the data per grid point obtained through the simulation. In each point, the corresponding value is represented by a colour.

To create a spatial heatmap for the DA results you can use the LB Spatial Heatmap component and connect the results for the calculated DA to the values input. The component uses the mesh from the created grid result of ‘HB Sensor Grid from Rooms’ to visualize the results on. Be aware that to visualize any results, you must already have run the simulation. You can use a LB Legend Parameters component to adjust the legend according to your simulation. Given that the results from this simulation are percentages (such as DA, UDI), it is useful to set the min and max of the legend to 0 and 100 respectively so that the heatmaps are directly comparable. By browsing your mouse over the different inputs of the LB Legend Parameters component, you can see which are the parameters that you can set each time. Define the graph title and used measurement units in a panel and connect those to the LB Legend Parameters component. 

To create a spatial heatmap for the sDA results you can use the LB Spatial Heatmap component and connect the results for the calculated sDA pass & fail to the values input. The Spatial Daylight Autonomy gives out the results of pass & fail for each value in comparison to the target minimum DA value set in the simulation. Given that the results are either pass or fail, it is useful to set the min and max of the legend to 0 and 1 respectively to create a clear visual.

• Use a LB Spatial Heatmap component.

• Connect the ‘DA’ from the HB Annual Daylight component to the ‘_values’ input.
• Connect the ‘mesh’ result from the HB Sensor Grid from Rooms component to the ‘_mesh’ input.
• Adjust legend parameters with a LB Legend Parameters component. 

• Define the graph title ‘Daylight Autonomy’ in a panel, then connect it to the ‘global_title_’ input of the LB Spatial Heatmap component.

• Define the measurement units of the metrics to ‘%’ ( or ‘pass/fail’ for the sDA ) in a panel. Connect it to the ‘legend_title_’ input of the LB Spatial Heatmap component.

Following the same steps, with the results of the Annual Daylight simulation you can also find and visualize the UDI adequate range results, UDI_up and UDI,low results. To do that you simply need to connect to the respective results from the HB Annual Daylight component to the ‘_values’ input of the LB Spatial Heatmap component. Set the ‘global_title_’ input according to which result you are visualizing.

In the case of the Spatial Daylight Autonomy (sDA) make sure that you connect the ‘pass_fail’ result and NOT the ‘sDA’ result of the HB Spatial Daylight Autonomy component to the ‘_values’ input. This is because the information per grid point is included on the ‘pass_fail’ result.

Honeybee Daylight Simulation 6/10

Annual Irradiance Simulation link copied

The fourth simulation method in this tutorial is the Annual Irradiance simulation. With Annual Irradiance you can simulate what is the hourly solar irradiance measured at each sensor of your HB model sensor grid. In this section you will learn how to create and run this type of simulation and how to post-process the result.

Annual Irradiance Simulation is more commonly used to simulate over outdoor surfaces, e.g. windows, facades or PV panels. In this example, we will go through the steps of creating and running this simulation for the same HB model as the other simulations, using the interior surface of the floor.

Create & Run the Annual Irradiance Simulation

In this tutorial, the HB Annual Irradiance component will be used for this reason and not the HB Cumulative Radiation, since the approach followed for the calculation is considered to produce more accurate values. First, you need to create a HB Annual Irradiance component and connect it to the WEA object to get the weather data. Then, input the ‘model’ result of HB Assign Grids and Views. You should pay attention to this, because it would create an error if you connected the ‘model’ result directly from the HB model component! Moreover, you need to define the orientation of the design. In this tutorial we are going to set the north vector along the positive direction of Y axis, facing the opposite direction of the aperture normal. 

Then you need to create a HB Radiance Parameter component to define the performance settings of the simulation. The recipe type of the radiance parameter should be set to 2 for running an Annual Irradiance  simulation.  For the detail level use 2 (high detail) this tutorial. For further information on which detail level of radiance parameters you should choose or how you can select customized values for the radiance parameters, check the “HB custom radiance parameters” tutorial.

To create and run the Annual Irradiance simulation you need to follow these steps: 

• Create an HB Annual Irradiance component.

• Connect the ‘wea’ result from the HB WEA from EPW component to the ‘_wea’ input.
• Connect the ‘model’ result from the HB Assign Grids and Views component to the ‘_model’ input. 
• Create a Unit Y component and connect the ‘unit vector’ result to the ‘north_’ input.

• Create an HB Radiance Parameter component.

• Use a Number Slider and set it to 2 to define the type of recipe.

• Use a Number Slider and set it to 2 to define the detail level of the analysis. 

• Create a False Start Toggle component and connect it to the ‘_run’ input of the HB Annual Irradiance component.

• Double-click the False Start Toggle component in order to set it to ‘True’ and run the simulation.

Visualize the results

For easier comprehension of the simulation, you can visualize the results. A very convenient way to visualize the results obtained from any type of Radiance simulation is to create a Spatial Heatmap. A Spatial Heatmap is a 2-dimensional representation of the data per grid point obtained through the simulation. In each point, the corresponding value is represented by a colour.

To create a spatial heatmap for the Annual Irradiance results you can use the LB Spatial Heatmap component and connect the results for the simulation to the values input. The component uses the mesh from the created grid result of ‘HB Sensor Grid from Rooms’ to visualize the results on. Be aware that to visualize any results, you must already have run the simulation. You can use a LB Legend Parameters component to adjust the legend according to your simulation. By browsing your mouse over the different inputs of the LB Legend Parameters component, you can see which are the parameters that you can set each time. Define the graph title and used measurement units in a panel and connect those to the LB Legend Parameters component. 

• Use a LB Spatial Heatmap component.

• Connect the ‘results’ from the HB Point-In-Time Grid-Based component to the ‘_values’ input.
• Connect the ‘mesh’ result from the HB Sensor Grid from Rooms component to the ‘_mesh’ input.
• Adjust legend parameters with a LB Legend Parameters component. 

• Define the graph title ‘Cumulative radiation’ in a panel from, then connect it to the ‘global_title_’ input of the LB Spatial Heatmap component.

• Define the measurement units of the metrics to ‘kWh/m2’ in a panel. Connect it to the ‘legend_title_’ input of the LB Spatial Heatmap component.

Honeybee Daylight Simulation 7/10

Direct Sun Hours Simulation link copied

The Direct Sun Hours simulation is the last daylight simulation explained in this tutorial. This simulation refers to the total number of hours that direct sun is received by each grid sensor of the HB model. In this section you will learn how to create and run a Direct Sun Hours simulation and how to post-process the results.

Create & Run the Direct Sun Hours Simulation

To create and run a Direct Sun Hours simulation you first need to create an HB Direct Sun Hours component and connect it to the WEA object to get the weather data. Then, input the ‘model’ result of HB Assign Grids and Views. You should pay attention to this, because it would create an error if you connected the ‘model’ result directly from the HB model component! After that you need to define the orientation of the design. In this tutorial we are going to set the north vector along the positive direction of Y axis, facing the opposite direction of the aperture normal.

The Direct Sun Hours simulation is created with the following steps: 

• Create an HB Direct Sun Hours component.

• Connect the ‘wea’ result from the HB WEA from EPW component to the ‘_wea’ input.
• Connect the ‘model’ result from the HB Assign Grids and Views component to the ‘_model’ input. 
• Create a Unit Y component and connect the ‘unit vector’ result to the ‘north_’ input.

• Create a False Start Toggle component and connect it to the ‘_run’ input of the HB Direct Sun Hours component.

• Double-click the False Start Toggle component in order to set it to ‘True’ and run the simulation.

Visualize the results

For easier comprehension of the simulation, you can visualize the results. A very convenient way to visualize the results obtained from any type of Radiance simulation is to create a Spatial Heatmap. A Spatial Heatmap is a 2-dimensional representation of the data per grid point obtained through the simulation. In each point, the corresponding value is represented by a colour.

To create a spatial heatmap for the Direct Sun Hours results you can use the LB Spatial Heatmap component and connect the results for the simulation to the values input. The component uses the mesh from the created grid result of ‘HB Sensor Grid from Rooms’ to visualize the results on. Be aware that to visualize any results, you must already have run the simulation. You can use a LB Legend Parameters component to adjust the legend according to your simulation. By browsing your mouse over the different inputs of the LB Legend Parameters component, you can see which are the parameters that you can set each time. Define the graph title and used measurement units in a panel and connect those to the LB Legend Parameters component. 

• Use a LB Spatial Heatmap component.

• Connect the ‘results’ from the HB Direct Sun Hours component to the ‘_values’ input.
• Connect the ‘mesh’ result from the HB Sensor Grid from Rooms component to the ‘_mesh’ input.
• Adjust legend parameters with a LB Legend Parameters component. 

• Define the graph title ‘Direct sun hours’ in a panel, then connect it to the ‘global_title_’ input of the LB Spatial Heatmap component.

• Define the measurement units of the metrics to ‘hours’ in a panel. Connect it to the ‘legend_title_’ input of the LB Spatial Heatmap component.

Honeybee Daylight Simulation 8/10

Possible errors and warnings link copied

When running the daylight simulation, multiple errors or warnings can occur. The solutions of some errors related to Radiance are shown below. Note that another error can occur but could be related to the set-up of the HB model, therefore check the tutorial about the HB model set-up for other error possibilities. Additionally, warnings can appear while running a daylight simulation, which sometimes could be ignored. 

No Radiance installation

An error that might occur when you try to run a daylight simulation for the first time or after updating/re-installing Ladybug, is the error: 

‘Solution exception: No Radiance installation was found on this machine’.

It states that the Radiance installation was not found. This has to do with the installation of the Ladybug plug-in. To solve this, manually install the compatible version of radiance for your Ladybug from GitHub. Make sure that when manually installing Radiance you do not change the destination of the installation, otherwise the program might not be able to find the package. 

Failed to collect data

An error that might occur when you try to run a daylight simulation for the first time or after updating/re-installing Ladybug, is the error:

‘Input parameter _model failed to collect data!’. 

It states that the Honeybee component did not collect any data to be able to run the simulation. This is a warning that might appear when you open someone else’s GH script. In general, this is a warning you can ignore. If you want this warning to be resolved, you must replace the component. In this case recreate or copy/paste the HB Annual Daylight component, connect again the inputs and it should work properly.  

Honeybee Daylight Simulation 9/10

Conclusion link copied

In this tutorial you learned how to perform a daylight simulation using Ladybug and Honeybee. By reaching the end of the tutorial you are now able to prepare a Honeybee room for a daylight simulation by assigning the material optical properties, creating a sensor grid and importing the relevant weather data. Moreover, you learned how to perform 5 types of daylight simulation – Daylight factor simulation, Point-in-time simulation, Annual daylight simulation, Annual irradiance simulation, Direct sun hours simulation – and post-process their results for better visualization. Following this tutorial, you are ready to perform an energy analysis simulation. 

Final exercise file

Here you can download the complete Grasshopper script with all 5 daylight simulations. For your own use you can remove the unnececary simulations. 

Honeybee Daylight Simulation 10/10

Useful Links link copied

Linked tutorials

Previous tutorial within Honeybee analysis explaining the set-up of the room:

Useful tutorials for the Honeybee daylight analysis:

Follow up tutorials

This next tutorial uses the same room set-up and the Honeybee model to create and perform the energy analysis and simulation:

External Links

• Daylight simulation script runthrough – by Mathias Sønderskov
• Hydra repository of examples
• Ladybug Forum

Other Educational Resources

• NLITED Educational Platform
• Repository with presentations from annual Radiance workshops

Useful links

Radiance for Ladybug download from github:

• Radiance for Ladybug github