Wonderful Ladybug Tools Community,
We are happy to announce another release of the Ladybug Tools (LBT) for Grasshopper (version 1.3.0)!
You can download it from Food4Rhino and install by following the instructions here.
For people who already have an older LBT plugin installed, the Food4Rhino download for version 1.3.0 includes an uninstaller.gh file that can be used to completely uninstall your old version. Given all of the changes that we have made to the plugin over the last few months, we recommend using this uninstaller and then reinstalling the plugin in order to ensure everything on your system is up to date. Note that the uninstaller.gh will remove any custom standards you may have manually added to the ladybug_tools/honeybee_standards folder and so you should make a copy of them before running the uninstaller. If you forget, the uninstaller automatically copies them to C:\Users\[USERNAME]\.honeybee_standards before it runs. And don’t forget to update to the compatible version of OpenStuido and Radiance listed in the compatibility matrix.
Since the last release, we have standardized several aspects of the Honeybee JSON file schema and core libraries in preparation for the release of the Polliation Rhino Plugin and Pollination Revit Plugin. People who have been saving their Honeybee models into the HBJSON format to easily share models between machines (and take advantage of the future ecosystem around HBJSON) can use the new HB Update HBJSON component to upgrade their old HBJSON files to the latest version.
The biggest update that we have since the previous release is that effectively all Legacy Radiance capabilities are now supported in LBT version 1.3. This includes all Legacy Radiance recipes and all result processing capabilities. There are a few Legacy features left to add, particularly in Ladybug, but we will be working on these over the next few months as we add more advanced energy and radiance features.
Now, on to the exciting part!
Overall Features
Searchable Documentation for Components
Many people on this forum are aware that we have documentation for the Ladybug Tools Python SDK but also know that this SDK documentation is at a level of detail far beyond what most people need when working in Grasshopper. So we are happy to say that we now have searchable documentation devoted solely to the Grasshopper components of the LBT plugin.
Click to read more
We plan to keep this component documentation updated with every stable release of the plugin. The hope is that, by linking to pages within this documentation, people in forum discussions can reference components in a way that is both more detailed and more stable than simply stating the component name or copy/pasting an image of it.
Better Recipe Reporting and Visualization
It became clear to us after the last release that, while our new methods for executing recipes are powerful in the way they manage parallel tasks, they lacked several key reporting features to make it clear how the recipe execution happens. Accordingly, the latest recipes in the new LBT plugin will give a clear report of steps that have failed whenever anything goes wrong. We also added a new component called HB Visualize Recipe Execution, which can be used to visualize the execution of a recipe within a web browser.
Click to read more
The component only needs to be run once in order to open a web page that can be refreshed to display the latest progress of the recipe execution. As the video below shows, users should select the Let[RECIPE_NAME]Fly task in the interface that pops up to see the progress of the whole recipe. Clicking on the “graph” of that task and un-checking “hide done” will show the status of all recipe steps. We want to highlight that this convenient browser-based UI was not developed by us and is available to us all because we use the open source luigi package developed by Spotify in order to execute the tasks of all recipes. So Spotify deserves a lot of credit here for open sourcing a widely useful tool for workflow execution.
Last among the new recipe features we added was the ability to execute all recipes silently, which should be helpful for users simulating large parametric runs.
General Improvements for Parallel Processing
Our historic approach to parallel processing has been varied but this LBT 1.3 release standardizes how such parallelization is implemented across the plugin. Now, all parallel_ boolean inputs have been replaced with a _cpu_count_ that allows you to select the specific number of processors used by the component. In all cases, if you leave this _cpu_count_ unassigned, it will automatically default to using one less processor than the total number of processors available on your machine. This is true whether you are simulating a recipe, performing a Ladybug Direct Sun/Radiation calculation, or intersecting solids to build a Honeybee model.
Click to read more
We felt that this setup provided everyone with the best experience since the previous parallel_ option would easily take over the machine and interfere with other tasks people wanted to do while simulations were running. Also, we know many users are not aware of the number of processors on their machines (or are designing Grasshopper definitions for machines with an unknown number of CPUs). So using the new default should be suitable for these cases.
Energy Features*
*Most of the energy features listed below apply to both the Dragonfly workflows and the HB-Energy workflows.
gbXML Import and Export
Exporting and importing Green Building XML (gbXML) files is critical for interoperability throughout the Building Energy Modeling (BEM) ecosystem. So we are happy to announce two new components: the HB Dump gbXML component and the HB Load gbXML component. The components do exactly what they sound like and the Load gbXML component can also be used to import OSM and IDF files into honeybee. Since the Ladybug Tools plugin sits within the robust geometry engine of Rhino, it can be used to produce clean geometry for other BEM interfaces that have simpler geometry engines. We have already tested the export of such honeybee-generated gbXMLs into IES and verified that the translation happens smoothly.
Click to read more
The gbXML translators within Honeybee are leveraging those of OpenStudio under the hood. So you can generally expect that energy model characteristics that are translated by OpenStudio will also be translated by Honeybee. This includes the primary characteristics of all geometry (eg. boundary conditions, face types, and all zoning). It also includes constructions and material layers. Lastly, the gbXML export includes loads for people/equipment/lighting and the thermostat setpoints (on the design day), which should be particularly helpful for export to HVAC sizing software such as Trane TRACE.
Programs, ConstructionSets, and HVAC for ASHRAE 2016 and 2019
In accordance with the upgrade to OpenStudio 3.2 that happened in this release, we were able to expose the new ProgramTypes, ConstructionSets, and HVAC templates for the latest versions of the ASHRAE standard that forms the basis of most international building energy codes. Specifically, we now have templates for ASHRAE 90.1, 2016 (IECC 2018) and ASHRAE 90.1, 2019 (IECC 2021). Assigning the new standards is the same as previous workflows (there is a new HB Building Vintages component with the new options). When building vintages are not selected for a particular program, construction set or HVAC, the plugin automatically defaults to the latest standard (ASHRAE 90.1, 2019).
Support for Building Mix Programs
While the state-of-the-art way to build energy models is to represent separate parts of a building with distinct Rooms and room ProgramTypes, many of us are unable to do this in early stages when working with building massing. In these cases, it’s preferable to use a single ProgramType object to represent an entire building mix and, historically, this requires a list of program ratios in order to use the HB Blend Programs component to create this building mix program. However, sometimes, even this list of program ratios is not available and it is for this reason that we’ve added support to plug the Building Program directly into the components that create Honeybee Rooms (or Dragonfly Buildings).
Click to read more
The ratios of room programs for these full-building mixes were derived from the US Dept. of Energy Commercial Reference Buildings by analyzing the floor area used by each room program in the full model. All blended room programs will be for the latest version of ASHRAE 90.1 (currently 2019). These new building mixes should be particularly helpful in urban workflows with Dragonfly when one only knows the usage of a building and not the breakdown of individual room programs.
Simple Daylight Controls
EnergyPlus’s simple daylight controls were a popular feature of Honeybee Legacy and so we are happy to say that they are now implemented in LBT honeybee via the HB Apply Daylight Control component. We’ve exposed a few more inputs that should make it easier to model a wider range of daylight dimming technologies.
Internal Masses
Another highly-requested legacy feature was the ability to add additional thermal mass to Rooms, which can have significant impacts on peak loads and thermal comfort. So we have added support for this via the HB Internal Mass component
Multi-State Dynamic Window Constructions
Historically, the only way to model dynamic building elements like electrochromic glass was by using the HB Window Construction Shade component or equivalent legacy workflows. However, these only allow a maximum of two states (on and off) meaning that many technologies cannot be well-represented this way. Accordingly, LBT 1.3 includes a Window Construction Dynamic component that can represent dynamic constructions with any number of dynamic states.
Click to read more
At the moment, a schedule is the only way to set the dynamic state at each timestep but we could potentially add more control strategies in the future if there is demand for them.
Miscellaneous New Inputs and Outputs
Throughout the plugin, we exposed various new inputs and outputs on components. To list a few of particular note:
- We added two new inputs for All-Air and DOAS HVAC systems that enable automatic demand-controlled ventilation. For DOAS systems, you can even set availability schedules to shut off the whole ventilation system for unoccupied times. These should help with modeling some of the most common energy conservation strategies used with these systems.
- It is now possible to set ventilation rates in terms of ACH on the HB Apply Load Values component and specify absolute flow rates in m3/s on the HB Apply Absolute Loads component.
- We exposed a Solar Heat Gain Coefficient (SHGC) output on the Deconstruct Construction component.
- There’s a new component to convert infiltration rates measured in blower door tests to those that one might experience during typical building operation.
- The Airflow Network (AFN) component has a new input to change the Delta Pressure used in converting from static infiltration rates to the dynamic ones of the AFN, which will also help match AFN behaviour with blower-door measurements.
Radiance Features
Point-in-Time Grid and View Recipes
Point-in-time (PIT) simulations are usually the first recipes that new Radiance users run as they are important for understanding the fundamentals of daylight modeling. Accordingly, we are happy to say that LBT 1.3 has full support for both grid-based and view(image)-based PIT recipes in version 1.3. They are supported via the Point-In-Time Grid-Based and Point-In-Time View-Based components.
Click to read more
Supporting these recipes included the standardization of the Light Sources components to produce a wide variety of Radiance skies (CIE, ClimateBased, Custom). It also included a Visualize Sky component to check the sky properties. View-based results can be visualized using the “LB Image Viewer,” which has now been moved from Legacy to the LBT plugin, and gri-based results can be visualized with the LB Spatial Heatmap component like the other recipes using sensor grids.
New “Check Scene” Component
While the Point-in-Time View recipe can be used to produce high-quality Radiance renderings (with parallelization, overture calculations, and other bells and whistles), it can have a high overhead for simple use cases like quickly checking the properties of a Radiance scene. For this reason, we have added the HB Check Scene component, which uses streamlined methods to render quick, low-quality images for such purposes.
Click to read more
The component will render the current Rhino viewport with a cloudy sky by default but both the view and sky can be customized as needed.
New Image Processing Components
With the new ways to produce images, it was critical to include several components to process and interpret the images. To this end, we have added 3 components that essentially replicate legacy capabilities:
- HB False Color - to convert HDR images into falsecolor versions with a legend.
- HB HDR to GIF - to convert HDR images into more portable GIF images.
- HB Glare Postprocess - to compute Daylight Glare Probability (DGP) and other glare metrics from fisheye HDR images.
Click to read more
We have also added a new type of image-processing component that can perform a variety of adjustments on Radiance images called HB Adjust HDR component. The component can add custom text labels to the bottom of images and adjust the exposure of images to mimic the perception of the human eye.
Radiation and Sky View Recipes
While these recipes aren’t the most novel as they essentially replicate Legacy capabilities, they are nevertheless important. The HB Cumulative Radiation recipe uses the same sky-patch-based methods that are used in the LB Incident Radiation component but can account for ambient bounces. The HB Sky View component effectively makes the capabilities of the legacy “Vertical Sky Component” (VSC) recipe more generalizable. When used with vertically-oriented sensor grids with the cloudy_ option, the recipe will compute VSC. But, if all defaults are left as they are, the component will simply compute the fraction of the sky dome seen by each sensor.
Recipe for Annual Irradiance
In addition to the cumulative radiation recipe, the 1.3 release also includes an Annual Irradiance component, which can be used for cases where solar irradiance at each time step of a time period is needed. The fundamental calculation of this recipe is the same as that of Annual Daylight in that a detailed accounting of direct sun is computed at each timestep. However, the recipe computes broadband solar irradiance in W/m2 instead of visible illuminance in lux.
Click to read more
In addition to outputting detailed matrices of W/m2 at each time step, the following values are also recorded for each sensor point:
-
average_irradiance- The average irradiance in W/m2 over the Wea time period -
peak_irradiance- The highest irradiance value in W/m2 during the Wea time period -
cumulative_radiation- The cumulative radiation in kWh/m2 over the Wea time period
The peak_irradiance value is suitable for assessing the worst-case solar load on cooling design days or the highest radiant temperatures that occupants might experience over the time period of the input Wea.
Annual Result-Parsing Components
After several users requested the ability to parse and analyze the hourly results from Annual Daylight (and now also Annual Irradiance) simulations, we have added 4 components that assist with such workflows. All components take the .ill files produced by these simulations and output various statistics on them. The new components include the following:
- HB Annual Results to Data - imports the hourly lux or irradiance values for individual sensors to data collections for visualization/analysis with Ladybug.
- [HB Annual Average Values(https://docs.ladybug.tools/hb-radiance-primer/components/4_results/annual_average_values) - computes the average lux or irradiance for an hour or over a time period.
- HB Annual Cumulative Values - computes the cumulative radiation (or lux) over a time period.
- HB Annual Peak Values - computes the peak irradiance or lux over a time period.
Click to read more
The release also includes the HB Daylight Control Schedule component, which can be used to get electric light dimming schedules for use with Honeybee energy simulations. Lastly, we added a HB Spatial Daylight Autonomy component to make it easier to compute sDA from lists of DA results.
Support for BSDF Modifiers
Many users know that Bidirectional Scattering Distribution Functions (BSDFs) are becoming an increasingly popular way to model complex materials like blinds, and light diffusing materials in Radiance. As a result, we are happy to say that BSDF modifiers now work for all Radiance recipes that currently exist in the plugin.
Missing Legacy Features Targeted for the Next Stable Release
More Ladybug Visuals - We are still missing important ladybug visualizations such as radiation-related graphics, the wind profile, and analyses like shade benefit. We hope to get these in for the next release.
Improve Thermal Mapping Accuracy - We had the goal of improving the HB-Energy thermal mapping recipes in this release but we were not able to implement it in time. The current simplified longwave calculation in the LBT thermal maps is still the only thing preventing us from saying that the LBT thermal maps are a clear improvement over their Legacy counterpart. So we aim to have this implemented in the next release.
Dynamic Radiance Window Groups (3 and 5 Phase) - At the moment, there are components for dynamic Aperture and Shade groups but they are not used in any recipe. We hope to have 3-5-Phase and 5-Phase recipes implemented in the next release, which will be able to make use of these features to model dynamic shades.
Additional Energy Features - We are currently missing a few important energy simulation features like radiant HVAC, detailed service hot water systems, photovoltaics and more issues that can be seen on the honeybee-energy Github. We hope to work our way further down this list before the next release.
