Grasshopper ladybug


Ladybug allows you to import and analyze standard weather data in Grasshopper; draw diagrams like Sun-path, wind-rose, radiation-rose, etc; customize the diagrams in several ways; run radiation analysis, shadow studies, and view analysis.

Honeybee connects Grasshopper3D to validated simulation engines such as EnergyPlus, Radiance, Daysim and OpenStudio for building energy, comfort, daylighting and lighting simulation.

Licensed under @license GPL-3.0+: ( Read more here about the license.

Ladybug and Honeybee are open source environmental plugins for Grasshopper to help designers create an environmentally-conscious architecture

Ladybug and Honeybee are open source environmental plugins for Grasshopper to help designers create an environmentally-conscious architecture

Ladybug and Honeybee are open source environmental plugins for Grasshopper to help designers create an environmentally-conscious architecture

Ladybug and Honeybee are open source environmental plugins for Grasshopper to help designers create an environmentally-conscious architecture

Ladybug and Honeybee are open source environmental plugins for Grasshopper to help designers create an environmentally-conscious architecture

Ladybug and Honeybee are open source environmental plugins for Grasshopper to help designers create an environmentally-conscious architecture

Ladybug and Honeybee are open source environmental plugins for Grasshopper to help designers create an environmentally-conscious architecture

Ladybug and Honeybee are open source environmental plugins for Grasshopper to help designers create an environmentally-conscious architecture

Ladybug and Honeybee are open source environmental plugins for Grasshopper to help designers create an environmentally-conscious architecture

Ladybug and Honeybee are open source environmental plugins for Grasshopper to help designers create an environmentally-conscious architecture

Learning Resources

This page is a collection of free available online sources for Ladybug Tools.
For the latest videos check on-demand videos page. For workshop materials check workshops page.

Envelope Design with Honeybee THERM

The building envelopes that we create today may be in place for centuries and it is critical that we design and detail them well. This tutorial series gives guidance for designing such high-performing envelopes by modeling the heat flow through such details with Honeybee THERM. In this 3-hour series of 10 videos, you will learn how the smallest of thermal bridges can compromise the insulation performance of our envelopes yet there are often many simple and elegant solutions.

Getting Started with Ladybug for Dynamo

This playlist walks you through Ladybug installation for Dynamo and basic features of the plugin.

Getting Started with Ladybug for Grasshopper

This playlist walks you through Ladybug installation for Grasshopper and basic features of the plugin.

Ladybug Comfort Tutorials

A series of videos showing how to use the Ladybug comfort components in Grasshopper.

How to Use Ladybug Sunpath Component

This vintage playlist shows you how to use sunpath in Ladybug for Grasshopper.

Ladybug Workshop at PennDesign April 2014

This series is 6 videos recorded from a full day Ladybug workshop for MEBD students at PennDesign Many of the component has changed from 2014 but most of the workflows is still very similar.

Ladybug Tools was started by Mostapha in 2012 mainly out of frustration: “I couldn’t stand the repetitive, simplified and disconnected workflows that I had to use on a daily basis as well as the overall lack of knowledge about environmental building design. I wanted educate more people about the principles of environmental building design and that happened to be through Ladybug!”

The first version was released on January 2013 as a Ladybug plugin for Grasshopper. It was a collection of a mere 28 components for weather data visualization, solar radiation studies, and sunlight hours analysis. Following the success of Ladybug, Honeybee for Grasshopper was released in 2014 to connect Grasshopper to validated daylighting and energy simulation engines, such as RADIANCE, Daysim, EnergyPlus and OpenStudio.

Soon after, Chris came on board and helped move Ladybug on to the next phase of its development. While using Ladybug and Honeybee for his thesis at MIT, he added thermal comfort models to Ladybug, which provided a foundation for detailed comfort mapping tools he later added to Honeybee. From this start, Chris then further developed multiple components, becoming one of the lead developers of Ladybug Tools. In 2016, he completed a connection between Honeybee and LBNL THERM / WINDOW and he currently upgrades and maintains Ladybug legacy plugin and Honeybee’s connection with OpenStudio.

In 2016, we started re-writing Ladybug Tools to provide them as cross-platform Python libraries and plugins for Grasshopper and Dynamo. After more than a year of work, Mostapha and Theodore released the Butterfly plugin in March 20, 2017. Butterfly adds Computational Fluid Dynamics (CFD) simulation to Ladybug Tools by connecting Grasshopper and Dynamo to OpenFOAM. After the release of Butterfly Mostapha and Sarith released the first version of Honeybee[+] in August 2017.

We are currently in the process of linking Ladybug Tools with more analysis engines such as the Urban Weather Generator, and the SyntheticWeather engine for climate change projections (soon to be released under Dragonfly). With the help from Theo, we are also developing Ladybug Tools for web.

To ensure the long-term sustainability of the project as it grows exponentially, Mostapha and Chris co-founded Ladybug Tools LLC in August 2017 to provide commercial services around the project. These include contracted developments, project consulting, cloud computing, and training. These activities help fund the continued development, maintenance and release of Ladybug Tools and help make it a strongly viable, commercially supported, open source project.

Throughout this time, many developers tirelessly contributed to the community in many ways. As a result of their efforts, Ladybug Tools has grown into multiple inter-connected libraries and plugins that are used in academia as well as architecture and engineering offices worldwide. They allow for a wide range of analyses from climate visualization to computational fluid dynamics and have changed the face of environmental building design through their application to projects. With the development ongoing and the community evergrowing, we are excited about the infinite possibilities that lie ahead in the future!

Upcoming tasks

  • Cloud computing services
  • Ladybug Tools plugins for Revit
  • Ladybug Tools plugins for Rhino
  • Adding LBNL THERM capabilities to Honeybee[+]
  • Adding of energy modeling capabilities to Honeybee[+]
  • Ladybug[+] alpha release
  • Dragonfly[+] alpha release (with precipitation data, LANDSAT image import, climate change “morphing”, and Python UWG)


Posted on March 13, 2016 by paulwintour

Ladybug & Honeybee

Ladybug and Honeybee are environmental plug-ins for Grasshopper to help designers create an environmentally-conscious architectural design. They were originally 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. 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 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.

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 difficult 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 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 basically the programming equivalent of a breathalyser before you can drive.

Here is a brief list of what’s new in the latest version (0.0.61) and other important things to keep in mind when using the plug-in:

  • Units – Ladybug works with both metric and imperial units. If working in metric, you can use either meters, centimeters or millimeters. Honeybee on the other hand works exclusively in meters as this is the unit system of EnergyPlus and Radiance.
  • Ladybug 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 include:
    • Location information;
    • Temperature, humidity and enthalpy;
    • Wind data; and
    • Solar radiation data.

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.

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.

How to install Ladybug for Grasshopper

Ladybug is a free plugin for Grasshopper that uses the EnergyPlus engine to provide a range of environmental calculations and visuals for input geometry. This guide will show you how to install Ladybug.

If you are looking to install the more recent Ladybug + Honeybee components for Grasshopper, this guide will help you too.

Check you have the right software

Firstly, you need Rhino 5. Rhino 4 won’t do! You can download a free trial here .

You also need Grasshopper, a free plugin for Rhino. Download the latest version here.

Then you need GHPython. Download it, and unzip it. In GH, open your components folder:

This should open a folder in a location like C:UsersjramsdenAppDataRoamingGrasshopperLibraries . Paste GHPython.gha into this folder.

Install Ladybug

Visit the Ladybug page, take a read of it and have a look at the video. Then download the unlocked version from the page (or quicklink here). This should download a zip folder. Unzip this folder (the next step won’t work if you don’t unzip it first!).

Within the folder should be about 28 .ghuser files. Select them all and drag them directly into the GH window.

Done! To double-check, go to your GH User Object folder under the Special Folders as above (e.g. C:UsersjramsdenAppDataRoamingGrasshopperUserObjects). The .ghuser folders should be in here.

Now a new tab should have appeared in your GH window called Ladybug.

There are 5 categories of components, labelled 0-4. In using Ladybug, these are run through roughly in order.

Grasshopper ladybug

First time here? Check out the Help page!

I am a long time energy modeler recently venturing into daylight modeling. I am now interested in gaining a grasp of visualization tools. I have seen a lot of references to Rhino, Grasshopper, etc. but I haven’t found a good description of how these tools interconnect and how to go about getting started. There are many video tutorials on using various aspects of these different tools but no basic text description on how to get started. For example, generating shadow range analysis early in the design stage using the Architects drawing of the building. Or sunlight hour analysis.

Welcome to the world of daylight modeling! Funny you ask about this now, your timing is quite good. Mostapha Roudsari has been rather active on this forum in the last day or so, and he’s the author of the tools Ladybug and Honeybee, which are both well-suited to the daylighting visualizations you seem interested in. Links to these tools, and tutorials on how to use them, are on Mostapha’s GitHub profile.

For easy integration of Radiance-based daylighting analysis with an energy model, I humbly submit that OpenStudio and the Radiance measure that comes with its latest versions is your best bet, and does not require any commercial software such as Rhino or Grasshopper. But this will merely give you a whole building energy use result; the OpenStudio Radiance measure is not long on visualizations currently.

You’re right. Most of the available resources are video tutorials. There are a number of blog posts that some of the users has posted for specific cases but there is no structured written tutorials similar to these video tutorials.

This presentation slides should answer some of your questions. Also this post by Paul Wintor might be a good place to start. He has also written a post for sunlighthours calculation with ladybug. You can find more posts about Ladybug and Honeybee on his website.

It has been awhile that I want to record a number of short videos that shows use-cases similar to what you said but assuming the long list of things that I want/need to do including rewriting Ladybug + Honeybee that may take some time to happen.

Meanwhile the best place to find examples for different workflows beside the tutorial videos is Hydra. Hydra is the visual repository for several Ladybug and Honeybee workflows. There is a short description for each example file and also screen captures of the final results. Some of them even have videos. Here is one of the examples for sunlighthours.

You can read more on Ladybug forum. It is also the best place to post your questions. Maybe if you post the same question on the group someone from the community can get back to you with better resources. There are several schools which are teaching Ladybug + Honeybee. I wonder if they have some examples that they can share. Here is an old tutorial from Building Technology Laboratory class at MIT.

I hope that I have somewhat answered your question. Let me know your thoughts. We’re re-organizing the whole development and this is the best time to hear feedback such as yours. Thanks.

Week 3: Ladybug — Dynamo VS Grasshopper

I wanted to compare ladybug in Dynamo and Grasshopper to determine which scripting program would be the best to use.

Last week I completed a super basic analysis using 4 rectangles that acted as the site and the surrounding buildings.

This week I wanted to actually add the Site into Revit, import it into dynamo and complete another solar analysis.

I converted the rhinoceros site constructed by harris into a dwg and then imported into a new family in Revit. This was then loaded into the Revit project, and imported into dynamo through the select model element component.

I was able to get it into Dynamo, but that is where I got stuck.

I knew I had to turn the lines into surfaces in order to generate test points, but I couldn’t work out how. I tried surface by patch, loft, and multiple other random components I knew wouldn’t work. There was either nothing to see or an error, with each error saying they aren’t closed lines (fair enough).

I know there is an answer for this, but I wanted to see what would happen if I tried to run a solar analysis on a sphere, as Alexis hinted it wouldn’t work.

Above is the results, which is nothing…

So I moved onto grasshopper to see if it would generate a better analysis.

Which it did, and it also included a key which is great!

Ladybug in grasshopper was also a lot less complex then in Dynamo (even though I was trying to work out why it said ‘let it fly’ for 20 minutes).

I also tested it with a sphere, and it worked much better than dynamo.

This will allows the team to test curvilinear shapes.

I spoke to the whole group about if they think is will actually be useful. Majority of them agreed and said it will help us determine where openings can be and also where to put the hololens as it requires dim light.

I now have a working script, I don’t think I need to experiment anymore with ladybug for this task. I will be able to put the design iterations into the script to visualize how the sun will work with the pavilion which may become beneficial to the final structure.

During Week 4 I’m planning to experiment and research Optimo to see how that may become a useful tool.

Digital gipsy

22.02.2016 04.10.2018

I’m starting to translate descriptions of different addons for Grasshopper. The 1st one will be Labybug (+ Honeybee). This publication will be supplemented.

Начинаю переводить описания разных полезных дополнений к Grasshopper. Первым будет Labybug (+ Honeybee). Публикация будет дополняться.

Ladybug is a free and open source environmental plugin for Grasshopper to help designers create an 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 – бесплатное open source дополнение к Grasshopper, позволяющее создавать осознанный с точки зрения окружающей среды дизайн. Первоначальным шагом в процессе проектирования должен быть анализ метеорологических данных; глубокое понимание этих данных, вероятнее всего, приведет проектировщиков к принятию лучших решений.

Ladybug imports standard EnergyPlus Weather files (.EPW) in Grasshopper and provides a variety of 2D and 3D designer-friendly interactive graphics to support the 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.

Ladybug импортирует EnergyPlus Weather files (.EPW) в Grasshopper и представляет разнообразные 2d и 3d графически оформленные данные для их использования в процессе принятия решений на ранних стадиях проектирования. Инструмент также позволяет сделать анализ радиации и количества световых часов. Интеграция с Grasshopper позволяет получать почти мгновенный результат для проектных вариантов, и, т.к. он запускается в проектной среде, информация и анализ интерактивны.

Honeybee connects Grasshopper3D 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.

Honeybee соединяет Grasshopper c EnergyPlus, Radiance, Daysim и OpenStudio для создания модели получаемой энергии и естественного освещения. Цель – сделать многие функции этих моделей параметрическими.

You need to have Ladybug installed in order to run Honeybee.

Для работы Honeybee необходимо установить Ladybug.

No Comments

Leave a Reply

Your e-mail will not be published. All fields are required.