Ladybug Tools for Grasshopper 1.0.0 Release

Dearest Ladybug Tools Community,

We are happy to announce the first stable release of the new Ladybug Tools (LBT) plugin for Grasshopper (version 1.0.0)!

You can download it from Food4Rhino and install by following the instructions here. Sample files are included within the zip file that you download from Food4Rhino. We will be posting more content over the next month about how to use the LBT plugin and how to take advantage of its features. If you want to be in the loop about all of these posts, be sure to follow us on LinkedIn and Twitter.

The new LBT plugin includes Ladybug, Honeybee, and Dragonfly. Since July, the Legacy plugin has been installed under the LB-Legacy and HB-Legacy tabs so the Ladybug Tools plugin can be installed alongside the latest Legacy Plugin without issues. However, the LBT Plugin is intended to fully replace the Legacy Plugin in the long term. While this LBT release is still missing 10%-20% of legacy features (see below), we feel it is good enough for many of you to start converting your legacy workflows and begin taking advantage of the numerous enhancements and new features listed below. We will be working hard to implement the last of the missing features over the next few months and, for the time being, you shouldn’t experience any issues if you have to build Grasshopper definitions that mix Legacy and LBT components.

We also want to highlight that, just like Legacy, the LBT Plugin is completely free and open source. This includes the Grasshopper components, the Ladybug Tools core libraries, all the way down to the simulation engines and programming language. All the code for Ladybug Tools plugins and libraries are hosted under the Ladybug Tools GitHub organization.

With particular regard to the last point, we want to take a second and recognize that many of the features and enhancements listed below would not have been possible without the giants whose shoulders we stand on. We owe enormous thanks to many people at NREL (especially the OpenStudio, OpenStudio-Standards, and URBANoptTM development teams), the developers of EnergyPlus, Greg Ward and the developers of Radiance, the developers of Python, and the US Department of Energy. Not only have some of these groups provided funding that has made this release possible in the 2-year time frame that it took us to make this release but our code is just the icing on a massive software layer cake that these groups have been building for decades. Ladybug Tools has the privilege of being a user interface for the software that these groups have built and, as a result, it tends to receive an inordinate amount of recognition. But, as a community, let us all remember to express our gratitude to these groups and give them the credit they deserve wherever possible.

We also want to thank the many members of this community who assisted in testing the new plugins. Because of their efforts, this release is much more stable and bug-free than it would have been otherwise.

Now, on to the exciting part!

Plugin-Wide Enhancements

Speed / Performance

Almost everything in the new LBT plugins is faster than its legacy counterpart. In some cases, the difference is incremental while, in others, it is an order of magnitude. But we think everyone will find the plugins much faster, which not only enables greater productivity in building grasshopper definitions but also allows for the construction of much larger models.

Click to read more We want to highlight that almost all of these speed improvements are from better-written Ladybug Tools code and we have made a conscious effort to minimize any changes that affect the quality or accuracy of results. Much of the new-found performance comes from simple improvements like a streamlined approach for copying objects between components or not dumping large amounts of data into the Grasshopper interface unless requested. Changes like this have reduced many of the component runtimes to less than half of their legacy equivalent.

OS Independence and Support for Mac

We have heard the cries of anguish from the Mac users of our community and we are happy to say that LBT is completely functional in Rhino for Mac.

Click to read more This includes all Radiance and OpenStudio/EnergyPlus simulation capabilities, which can be run using the Mac versions of these engines. The Grasshopper plugin and core libraries running on Mac are exactly the same as the ones running on Windows. So you should not experience any differences in results between Mac and Windows and there should be no issues passing Grasshopper definitions back and forth between Windows and Mac machines.

Saving Objects to Files and Assembling Libraries of Standards

Some of you might be familiar with the legacy honeybee “Dump Objects” and “Load Objects” components, which could be used to save some objects into their own files. In LBT, we have taken this “save-ability” philosophy to the extreme such that almost any object that you create with the Grasshopper components can be saved into its own JSON file (or a JSON text string) that can be loaded up in another definition.

Click to read more

