Ladybug and Honeybee are environmental plug-ins for Grasshopper to help designers create an environmentally-conscious architectural design. They were initially developed by Mostapha Sadeghipour Roudasri but are open-source and maintained by several people, including Chris Mackey. Like many of the other Grasshopper plug-ins, they are both named after animals.
Ladybug
The name ‘Ladybug’ was originally chosen due to the ladybug’s weather forecasting ability. Ladybug allows you to import standard EnergyPlus Weather files (*epw) into Grasshopper and provides a variety of 3D interactive graphics/metrics, including Sun-path, wind-rose, radiation-roses, radiation analysis, shadow studies, and view analysis.
Honeybee
Honeybee, on the other hand, connects Grasshopper to EnergyPlus, Radiance, Daysim and OpenStudio for building energy and daylighting simulation. The Honeybee project intends to make many of the features of these simulation tools available in a parametric way. The name ‘honeybee’ derives from their ability to collect nectar from a flower.
Tool verse toolkit
When presenting Ladybug and Honeybee, Mostapha and Chris discuss the notion of tool verse toolkit. Essentially, Ladybug and Honeybee have been designed to be somewhat intentionally challenging to use. While this may seem counter-intuitive, the rationale behind this decision is that often with these types of software, users don’t fully understand what is happening ‘under the hood’. This lack of knowledge means that often incorrect input parameters are entered, resulting in meaningless results. By allowing access to individual tools (components), users are forced to understand how they work before a result is returned. Furthermore, it affords users the possibility to customise their script, hence the notion of tool vs toolkit. It is the programming equivalent of a breathalyser before you can drive.
Tips
Here is a brief list of some essential things to keep in mind when using the plug-in:
Installation
Installation can be a little tricky, and it is strongly recommended that you follow the official instructions to make sure everything works as intended.
Units
Ladybug works with both metric and imperial units. If working in metric, you can use either meters, centimetres or millimetres. Honeybee, on the other hand, works exclusively in meters as this is the unit system of EnergyPlus and Radiance.
Syntax
The inputs of each component is codified with underscores as follows:
- _ Required input
- _Default_
- Optional_
Weather files
The *epw format was developed by the US Department of Energy (DoE) to be a standard weather data format, to which several other data formats could be converted. The DoE use to provide a collection of thousands of weather files from around the world. Recently, however, this has been moved to the EnergyPlus website. These have been derived from a wide range of sources which includes TMY2, TMY3, IWEC, and RMY. In general, it is recommended to use ‘TMY3’ (Typical Meteorological Year 3) as it is more accurate unless it is too far from the subject site, in which case it is better to use ‘TMY2’. The *epw weather file contains weather data for all 8760 hours of a 365-day year. This data includes:
- Location information;
- Temperature, humidity and enthalpy;
- Wind data; and
- Solar radiation data.
EPW map
After years of struggling with the text-based indexing of the DOE’s epw file database, it is now possible to search for weather files using a map interface and search bar thanks to Mostapha’s recent web interface. From now on, the Ladybug’ Download EPW’ component will direct you to this interface. Search for your location, right-click and copy and paste the weather file link into the weatherFileURL input of the ‘Ladybug _OpenEPW and STAT weather file’ component. When downloading zipped weather files, these will often contain several file formats, including:
- *epw file – An EnergyPlus Weather Data File, developed by U.S. Department of Energy;
- *stat – Stasticis file; and
- *ddy – An ASHRAE Design Conditions Design Day Data (American Society of Heating Refrigerating and Air-Conditioning Engineers Inc).
Colour Gradient Library
After realising that several users wanted quick access to common colour gradients that frequently plug into the Legend Parameters component, there is now a component called ‘Color Gradient Library’ to do just this. An image displaying all of these gradients can be found here, and an example file showing how to use the library can be found here.
‘You should first let the Ladybug fly…’
If you receive this error message saying, this is because Grasshopper needs to read the libraries of the ‘Ladybug_Ladybug’ component first before trying to run any other Ladybug components. All grasshopper components in a given Grasshopper file are arranged in an order on the canvas; with some components being read first when you open the file depending on the order that you dropped the components onto the canvas. You can send any component to the back of the grasshopper canvass by selecting them in hitting Ctrl + B on the keyboard. If you do this for your Honeybee_Honeybee and Ladybug_Ladybug components, this will ensure that they load first next time that you open your grasshopper file. Note that even if you are just using Honeybee, you will still need to drop ‘Ladybug_ladybug’ onto the canvas.
Conclusion
For more information about both plug-ins, refer to the Ladybug Primer and the Honeybee Primer. You may also want to check out Hydra, which is a visual platform for sharing Ladybug and Honeybee scripts. Hydra contains numerous definitions and datasets which can be easily downloaded for use.
