{"id":9071,"library":"lbt-dragonfly","title":"Ladybug Tools Dragonfly","description":"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.","status":"active","version":"0.13.7","language":"en","source_language":"en","source_url":"https://github.com/ladybug-tools/lbt-dragonfly","tags":["building performance","energy modeling","urban climate","BIM","HVAC","environmental design"],"install":[{"cmd":"pip install lbt-dragonfly","lang":"bash","label":"Install core library"}],"dependencies":[{"reason":"Core energy modeling functionality, bundled by lbt-dragonfly.","package":"dragonfly-energy","optional":false},{"reason":"Integration with OpenStudio for energy simulations, bundled by lbt-dragonfly.","package":"dragonfly-openstudio","optional":false},{"reason":"Underlying geometry and building model components, bundled by lbt-dragonfly.","package":"lbt-honeybee","optional":false}],"imports":[{"symbol":"Model","correct":"from dragonfly.model import Model"},{"symbol":"Room","correct":"from dragonfly.model import Room"},{"symbol":"Building","correct":"from dragonfly.model import Building"},{"note":"While `dragonfly-energy` is a separate package, `lbt-dragonfly` consolidates imports under the top-level `dragonfly` namespace for convenience.","wrong":"from dragonfly_energy.model import EnergyModel","symbol":"EnergyModel","correct":"from dragonfly.energy import EnergyModel"},{"symbol":"Schedule","correct":"from dragonfly.energy import Schedule"}],"quickstart":{"code":"from dragonfly.model import Room, Building\nfrom dragonfly.energy import EnergyModel\n\n# 1. Create a simple Room object\nroom = Room.from_rectangular_floor_plan(\n    name='OfficeRoom',\n    width=5, depth=4, height=3\n)\n\n# 2. Create a Building object from rooms\nbuilding = Building(rooms=[room], name='MyOfficeBuilding')\n\n# 3. Create an EnergyModel for the building\nenergy_model = EnergyModel(building=building)\n\n# You can access properties of the created objects\nprint(f\"Created Room: {room.name} with area {room.floor_area:.2f} m²\")\nprint(f\"Created Building: {building.name} with {len(building.rooms)} rooms\")\nprint(f\"EnergyModel created for building: {energy_model.building.name}\")\n\n# Note: To run simulations, you'd typically need a weather file\n# and potentially OpenStudio or EnergyPlus installed, which is beyond this quickstart.\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.13.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install lbt-dragonfly` to install the library. If already installed, ensure your Python environment is correctly activated.","cause":"`lbt-dragonfly` or its core sub-packages (like `dragonfly-energy`) are not installed or are not accessible in your current Python environment.","error":"ModuleNotFoundError: No module named 'dragonfly'"},{"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.","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.","error":"AttributeError: module 'dragonfly' has no attribute 'energy'"},{"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.","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.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'C:\\EnergyPlusV9-5-0\\EnergyPlus.exe'"}]}