This includes all energy constructions + schedules, all radiance materials, and even entire honeybee Models that possess all their properties for both energy + radiance simulation. This “save-ability” allows you to easily build up a personal library of standards in JSON files that can be shared and installed by other users, making it easier to build libraries for specific building codes or an office-wide basis of design. Down the line, the JSON save-ability of Honeybee Models will also make it easier to share building designs across different CAD platforms and upload models to the cloud… but more on this later. In the meantime, more info in the JSON schema used to represent objects can be found on the honeybee-schema wiki.

Streamlined Workflows for Large Models

This release is the first where we are unveiling the new LBT Dragonfly, which has been reborn from its legacy counterpart as a tool for creating large-scale energy and radiance models.

Click to read more

All Dragonfly models are fully translatable into Honeybee models but the Dragonfly schema is fundamentally a 2D representation of building geometry, where all rooms are assumed to be extrusions of floor plates. This makes it much easier to build models in cases where such extruded-floor-plate logic applies and alleviates many legacy pain points of large model-building, such as intersecting + solving adjacency, duplicating repeated stories over the height of a building, auto-generating plenum spaces, and even parallelizing the simulation of different parts of a model. Dragonfly also includes a direct connection to URBANopt SDK that has been developed by NREL… but more on that later. More info on the Dragonfly schema can be found on the dragonfly-schema wiki.

Improved Visualization and More Customization

Those of you who enjoy customizing your Ladybug Tools graphics will be happy to hear that the Legend Parameters have gotten a full make-over for the LBT plugin. Now, there’s almost nothing about your legends that you cannot customize, whether it’s displaying text instead of numbers, flipping the legend to be horizontal instead of vertical, or changing the legend to use gradients instead of segments.

Click to read more

We have also improved the component that orients the legend to the camera to make it easier to include your legends in 3D views. We hope that this new customization will enable many of you to eliminate extra post-processing steps, such as cleanup in Photoshop or Illustrator. Your legends can now be as beautiful right out of the component as your designs are!

Better QAQC Tools

Any experienced modeler knows that checking assumptions for quality control often accounts for a huge fraction of the model-building process. This is why we are happy to announce that Honeybee now has an entire tab devoted to visualizing and checking model attributes.

Click to read more

Among the highlights of the new tab are components for coloring Rooms and surfaces with attributes (see below) as well as super-fast “labeling” components for placing text labels on honeybee objects. It’s also worth noting that the geometry that you see output from these visualization components is exactly the same as that which is going off to the simulation engines. In Legacy, there was a lot of implicit model “re-evaluation” that was done upon export to simulation engines in order to translate the Zoo of Rhino Breps (NURBs, Spheres, etc) to a planar format. This made it difficult to understand what geometry was actually being simulated but, now the 1-to-1 mapping between Honeybee objects and the simulation engines should make it much easier to check your geometry and know that it is simulating correctly.

Ladybug Tools SDK to Create Your Own Components

One of the aspects of the new Ladybug Tools Plugin that we are particularly proud of is that most of of the code used by the plugin exists in reusable core libraries that have been organized and documented in a Software Development Kit (SDK), much like RhinoCommon SDK or OpenStudio SDK. This makes it much easier to build off of the Ladybug Tools Plugin to create your own components using GHPython (or even CPython if you want to go outside Grasshopper).

Click to read more

Simply typing an import statement for the core libraries like import ladybug gives you access to all of the plugin’s time-series data management tools (analysis periods, conditional statements), visualization libraries, climate graphics, and more. There’s no need to go digging through the source code to make use of these capabilities thanks to search-able documentation for the SDK like you can see here for the honeybee-energy library. For those of you looking to learn more about this, we will have a full post on this topic coming soon. So stay tuned!

[COMING SOON] Ladybug Tools Plugins for Rhino and Revit

While this release only includes a user interface (UI) for Grasshopper, you should know that we now have plugins undergoing testing for Revit and standalone Rhino (without Grasshopper).

Click to read more

These Revit + Rhino plugins can be used to build energy and radiance models and they use the same file schema and core libraries as Ladybug Tools for Grasshopper, which means it will be easy to load up, edit and simulate models built from these plugins in Grasshopper. So updating your workflows from Legacy to LBT will put you in a good position to participate in this new CAD-integrated software ecosystem that is on the horizon.

The interface for creating constructions in the Rhino and Revit plugins

Rhino_Revit Schedule UI
The interface for creating schedules in the Rhino and Revit plugins

The Revit sample model; exported from Revit and loaded into Grasshopper

