Release Notes - Ladybug 0.0.64 and Honeybee 0.0.61

Great community of Ladybug!  It is with honor and pride that I announce one of the last releases of Ladybug + Honeybee, which (after this release) will be referred to as the legacy version of Ladybug Analysis Tools (LAT).  Our plugin has come a long way in the last 4 years and, while the legacy version will still include some small updates and contributions, we are confident in saying that the changes will be far fewer and the plugin more stable in the following months as we switch gears into the LAT effort.  I can say personally that (save for a couple of small capabilities) I have made it through my list of critical features and I will hereafter be working on making these features cross-platform, cleanly-implemented, and well-documented in the new Ladybug Analysis Tools software package.  As always, you can download the new release from Food4Rhino. Make sure to remove the older version of Ladybug and Honeybee and update your scripts.

The majority of changes with this release represent “icing on the cake” after a long, multi-year effort to connect to the major open source engines and datasets.  So, without further adieu, here is the list of the new capabilities added with this release:

LADYBUG

Stereographic Sky Projections - Thanks to several code contributions from Byron Mardas, all Ladybug sky visualizations now support stereographic projections!  Such projections are useful for understanding the hemispherical visualizations in a 2D format and they also make it easier to overlay different sky datasets on top of one another. Check here for an example file showing the sun path overlaid with h... and see here for an example file using shading masks representing strategie....

Wind Rose Upgrades - Devang Chauhan has added several new features to the Ladybug wind rose including both visual and numerical outputs of average wind velocity and frequency for each petal of the rose.  Not only does this enhance the usefulness of the rose but it also paves the way for the use of the wind rose to set up CFD simulations once Butterfly is released in the near future.  The new features of the wind rose can be seen in this hydra example file.

Complete Set of Local Thermal Discomfort Models -  After the last release included components to evaluate radiant asymmetry discomfort (which can be modeled using these example files: 1, 2), today’s release completes Ladybug’s suite of local discomfort models from ASHRAE and the ISO by adding components to account for discomfort from cold draft.  Specifically, two draft models have been added for different types of situations.  The first is an older model published by P.O. Fanger, which was developed through experiments where subjects had cold air blown on the back of their neck (the most sensitive part of the body to draft).  While this is useful for understanding a worst-case scenario, it can greatly overestimate the discomfort for cases of draft at ankle level - a more common occurrence that typically results from the tendency of cold air to sink.  For this situation, a second draft discomfort model has been included, which is specifically meant to forecast ankle draft discomfort.  The model is currently undergoing review for integration into ASHRAE-55 and a publication outlining the derivation of this model can be found here:

