Carbonfly
An easy-to-use Python library and Grasshopper toolbox for indoor CO2 CFD simulation
Install / Use
/learn @RWTH-E3D/CarbonflyREADME
Carbonfly
An easy-to-use Python library and Grasshopper toolbox for indoor CO2 CFD simulation, based on OpenFOAM and the Windows Subsystem for Linux (WSL).
<img src="./pics/carbonfly_logo.svg" width="10%" alt="Carbonfly Logo" />Quick Navigation
- Key Features
- Roadmap
- How to install?
- Carbonfly Video Tutorials
- Examples
- Documentation
- Instructions for Developers & FAQs
- License
- How to cite
Key Features
- 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, natural ventilation, and dynamic respiration 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.
- In-Grasshopper post-processing & IAQ assessment: Directly read OpenFOAM results inside Grasshopper for visualization and CO2-based Indoor Air Quality (IAQ) assessment based on different standards.
Workflow overview:
<img src="./pics/carbonfly_overview.gif" width="50%" alt="Carbonfly workflow overview" />Post-processing in ParaView:
<img src="./examples/_pics/01a_simple_mech_vent_transient_ParaView.gif" width="50%" alt="Carbonfly post-processing in ParaView" />Post-processing in Grasshopper:
<img src="./pics/carbonfly_postprocessing.gif" width="50%" alt="Carbonfly post-processing workflow" />Roadmap
<table style="width:100%"> <tr> <th>Feature</th> <th>Status</th> <th>Implementation Details</th> </tr> <tr> <td>Transient and steady-state CFD simulation of indoor CO2 / temperature / velocity etc. for mechanical ventilation</td> <td>✅ Done (v0.1.0)</td> <td>Based on WSL 2 (Ubuntu-20.04) & OpenFOAM v10. Solver <code>buoyantReactingFoam</code> which supports multi-species with enhanced buoyancy treatment. The reaction is disabled and only the mixing, mainly driven by buoyancy, is considered.</td> </tr> <tr> <td>Natural ventilation through open windows</td> <td>✅ Done (v0.3.0)</td> <td> See our <a href="./examples" alt="Examples" target="_blank">Examples</a>: 1) Transient: <code>Carbonfly Dynamic Window</code> based on <code>pressureInletOutletVelocity</code>; 2) Steady-state: simplified split window (top/bottom); 3) Bounding box (indoor + outdoor). </td> </tr> <tr> <td rowspan="2">Manikins with different Levels of Detail (LOD)</td> <td>✅ Done (v0.2.0)</td> <td>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.</td> </tr> <tr> <td>⏳ Planned</td> <td>LOD1/2/...</td> </tr> <tr> <td rowspan="2">Thermal comfort models</td> <td>✅ Done (v0.4.0)</td> <td>Gagge two-node model for standing, sitting, and sleeping positions (based on <a href="https://github.com/CenterForTheBuiltEnvironment/pythermalcomfort" alt="pythermalcomfort link">pythermalcomfort</a>)</td> </tr> <tr> <td>⏳ Planned</td> <td>Support more models</td> </tr> <tr> <td>Dynamic respiration</td> <td>✅ Done (v0.5.0)</td> <td>Time-varying mouth boundary for <code>U</code> via <code>codedFixedValue</code> (sine). Parameterized by breathing frequency and average breathing flow rate (L/min). Amplitude is computed from target ventilation and patch area. </td> </tr> <tr> <td>Recirculated supply & return</td> <td>✅ Done (v0.6.0)</td> <td>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). </td> </tr> <tr> <td rowspan="3">Post-processing</td> <td>✅ Done (v0.8.0)</td> <td>Perform analysis and visualization directly in Grasshopper instead of ParaView. See our <a href="./examples" alt="Examples" target="_blank">Examples</a>.</td> </tr> <tr> <td>✅ Done (v0.8.0)</td> <td>Indoor Air Quality (IAQ) assessment based on international/national standards. If you know of other CO2-based IAQ standards, please leave a comment in our <a href="https://github.com/RWTH-E3D/carbonfly/discussions/5" alt="discussion board IAQ standards link">discussion board</a>.</td> </tr> <tr> <td>⏳ Planned</td> <td>Integration with multi-objective optimization workflow.</td> </tr> </table>How to install?
See How to Install & Update & Uninstall
Carbonfly Video Tutorials
Carbonfly Tutorial Series (YouTube)
Examples
See Examples
Documentation
Python library
See Python Library Documentation
Grasshopper Toolbox
See Grasshopper Toolbox Documentation
Instructions for Developers & FAQs
See Instructions for Developers & FAQs
License
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) 2026 Qirui Huang, Institute of Energy Efficiency and Sustainable Building (E3D), RWTH Aachen University
How to cite
If you want to cite Carbonfly, there are two ways to do it:
-
If you use Carbonfly in your academic work, please cite our journal paper: https://doi.org/10.1016/j.softx.2026.102580 (preferred)
Examples:
BibTeX:
@article{Huang_2026_Carbonfly_SoftwareX, author = {Huang, Qirui and Langenbeck, Anna and Frisch, J{\'e}r{\^o}me and van Treeck, Christoph}, title = {{Carbonfly}: {An} easy-to-use {Python} library and {Grasshopper} toolbox for {CO}$_2$-based indoor airflow and air quality {CFD} simulation}, journal = {SoftwareX}, year = {2026}, volume = {34}, pages = {102580}, doi = {10.1016/j.softx.2026.102580}, }APA style:
Huang, Q., Langenbeck, A., Frisch, J., & van Treeck, C. (2026). Carbonfly: An easy-to-use Python library and Grasshopper toolbox for CO₂-based indoor airflow and air quality CFD simulation. SoftwareX, 34, 102580. https://doi.org/10.1016/j.softx.2026.102580 -
If your work depends on a specific release of Carbonfly, please additionally cite the archived Zenodo version corresponding to the release you used. Each release is archived on
. Please either cite the version you used as indexed at Zenodo (for reproducibility) or cite all versions.Examples:
BibTeX:
@misc{Carbonfly_Zenodo_Huang, author = {Qirui Huang}, title = {{Carbonfly}: {An} easy-to-use {Python} library and {Grasshopper} toolbox for {CO}$_2$-based indoor airflow and air quality {CFD} simulation}, year = {2025}, publisher = {Zenodo}, url = {https://github.com/RWTH-E3D/carbonfly}, doi = {10.5281/zenodo.17117827}, }APA style:
Huang, Q. (2025). Carbonfly: An easy-to-use Python library and Grasshopper toolbox for CO₂-based indoor airflow and air quality CFD simulation [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.17117827BibTeX (version-specific):
@misc{Carbonfly_Zenodo_Huang, author = {Qirui Huang}, title = {{Carbonfly}: {An} easy-to-use {Python} library and {Grasshopper} toolbox for {CO}$_2$-based indoor airflow and air quality {CFD} simulation (Version v0.8.0)}, year = {2025}, note = {Zenodo} url = {https://doi.org/10.5281/zenodo.17504360}, doi = {10.5281/zenodo.17504360}, }APA style (version-specific):
Huang, Q. (2025). Carbonfly: An easy-to-use Python library and Grasshopper toolbox for CO₂-based indoor airflow and air quality CFD simulation (Version 0.8.0) [Comput