[AVAILABLE BY REQUEST] Single-Click Installer

Single-click executable installers were among the most requested features in a survey we did last year and we are happy to say that we are offering such installers for the LBT Grasshopper plugin. Though the Food4Rhino installation process is completely free, we are selling these single-click installers since they are intended to save time and money by making the installation process faster, easier, and error-free. If you are interested in purchasing the installer, please email

Click to read more

Benefits of the single-click installer include:

  • Installation of all plugins and simulation engines in minutes not hours.
  • Avoid back-and-forth communication with IT departments by installing everything at once instead of in multiple steps.
  • Avoid the need to repeat installation steps from accidental install of incompatible versions of the plugin and simulation engines.
  • Install only stable releases of the plugin that have undergone rigorous testing for bugs by the developers of Ladybug Tools.
  • Maintain compatibility across the machines of an organization, allowing for ease of file exchange between machines.
  • Use a single signed and certified executable instead of the (sometimes) unsigned executables distributed by US national labs for the various simulation engines.


New Energy Features


One of the most beloved features of OpenStudio is the ability to create construction sets that specify default constructions for different types of surfaces (Walls, Roofs, Windows) using a single object that can be applied broadly across the Model. These ConstructionSet objects are now a part of HB-Energy, which means you can create them, apply them to Honeybee Rooms, and save them into a JSON for your personal standards library.

Click to read more

HB-Energy also ships with a library of standard ConstructionSets that conform to different versions of the International Energy Conservation Code (IECC) and ASHRAE 90.1. For each version of the IECC, there are ConstructionSets for a range of climate zones (from hot to cold), making it easier to set up your energy models from a standard that is sensitive to the climate of your project. More information on HB-Energy ConstructionSets can be found on the honeybee wiki.


Yet another great feature of OpenStudio that was partially implemented in Legacy were programs (or OpenStudio space types) that allow you to specify default loads and schedules using a single object that can be applied to multiple spaces or Rooms. These ProgramType objects are now a full-class citizen of HB-Energy, which means you can create them, apply to Honeybee Rooms, and even blend into mixed programs. Or you can save them to a JSON file and build up a library of ProgramTypes for the building programs that your office designs the most.

Click to read more

Just like Legacy, HB-Energy ships with a library of standard ProgramTypes derived from the US Dept of Energy’s Commercial Reference Buildings. The one difference is that there are several more programs available in the LBT plugin’s standards library compared to Legacy. More information on HB-Energy ProgramTypes can be found on the honeybee wiki.

100+ Detailed HVAC Templates

The Legacy plugin had ~15 detailed HVAC templates that covered the bases for some of the most common contemporary HVAC systems but many crucial systems were missing. The new HB-Energy not only has almost 100 more HVAC systems but the default efficiencies for the various pieces of HVAC equipment now conform to IECC/ASHRAE standards.

Click to read more

As with Legacy, all ASHRAE Appendix G systems are supported but there are now several options for the plants of these systems. For example, many of the new HVAC templates come with options for using central heat pumps and several have support district heating + cooling plants. There are also a wide range of HVAC templates have been added for residential applications. We’ll have a longer post on these templates soon along with some tutorial videos that help you pick the right template for different situations.

Airflow Network

You have been asking us for years and we’re now happy to say that HB-Energy supports the EnergyPlus Airflow Network (AFN)!

Click to read more

While the AFN is fundamentally complex, we have tried to make it easy to start by making a 1-to-1 mapping between the AFN and the simple ventilation objects that honeybee has historically used (and that honeybee still uses by default). So, if you set up your model with operable windows and a control strategy for when the windows open, you can model that exact same setup with the AFN. We will have a longer post about this later so stay tuned!

True AirBoundaries

Throughout the development of Legacy, EnergyPlus had no way to specify true AirBoundary surfaces between Zones and, for this reason, legacy air walls were more like a sheet of plywood across which air could mix but sun and radiant heat could not pass. All of this changed with EnergyPlus 9.3, which introduced the Construction:AirBondary and we are happy to say that HB-Energy fully supports these AirBoundary constructions.

Click to read more

