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).

Quick Navigation

• Key Features
• Roadmap
• How to install?
• Carbonfly Video Tutorials
• Examples
• Documentation
• Instructions for Developers & FAQs
• License
• How to cite

Key Features

1. Indoor ventilation CFD: Run steady-state and transient simulations of CO2 transport, airflow, and buoyancy-driven temperature.
2. Rhino-to-CFD in "one click": Use Rhino/Grasshopper geometry. Carbonfly handles meshing and other setups - no OpenFOAM text files to edit.
3. Plug-and-play boundaries: Presets for inlets, outlets, natural ventilation, and dynamic respiration etc., with sensible defaults you can tweak.
4. Fast what-if studies: Change flow rate, supply temperature, CO2 concentration, and diffuser placement and quickly rerun for comparison.
5. Visualization-ready outputs: Exports a standard OpenFOAM case for viewing CO2 / velocity / temperature / pressure etc. in ParaView.
6. 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:

Post-processing in ParaView:

Post-processing in Grasshopper:

Roadmap

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).
Post-processing	✅ Done (v0.8.0)	Perform analysis and visualization directly in Grasshopper instead of ParaView. See our Examples.
	✅ Done (v0.8.0)	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 discussion board.
	⏳ Planned	Integration with multi-objective optimization workflow.

Back to top ↥

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) 2025 Qirui Huang, Institute of Energy Efficiency and Sustainable Building (E3D), RWTH Aachen University

Back to top ↥

How to cite

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: 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...

Back to top ↥

Contributors