An easy-to-use Python library and Grasshopper toolbox for indoor CO2 CFD simulation, based on OpenFOAM and the Windows Subsystem for Linux (WSL).
- Key Features
- Roadmap
- How to install?
- Documentation
- Instructions for Developers & FAQs
- License
- How to cite
- Indoor ventilation CFD: Run steady-state and transient simulations of CO2 transport, airflow, and buoyancy-driven temperature.
- Rhino-to-CFD in "one click": Use Rhino/Grasshopper geometry. Carbonfly handles meshing and other setups - no OpenFOAM text files to edit.
- Plug-and-play boundaries: Presets for inlets, outlets, and walls etc., with sensible defaults you can tweak.
- Fast what-if studies: Change flow rate, supply temperature, CO2 concentration, and diffuser placement and quickly rerun for comparison.
- Visualization-ready outputs: Exports a standard OpenFOAM case for viewing CO2 / velocity / temperature / pressure etc. in ParaView.
See our Examples:
| Feature | Status | Implementation Details |
|---|---|---|
| Transient and steady-state CFD simulation of indoor CO2 / temperature / velocity etc. for mechanical ventilation | ✅ Done (v0.1.0) | Based on WSL 2 (Ubuntu-20.04) & OpenFOAM v10. Solver buoyantReactingFoam which supports multi-species with enhanced buoyancy treatment. The reaction is disabled and only the mixing, mainly driven by buoyancy, is considered. |
| Natural ventilation through open windows | ✅ Done (v0.3.0) |
See our Examples:
1) Transient: Carbonfly Dynamic Window based on pressureInletOutletVelocity;
2) Steady-state: simplified split window (top/bottom);
3) Bounding box (indoor + outdoor).
|
| Manikins with different Levels of Detail (LOD) | ✅ Done (v0.2.0) | LOD0 Manikin is a simplified human model focused on CO2 dispersion. It is represented by straight lines and basic geometric volumes, without body part subdivision. Breathing is simplified to mouth breathing only, with no nasal passage. This abstraction is well suited for multi-occupant scenarios where reduced CFD mesh size and computational cost are essential. |
| ⏳ Planned | LOD1/2/... | |
| Thermal comfort models | ✅ Done (v0.4.0) | Gagge two-node model for standing, sitting, and sleeping positions (based on pythermalcomfort) |
| ⏳ Planned | Support more models | |
| Dynamic respiration | ✅ Done (v0.5.0) | Time-varying mouth boundary for U via codedFixedValue (sine). Parameterized by breathing frequency and average breathing flow rate (L/min). Amplitude is computed from target ventilation and patch area.
|
| Recirculated supply & return | ✅ Done (v0.6.0) | Paired boundaries for internal (no-fresh-air) air recirculation, applicable to various devices, e.g., split AC indoor units for heating or cooling without fresh air input. The CO2 concentration of the supply air is equal to that of the return air (dynamic). |
See How to Install & Update & Uninstall
See Examples
See Documentation
See Instructions for Developers & FAQs
Carbonfly is a free, open-source plugin licensed under LGPL-3.0.
There are several ways you can contribute:
- 🐞 Report bugs or issues you encounter
- 💡 Suggest improvements or new features
- 🔧 Submit pull requests to improve the code or documentation
- 📢 Share the plugin with others who may find it useful
Copyright (C) 2025 Qirui Huang, Institute of Energy Efficiency and Sustainable Building (E3D), RWTH Aachen University
If you want to cite Carbonfly in your academic work, there are two ways to do it:
-
Each release is archived on
. Please either cite the version you used as indexed at Zenodo (for reproducibility) or cite all versions.
Examples:
BibTeX:
@software{Carbonfly_Huang, author = {Qirui Huang}, title = {Carbonfly}, subtitle = {An easy-to-use Python library and Grasshopper toolbox for indoor CO2 CFD simulation}, date = {2025}, publisher = {Zenodo}, url = {https://github.com/RWTH-E3D/carbonfly}, note = {GitHub repository}, doi = {10.5281/zenodo.17117827} }
APA style:
Huang, Q. (2025). Carbonfly: An easy-to-use Python library and Grasshopper toolbox for indoor CO2 CFD simulation [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.17117827 -
If you wish to cite Carbonfly for its design, methodology, etc. (rather than a specific release), please cite our paper:
Coming soon...