{"id":27707,"library":"dragonfly-core","title":"Dragonfly Core","description":"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.","status":"active","version":"1.76.2","language":"python","source_language":"en","source_url":"https://github.com/ladybug-tools/dragonfly-core","tags":["urban-modeling","building-energy","ladybug-tools","simulation"],"install":[{"cmd":"pip install dragonfly-core","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Core dependency for geometry, simulation, and conversion to Honeybee models.","package":"honeybee-core","optional":false},{"reason":"Schema definitions for Dragonfly objects, required for serialization/deserialization.","package":"dragonfly-schema","optional":false},{"reason":"Used for geometric operations on 2D and 3D objects.","package":"ladybug-geometry","optional":false}],"imports":[{"note":"Building is in a submodule; direct import fails.","wrong":"import dragonfly.Building","symbol":"Building","correct":"from dragonfly.building import Building"},{"note":"Story is not exposed at the top-level package init.","wrong":"from dragonfly import Story","symbol":"Story","correct":"from dragonfly.story import Story"},{"note":"No common wrong import.","symbol":"DragonflyModel","correct":"from dragonfly.model import DragonflyModel"}],"quickstart":{"code":"from dragonfly.building import Building\nfrom dragonfly.story import Story\nfrom dragonfly.model import DragonflyModel\n\n# Create a simple rectangular building with one story\nstory = Story.from_rect('Story1', width=10, height=5, floor_height=3)\nbuilding = Building('Building1', unique_stories=[story], floor_to_floor_height=3.0)\nmodel = DragonflyModel('MyModel', buildings=[building])\nprint(model.to_dict())","lang":"python","description":"Create a simple Dragonfly model with a single building and story."},"warnings":[{"fix":"Use new 'assign_clearstory' methods on RoofSpecification; avoid direct subface manipulation.","message":"In v1.76.0, Clearstory objects were added and roof assignment methods changed. Code that directly manipulates roof subfaces may need updates.","severity":"breaking","affected_versions":">=1.76.0"},{"fix":"Ensure all coordinate and dimension inputs are in meters (m). Convert from feet or other units before passing.","message":"Dragonfly uses meters internally. Coordinates and dimensions must be in meters; incorrect units lead to scaling errors.","severity":"gotcha","affected_versions":"all"},{"fix":"Replace 'building.stories' with 'building.unique_stories'.","message":"The 'Building.stories' property is deprecated in favor of 'Building.unique_stories'. Using 'stories' may raise a deprecation warning in future releases.","severity":"deprecated","affected_versions":">=1.60.0"},{"fix":"Upgrade to >=1.75.35 for a partial workaround; avoid MultiPolygon if targeting URBANopt.","message":"MultiPolygon geometries are not fully supported by URBANopt. Workaround exists in v1.75.35 but may cause conversion failures.","severity":"gotcha","affected_versions":"<1.75.35"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Use 'from dragonfly.building import Building'","cause":"Importing from top-level package instead of submodule.","error":"ImportError: cannot import name 'Building' from 'dragonfly'"},{"fix":"Use 'building.unique_stories' instead of 'building.stories'","cause":"Property 'stories' was renamed to 'unique_stories' in recent versions.","error":"AttributeError: 'Building' object has no attribute 'stories'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}