Liu, S., Schiavon, S., Kabanshi, A. and Nazaroff, W. (2016), Predicted Percentage Dissatisfied with Ankle Draft. Indoor Air. Accepted Author Manuscript. doi:10.1111/ina.12364 (http://escholarship.org/uc/item/9076254n).

Special thanks is due to Shichao Liu, Toby Cheung and Stefano Schiavon for sharing the model and the results of their study with the development team.  The integration of draft models  completes the full integration of ASHRAE-55 and EN-15251 with Ladybug.  Now, you can rest assured that, if there is a certain thermal comfort standard that you need to fulfill for a given project, you can model it with the ‘bug!

Window-Based Draft Model - With the integration of draft models, the first question that one might ask is “how should these models be applied to typical design cases?”  While the (soon-to-be-released) Butterfly plugin for OpenFOAM should open up a Pandora’s box of possible situations, this release of Ladybug includes a simplified downdraft model from cold vertical surfaces, which helps model several typical cases of draft discomfort.  The model has been validated across several papers:

Heiselberg, P. (1994). Draught Risk From Cold Vertical Surfaces. Building and Environment, Vol 29, No. 3, 297-301

Manz, H. and Frank, T. (2003). Analysis of Thermal Comfort near Cold Vertical Surfaces by Means of Computational Fluid Dynamics. Indoor Built Environment. 13: 233-242

It has been built into the “Ladybug_Downdraft Velocity” component and has been included in an example file illustrating discomfort from cold windows in winter.  The example is intended to show when glazing ratio and window U-Values are small enough to eliminate perimeter heating - a practice that is aesthetically unpleasing, costly to maintain and wasteful in its energy use.

Operative Temperature on the Psychrometric Chart - This is a feature that should have been added a long time ago but we are finally happy to say that the Ladybug_Psychrometric Chart can draw a comfort polygon assuming that the air temperature and radiant temperature are the same value (aka. an operative temperature psychrometric chart).  This operative temperature chart is the format that is needed to use the ASHRAE-55 graphical method and is generally a better representation of the range of comfort in cases where one does not intend to hold the radiant temperature constant.  This operative temperature capability is now set as the default on the component but you can, of course, still bring back the older comfort polygon by simply plugging in a value for meanRadiantTemperature_.

Contour Map Visualizations - Using the same inputs as the Ladybug_Recolor Mesh component, the new Ladybug_Contour Mesh component allows you to generate contoured color graphics from the results of any analysis.  Now, you to maximize the use of your high-resolution studies with contours that highlight thresholds and gradients!

Image Texture Mapping for Colored Meshes - Antonello DiNunzio has added the very useful Ladybug_Texture Maker component, which allows you to bake Ladybug colored meshes with image texture maps (as opposed to the classic method that used colored vertices).  This enables the creation of transparent Ladybug meshes, making it even easier to overlay Ladybug graphics with one another and with Rhino geometry:

This component also adds the ability to render Ladybug + Honeybee meshes with other rendering programs like V-Ray and 3ds Max.  So you can produce Ladybug graphics like this!

Finally, image-mapped textures are also the format required for gaming and Virtual Reality software like Unity and Augmented Reality programs like Augment.  So now you can export your Ladybug meshes all of the way to the virtual world!

Rhino Sun Component - If you have ever had to set up the sun for a rendering plugin and wished that you could just take your Ladybug sun and use that, then you are in luck! Byron Mardas has contributed a component that lets you set the Rhino sun based on your EPW location data, your north direction (if different from the Y-Axis) and any time of day that you want. Not only does this make it easier to coordinate the Rhino sun with your Ladybug visualizations, but you can also use it for real time shadow previews by setting your Rhino view to “Rendered” and scrolling through a slider.

Rendered Ladybug Animations - With both the image texture mapping and the Rhino sun components released, your first thought might be “it would be great if I could use this all in a rendered animation!” Thankfully, Ladybug has added a new component to help you here. The Ladybug_Render View component works in essentially the same way as the Capture View component, allowing you to make a series of images as you animate through a slider. The major benefit here is that it works with both Rhino Render and V-Ray so that animations like this can be produced effortlessly:

Cone of Vision Added - Antonello Di Nunzio has added a component that allows you to visualize various cones of vision in order to help inform your view studies. You can fine tune parameters to include just text-readable or full peripheral vision and use the resulting view cone to constrict the results of your “Ladybug_View Analysis” studies.

Terrain WIP Components Released as the Gismo Plugin - Our friend Djordje has released a new plugin Gismo - a plugin for GIS environmental analysis. As a result the following 5 terrain components: Horizon Angles, Flow Paths, Terrain Shading Mask, Terrain Generator 2, Terrain Analysis, have been removed from Ladybug+Honeybee's WIP section and are added to Gismo.

HONEYBEE

Search, Select, and Import the Hundreds Outputs from EnergyPlus/OpenStudio - Many of the power users in our community know that EnergyPlus is capable of writing several hundred different outputs from the simulation (well beyond what the basic Honeybee result readers can import). While Honeybee has always allowed one to request these outputs by adding them to the simulationOutputs_ of the component, there has not been an official workflow for searching through all of the possible outputs or importing their specific results… until now! We have added the "Honeybee_Read Result Dictionary" component, which allows you to parse the Result Data Dictionary (or .rrd file) that EnergyPlus outputs during every run of a given model. This allows you to see all of the outputs that are available for the model and you can even search through this list to find a particular output that you are interested in. Once you find what you are looking for, simply copy the text output from the component into a panel and and plug this into simulationOutputs_. Then you can use the "Honeybee_Read EP Custom Result" component to bring your custom results into GH after rerunning the simulation. The example file of an evaporative cooling tower shows how to use the w... to request and import in the energy removed by the tower.

OpenStudio HVAC System Sizing Results - After the full integration of HVAC in the last release, we realized that a number of people wanted to run EnergyPlus models simply to evaluate the size of the Heating/Cooling system in the model (obtained from the EnergyPlus autosize calculation that is run at the start of every simulation). Such a sizing calculation can be a great way to quantify the anticipated savings from a given strategy (like shading) on the size/cost of the building’s HVAC system. To get the results of the sizing calculation, all that one needs to do is connect the output eioFile from the OpenStudio component to the Honeybee_Read HVAC Sizing component. The outputs will indicate the peak heating/cooling loads of each zone (in Watts) as well as the size of each piece of HVAC equipment in the model. The next time that you are on a project that is about to value-engineer out an exterior shading system, use the workflow in the following example file to show that the client will probably end up paying for it with a more expensive HVAC system: Quantifying HVAC Sizing Impact of Shade.

Improved Memory Usage When Building Large Energy Models - As we take the capabilities of Honeybee to larger and larger models, many of us have begun to run up against a particular limitation of our machines: memory. After upgrading our machines to have 32 GBs of RAM, there was only one way left to alleviate the problem: restructure some of the code. Honeybee now uses an enhanced approach that ensures all the previous iterations of Honeybee objects will be removed from the memory once there is a change. In any case, the considerations of memory are definitely something that we intend to improve with the future Honeybee[+] plugin.

Workflow to Import gbXML Files - While GrizzlyBear has been around for several years, enabling us to export Honeybee zones to gbXML, we have gone for quite some time without a workflow to import gbXML files to Honeybee. The new Honeybee_gbXML to Honeybee component addresses this and establishes an easier path to import models from Revit into honeybee. You can read more about the component in this post.

Window Frame Capabilities Added to OpenStudio - After the implementation of LBNL THERM / WINDOW capabilities in the last two releases, there was one final bridge to build in the Honeybee workflow - fully connecting LBNL WINDOW to Honeybee’s OpenStudio workflow. This release of Honeybee will now write all FrameAndDivider objects exported from LBNL WINDOW glazing systems into the energy simulation, enabling you to account for the frame’s thermal bridging effects. As long as the construction is brought in with the Honeybee_Import WINDOW IDF Report component, the frames associated with the construction will be assigned to all windows that have the construction. Finally, it is worth noting that the current Honeybee will also write all glass spectral data as well as gas (or gas mixture) materials into the simulation. This means that essentially all properties of any IDF export that one makes from LBNL WINDOW can be factored into the OpenStudio energy simulation (with the only exception being BSDF materials).

OpenStudio Daylight Sensors Added - In our previous releases of Honeybee, the only means of correctly account for daylight sensors in an energy simulation was to run an annual daylight simulation and use the resulting schedules for the lighting in the energy simulation. However, this can take a lot of time and work to set up and run, particularly if the daylight control (at the end of the day) will be driven by just one sensor per room. Now, we have added another option, which uses OpenStudio/EnergyPlus’s built-in daylight controls. You can assign just a point and an illuminance target on the “Set Zone Thresholds” component and the lighting will be automatically adjusted in the course of the simulation. It should also be noted that the addition of daylight sensors has also coincided with the addition of blind/shade control based on glare. The same sensor point for daylight can be used to drive dynamic shades in the energy simulation based on glare experienced at this point. This example file shows how to set up daylight controls on the EnergyPlus model and check the lighting power results to see the effect.

Better Defaults for Natural Ventilation - After many good people wrote to me informing me that Honeybee overestimates natural ventilation airflow and I wrote back showing the way that I intended natural ventilation to be set up with the component, it dawned on me that I had selected some poor component defaults. Accordingly, this release includes a window-based natural ventilation option on the Set EP Airflow component that corrects for some of the common issues that I have seen. Insect screens are included by default and the component runs a general check to see if wind-driven cross ventilation is possible before auto-assigning it. The component will air on the side of more-conservative, lower airflow rates unless the user overrides the defaults. Finally, it’s worth noting that all of these changes have not affected the freedom of the Custom WindAndStack option on the component. The new defaults can be viewed in this example file.

CFD Results Can be Plugged into Microclimate Maps - In preparation for the (very soon) release of the Butterfly that connects to the OpenFOAM CFD platform, we just wanted to note that all of the microclimate map recipes can now take an input of a csv file with a matrix of CFD results for wind speed. For the time being, we have used these to produce very high-accuracy, high resolution maps of outdoor comfort. There will be more to follow soon!

We should also note that, in the last release I mentioned that we would be phasing out the EnergyPlus component so that all efforts are focused on the OpenStudio component. While I reiterate that all of the features of the EnergyPlus component are available in the OpenStudio component and I encourage everyone to use the OpenStudio component in order to take advantage of its HVAC capabilities, I have come to realize that many prefer to use the EnergyPlus component out of habit and have not yet gotten the time to understand why the OpenStudio component is an improvement over the EnergyPlus component. As a result, we have decided to leave the EnergyPlus component in place for the time being so that everyone has more time to understand this. The future Ladybug Analysis Tools platform will only interact with EnergyPlus through OpenStudio and so it is recommended that everyone use these two components in the Honeybee plugin will serve as an educational resource to understand our current path moving forward with OpenStudio.

Lastly, it is with great pleasure that we welcome Devang Chauhan and Byron Mardas to the developer team! As mentioned previously Devang has contributed several updates to the Ladybug Wind Rose in addition to finding and solving a multitude of bugs in other components. Byron has contributed code that has enabled the previously-mentioned stereographic sky projections along with a better method for running the Ladybug Sky Mask. Finally, Byron has contributed the Rhino Sun component, which allows you to coordinate your Rhino renders with your Ladybug data. Welcome to the Ladybug team, gentlemen!

As always let us know your comments and suggestions.
Cheers!

Ladybug Analysis Tools Development Team