Dragonfly Core

1.76.2 verified Sat May 09 auth: no python

Dragonfly Core is the core Python library for urban-scale energy modeling, part of the Ladybug Tools ecosystem. It provides objects for building stories, districts, and urban models that can be converted to Honeybee for detailed simulation. Current version 1.76.2, with frequent releases (weekly) and active maintenance.

pip install dragonfly-core

Common errors

error ImportError: cannot import name 'Building' from 'dragonfly' ↓

cause Importing from top-level package instead of submodule.

fix

Use 'from dragonfly.building import Building'

error AttributeError: 'Building' object has no attribute 'stories' ↓

cause Property 'stories' was renamed to 'unique_stories' in recent versions.

fix

Use 'building.unique_stories' instead of 'building.stories'

Warnings

breaking In v1.76.0, Clearstory objects were added and roof assignment methods changed. Code that directly manipulates roof subfaces may need updates. ↓

fix Use new 'assign_clearstory' methods on RoofSpecification; avoid direct subface manipulation.

gotcha Dragonfly uses meters internally. Coordinates and dimensions must be in meters; incorrect units lead to scaling errors. ↓

fix Ensure all coordinate and dimension inputs are in meters (m). Convert from feet or other units before passing.

deprecated The 'Building.stories' property is deprecated in favor of 'Building.unique_stories'. Using 'stories' may raise a deprecation warning in future releases. ↓

fix Replace 'building.stories' with 'building.unique_stories'.

gotcha MultiPolygon geometries are not fully supported by URBANopt. Workaround exists in v1.75.35 but may cause conversion failures. ↓

fix Upgrade to >=1.75.35 for a partial workaround; avoid MultiPolygon if targeting URBANopt.

Imports

Building

wrong

import dragonfly.Building

correct

from dragonfly.building import Building

Building is in a submodule; direct import fails.

Story
wrong
```
from dragonfly import Story
```
correct
```
from dragonfly.story import Story
```
Story is not exposed at the top-level package init.

DragonflyModel

from dragonfly.model import DragonflyModel

No common wrong import.

Quickstart

Create a simple Dragonfly model with a single building and story.

from dragonfly.building import Building
from dragonfly.story import Story
from dragonfly.model import DragonflyModel

# Create a simple rectangular building with one story
story = Story.from_rect('Story1', width=10, height=5, floor_height=3)
building = Building('Building1', unique_stories=[story], floor_to_floor_height=3.0)
model = DragonflyModel('MyModel', buildings=[building])
print(model.to_dict())