Ladybug Tools Dragonfly

0.13.7 · active · verified Thu Apr 16

lbt-dragonfly is a collection of core Python libraries for creating and analyzing urban climate and energy models, including geometric modeling, weather data handling, and simulation setup for building performance analysis. It is part of the Ladybug Tools suite. The current version is 0.13.7, and it typically sees frequent patch releases and minor updates.

Common errors

```
ModuleNotFoundError: No module named 'dragonfly'
```
cause `lbt-dragonfly` or its core sub-packages (like `dragonfly-energy`) are not installed or are not accessible in your current Python environment.

fix Run `pip install lbt-dragonfly` to install the library. If already installed, ensure your Python environment is correctly activated.
```
AttributeError: module 'dragonfly' has no attribute 'energy'
```
cause You might be using an older version of `lbt-dragonfly` where the `energy` submodule was not directly exposed under the main `dragonfly` namespace, or the `dragonfly-energy` package itself was not correctly installed as a dependency.

fix Upgrade your `lbt-dragonfly` installation to the latest version: `pip install --upgrade lbt-dragonfly`. If the problem persists, try reinstalling it in a fresh virtual environment.
```
FileNotFoundError: [Errno 2] No such file or directory: 'C:\EnergyPlusV9-5-0\EnergyPlus.exe'
```
cause Dragonfly is attempting to call an external simulation engine (e.g., EnergyPlus or OpenStudio) but cannot find its executable path on your system. This often happens when the engine isn't installed or its path isn't configured.

fix Ensure the necessary simulation engine (e.g., EnergyPlus, OpenStudio) is installed on your system and its executable path is correctly configured in your system's PATH environment variable, or provided explicitly to the Dragonfly functions that require it. Refer to Ladybug Tools installation guides for engine setup.

Warnings

breaking Version 0.13.0 introduced `dragonfly-openstudio` as a new core dependency. While primarily an internal packaging change, users might notice new capabilities or potentially new underlying requirements for OpenStudio installation if they intend to use `dragonfly-openstudio` features.
Fix: Ensure OpenStudio is correctly installed and configured on your system if you intend to use `dragonfly-openstudio` features. Review the Ladybug Tools OpenStudio installation guides for detailed instructions.
gotcha lbt-dragonfly provides the Python API for modeling, but full energy simulations often require external engines like EnergyPlus or OpenStudio to be installed on your system. The library itself does not bundle these engines.
Fix: Refer to the Ladybug Tools documentation for guides on installing and configuring necessary simulation engines (e.g., OpenStudio) to unlock full simulation capabilities. You will typically need to install these separately.
gotcha Ladybug Tools libraries, including Dragonfly, generally adhere to a consistent internal unit system (e.g., meters for lengths, Celsius for temperatures). Inconsistent units in user input can lead to incorrect model calculations or errors.
Fix: Always consult the specific class or function documentation for expected input units. Use helper functions for unit conversions where available (e.g., in `ladybug-geometry` or `honeybee`), or convert your data to the expected units before passing them to Dragonfly functions.

Install

pip install lbt-dragonfly Install core library

Imports

Model
```
from dragonfly.model import Model
```
Room
```
from dragonfly.model import Room
```
Building
```
from dragonfly.model import Building
```
EnergyModel
wrong:
```
from dragonfly_energy.model import EnergyModel
```
correct:
```
from dragonfly.energy import EnergyModel
```
While `dragonfly-energy` is a separate package, `lbt-dragonfly` consolidates imports under the top-level `dragonfly` namespace for convenience.
Schedule
```
from dragonfly.energy import Schedule
```

Quickstart

This quickstart demonstrates how to create basic geometric and energy model components using `lbt-dragonfly`. It shows the creation of a `Room`, a `Building`, and an `EnergyModel` linked to the building.

from dragonfly.model import Room, Building
from dragonfly.energy import EnergyModel

# 1. Create a simple Room object
room = Room.from_rectangular_floor_plan(
    name='OfficeRoom',
    width=5, depth=4, height=3
)

# 2. Create a Building object from rooms
building = Building(rooms=[room], name='MyOfficeBuilding')

# 3. Create an EnergyModel for the building
energy_model = EnergyModel(building=building)

# You can access properties of the created objects
print(f"Created Room: {room.name} with area {room.floor_area:.2f} m²")
print(f"Created Building: {building.name} with {len(building.rooms)} rooms")
print(f"EnergyModel created for building: {energy_model.building.name}")

# Note: To run simulations, you'd typically need a weather file
# and potentially OpenStudio or EnergyPlus installed, which is beyond this quickstart.

view raw JSON →