Now, in HB-Energy, you can simulate two rooms connected by an AirBoundary and know that the sun can pass from one to another and that surfaces can radiate heat to one another across the boundary. This will end up being particularly helpful in improving the accuracy of microclimate maps (currently under development) but it also has a range of immediately-usable applications. For example, you can now model a large indoor space like an atrium or a gymnasium as several rooms joined by air boundaries and this will help account for the differences in air temperature throughout the space without compromising the accuracy of the radiant calculation.

Solution for the “Concave Zone” Problem

A quick search on the forum will reveal how much the community has been affected by EnergyPlus’s historic issues with concave zones. We’re happy to say that HB-Energy now includes a solution for these issues that allows you to run concave zones with the most accurate solar distribution that EnergyPlus offers.

Click to read more

In Legacy, we always had to downgrade the E+ solar distribution to deal with concave zones to the point that the simulation results would not really be suitable for applications like microclimate mapping. But EnergyPlus 9.0 has a game-changing feature called PixelCounting, which uses ray tracing for the solar calculation and provides a full solution for the “concave zone” problem that does not involve downgrading the shadow calculation. We’re happy to say this is fully supported by HB-Energy and you now have the freedom to model any closed zone geometry you want.

URBANopt Integration

The LBT Dragonfly plugin has a connection to the URBANopt SDK which is a set of software packages that are being developed by NREL, LBNL, and other partners to assist with urban energy, grid-interactive, and district thermal system modeling.

Click to read more

Currently, the URBANopt connection from Dragonfly provides a streamlined means of running energy simulations of multiple buildings in parallel. It does not yet include district thermal systems or grid-interactive modeling in the simulation but, over the next year, we will be integrating aspects of the work that the URBANopt team is doing to provide 4th and 5th generation district system templates and grid interactive modeling capabilities. In the meantime, the Dragonfly interface can be used to model energy use in districts of disconnected buildings and to assess the size/cost of district systems by modeling peak load conditions. We will have a longer post on this for those looking to run energy simulations using URBANopt.

Urban MonthlyLoadAnimation

Missing Legacy Features Targeted for the Next Stable Release

There are a few important legacy features that we are working hard to integrate into the new LBT plugin, which you can expect to be integrated very soon (within the next few months).

A Few Ladybug Visuals

Click to read more

While LBT Ladybug currently has many of the most-used visualization components, there are still a few that are missing, most notably the Psychrometric Chart. However, we have most of the underlying software infrastructure that’s needed to expose these capabilities and we expect to have the full suite of climate graphics and geometry analysis components done by the next stable release of the Grasshopper plugin.

Several Radiance Recipes

Click to read more

LBT includes a very minimal set of radiance recipes and this is because it took us longer than expected to develop a means for representing recipes in a way that can scale for multiple CPUs (and eventually for cloud-based simulation). Now that this is done, we expect to have a full suite of Radiance recipes with the next stable release of the Grasshopper plugin.

Microclimate Mapping

Click to read more

We plan to implement detailed microclimate mapping capabilities using the same underlying scaleable schema that the Radiance Recipes use. So we should have full microclimate map support in the next release now that the underlying schema is complete.

Radiant HVAC

Click to read more

While we have over 100 detailed HVAC templates in the LBT plugin, radiant slabs and thermally active surfaces are not among them. Much of this comes down to the higher complexity of controls for these systems and the need to expose certain parameters but we intend to have customizable radiant HVAC templates in the next release.

Dragonfly UWG Integration

Click to read more

At the moment, LBT is not integrated with the Urban Weather Generator (UWG), which morphs epw files to account for urban heat island. However, we have almost all of the underlying infrastructure for it, which we plan to expose soon.

Currently Excluded Legacy Features

There are a few legacy features that are currently being excluded from the LBT plugin but we hope to support in the future. Supporting these features involves us reconciling platform-specific limitations of simulation engines and/or resources with the cross-platform and os-independent nature of the LBT plugin. So, at the least, it will take us some time to figure out the best means of supporting them and, if/when they are supported, they may only be available to users on certain platforms.

  • THERM Integration
  • Ironbug Integration
  • Ladybug Renewables
  • Envi-Met Integration
Missing components on the new Ladybug
About the honeybee category
UrbanOpt_ Dragonfly
HVAC simulations
Using the Forum Categories for Grasshopper Plugin Questions
AnnualLoads explanation
Missing Radiance Recipes in new HB
Severe errors during Energy Simulation in Honeybee
Annual radiation, clear sky
Glazing by Ratio on curved geometry -- error: attempted to divide by zero
About the dragonfly category
Convex vs Non-Convex Cooling and Heating results
Sky View analysis - 1. Solution exception:Attempted to divide by zero
Ladybug new version installation problem
Help: Missing Ladybug Renewable Components
New Update is missing some components
Ladybug Tools for Grasshopper 1.1.0 Bug Fixes & Patches
Missing LB function
Honeybee zoning - setEPZoneLoads component error
MRT Calculation in LBT 1.1
Update LB legacy scripts to LB 1.1.0
Domestic hot water energy consumption
Open Studio Shadow calculation object has no attribute
I'm quite confused about airwall in energyplus
Can't find Solar Evelope in 1.10
Therm tab/component missing in Ladybug Tools 1.1.0
How to Set-up Image-based sim in HB_radiance
Ladybug Tools for Grasshopper 1.1.0 Bug Fixes & Patches
Ladybug Tools 1.0.0 vs0.69 - repetitive components
Installation Error Certificate_Verify_Failed
Baseboard Heating in Honeybee
Calculating energy balance for each program or zone in honeybee
Issue in running DC image based simulation
Glare analysis component in Ladybug Tools 1.0.9
Dragonfly UWG problem
Simulation Start Day
Connect hb+ to energy plus
View analysis in certain radius
Sensible & Latent load fraction input
Ladybug Tools for Grasshopper 1.0.9 Patches & Improvments
Grasshopper DataOut / DataIn with Honeybee

Faster, Reliable & Robust : LBT. Congratulations @chris, @mostapha and the whole team.:+1:

:clap::clap::clap::clap: enormous thanks to the entire team!

just wonderful !!! Big thanks

awesome news!

quick question…to continue using the legacy tools with OpenStudio 3.x, after OS3.x installation do we have to do the steps listed in this post still…??

also just in general, is the new 1.0.0 release compatible with OpenStudio 2.9.x still?

The steps in that post that you linked to are definitely not necessary for running energy simulations with the new LBT plugin but, yes, nothing has changed about the legacy plugin. So, if you want to use OpenStudio 3.x with Legacy, you still need to follow those steps. Alternatively, if you want to leave your legacy using an older OpenStudio but ensure that the new LBT plugin is using OpenStudio 3.0, you can install OpenStudio 3.0 in your C:\Users\[USERNAME]\ladybug_tools folder as is recommended in the installation instructions. The Legacy plugin won’t know to look in the ladybug_tools folder but the new LBT plugin will find OpenStudio at that location.

I am going to say for the record that the new 1.0.0 release is NOT compatible with OpenStudio 2.9.1. Admittedly, you might still be able to get a simulation to run with the LBT plugin and 2.9.1 but many of the new E+ features listed here in the release notes like true air boundaries and the concave zones solution are not supported in 2.9.1. Not to mention a host of other features.


:clap: :clap: :clap: :raised_hands: Big Thanks!!

Beautiful work! Let’s see how much implementation time we need :slight_smile:

Such a good news!!
Thanks @chris, @mostapha, and the rest of the team. I know this was a big and long effort and lucky us you get there.
Keep going.

Wow, what a fantastic milestone - congrats!!

Hi, thanks for the MacOS version.

When I try to install it, the second toggle has an error message : “Solution exception : No module named fctnl”.

I am using Rhino 5 on MacOS, is this the problem ?

Thank you in advance.

Yes. You should use Rhino 6 or newer on Mac. The error that you see is not related to Ladybug Tools but how Python was packaged for Rhino Mac. This has been fixed in Rhino 6.

once again, thank you team!!

Wow! :clap: :clap: :clap:

Congrats @mostapha @chris @MingboPeng @SaeranVasanthakumar @AntoineDao !


2 posts were split to a new topic: Installation Questions about the Ladybug Tools Plugin with Radiance

What exciting news!The ladybug tool makes my work more convenient. I hope the later versions will do better!I also hope you can remember the “Butterfly ”that hasn’t been renewed for a long time.

1 Like

6 posts were split to a new topic: A question about timestep

Oh my god, it’s great, both Windows and Mac can be synchronized. It’s great!!

We’re not worthy — Thank you for all the effort!