DFODE-kit

March 31, 2026 · View on GitHub

DFODE-kit is a Python toolkit for building machine-learning surrogates for combustion chemistry integration. It helps users move from canonical flame simulations to sampled datasets, augmented and labeled training data, and finally to trained neural-network models that can be deployed in DeepFlame/OpenFOAM workflows.

In practice, DFODE-kit sits between:

DeepFlame / OpenFOAM, which generate and run reacting-flow cases, and
ML training workflows, which need clean, structured, reproducible chemistry datasets.

Documentation

Project documentation: https://deepflame-ai.github.io/DFODE-kit/
DeepFlame documentation: https://deepflame.deepmodeling.com/en/latest/
DeepFlame source: https://github.com/deepmodeling/deepflame-dev

What DFODE-kit does

DFODE-kit currently supports the core workflow below:

Configure runtime paths for OpenFOAM, Conda, and DeepFlame
Initialize canonical flame cases from explicit presets
Run those cases reproducibly
Sample thermochemical states into HDF5
Augment sampled datasets
Label them with Cantera/CVODE integration
Train neural-network surrogates

Current CLI commands

config — store machine-local runtime paths
init — initialize canonical cases from explicit presets
run-case — execute a case-local runner such as Allrun
sample — convert case outputs to HDF5 datasets
augment — augment sampled states
label — generate supervised labels
train — train a neural-network model
h52npy — convert HDF5 scalar fields to NumPy arrays

List commands locally with:

dfode-kit --list-commands

Installation

Clone the repository and install the package in editable mode:

git clone https://github.com/deepflame-ai/DFODE-kit.git
cd DFODE-kit
pip install -e .

If you want the lightweight local verification environment used in this repository:

uv venv .venv
uv pip install --python .venv/bin/python -e '.[dev]'

Runtime requirements

DFODE-kit itself is a Python package, but some workflows also require local installations of:

OpenFOAM
DeepFlame
Conda (or an equivalent Python environment manager)
Cantera for case initialization and labeling workflows

For DeepFlame/OpenFOAM-backed case execution, you must configure machine-local runtime paths with dfode-kit config.

Quickstart: 1D CH4 flame workflow

The example below shows a portable workflow for a 1D freely propagating premixed CH4/air flame at equivalence ratio 1.0.

1. Store machine-local runtime configuration

dfode-kit config set openfoam_bashrc /path/to/openfoam/etc/bashrc
dfode-kit config set conda_sh /path/to/conda/etc/profile.d/conda.sh
dfode-kit config set conda_env_name deepflame
dfode-kit config set deepflame_bashrc /path/to/deepflame-dev/bashrc

2. Initialize a canonical 1D flame case

Run this from a Python environment that has Cantera available:

source /path/to/openfoam/etc/bashrc
source /path/to/conda/etc/profile.d/conda.sh
conda activate deepflame
source /path/to/deepflame-dev/bashrc

python -m dfode_kit.cli.main init oneD-flame \
  --mech /path/to/mechanisms/CH4/gri30.yaml \
  --fuel CH4:1 \
  --oxidizer air \
  --phi 1.0 \
  --out /path/to/run/oneD_flame_CH4_phi1 \
  --apply --force

3. Run the case

python -m dfode_kit.cli.main run-case \
  --case /path/to/run/oneD_flame_CH4_phi1 \
  --apply --json

4. Sample the finished case into HDF5

python -m dfode_kit.cli.main sample \
  --mech /path/to/mechanisms/CH4/gri30.yaml \
  --case /path/to/run/oneD_flame_CH4_phi1 \
  --save /path/to/run/oneD_flame_CH4_phi1/ch4_phi1_sample.h5 \
  --include_mesh

5. Continue to data preparation and training

Typical next steps are:

python -m dfode_kit.cli.main augment \
  --source /path/to/run/oneD_flame_CH4_phi1/ch4_phi1_sample.h5 \
  --mech /path/to/mechanisms/CH4/gri30.yaml \
  --save /path/to/data/ch4_phi1_aug.npy \
  --preset random-local-combustion-v1 \
  --target-size 20000 \
  --apply

python -m dfode_kit.cli.main label \
  --mech /path/to/mechanisms/CH4/gri30.yaml \
  --time 1e-6 \
  --source /path/to/data/ch4_phi1_aug.npy \
  --save /path/to/data/ch4_phi1_labeled.npy

python -m dfode_kit.cli.main train \
  --mech /path/to/mechanisms/CH4/gri30.yaml \
  --source_file /path/to/data/ch4_phi1_labeled.npy \
  --output_path /path/to/models/ch4_phi1_model.pt

See the published data workflow guide for the expected artifacts and stage boundaries:

https://deepflame-ai.github.io/DFODE-kit/data-workflow/

Repository layout

dfode_kit/cli/ — CLI entrypoints and subcommands
dfode_kit/cases/ — case init, presets, sampling, and DeepFlame/OpenFOAM-facing helpers
dfode_kit/data/ — data contracts, HDF5 I/O, integration, augmentation, and labeling helpers
dfode_kit/models/ — model architectures and registries
dfode_kit/training/ — training configuration, registries, training loops, and preprocessing
canonical_cases/ — canonical flame case templates
tutorials/ — tutorial notebooks and workflow examples
docs/ — published project documentation
tests/ — lightweight verification tests

The following papers provide scientific context for DFODE-kit and closely related workflows:

DFODE-kit package paper

@article{li2025dfode,
  title={DFODE-kit: Deep learning package for solving Flame chemical kinetics with high-dimensional stiff Ordinary Differential Equations},
  author={Li, Han and Xiao, Ke and Xu, Yangchen and Zhang, Haoze and Chen, Zhenyi and Mao, Runze and Chen, Zhi X},
  journal={Computer Physics Communications},
  pages={110013},
  year={2025},
  publisher={Elsevier}
}

Multi-fuel generalization and a posteriori validation

@article{li2025comprehensive,
  title={Comprehensive deep learning for combustion chemistry integration: Multi-fuel generalization and a posteriori validation in reacting flow},
  author={Li, Han and Yang, Ruixin and Xu, Yangchen and Zhang, Min and Mao, Runze and Chen, Zhi X},
  journal={Physics of Fluids},
  volume={37},
  number={1},
  year={2025},
  publisher={AIP Publishing}
}

Physics-aware data augmentation and scale separation

@article{xiao2026enhancing,
  title={Enhancing deep learning of ammonia/natural gas combustion kinetics via physics-aware data augmentation and scale separation},
  author={Xiao, Ke and Xu, Yangchen and Li, Han and Chen, Zhi X},
  journal={Fuel},
  volume={419},
  pages={138904},
  year={2026},
  publisher={Elsevier}
}

GPU/ANN-accelerated LES of swirling premixed flames

@article{zhang2024graphics,
  title={Graphics processing unit/artificial neural network-accelerated large-eddy simulation of swirling premixed flames},
  author={Zhang, Min and Mao, Runze and Li, Han and An, Zhenhua and Chen, Zhi X},
  journal={Physics of Fluids},
  volume={36},
  number={5},
  year={2024},
  publisher={AIP Publishing}
}

Integrated GPU + machine learning acceleration framework

@article{mao2024integrated,
  title={An integrated framework for accelerating reactive flow simulation using GPU and machine learning models},
  author={Mao, Runze and Zhang, Min and Wang, Yingrui and Li, Han and Xu, Jiayang and Dong, Xinyu and Zhang, Yan and Chen, Zhi X},
  journal={Proceedings of the Combustion Institute},
  volume={40},
  number={1-4},
  pages={105512},
  year={2024},
  publisher={Elsevier}
}

DeepFlame platform paper

@article{mao2023deepflame,
  title={DeepFlame: A deep learning empowered open-source platform for reacting flow simulations},
  author={Mao, Runze and Lin, Minqi and Zhang, Yan and Zhang, Tianhan and Xu, Zhi-Qin John and Chen, Zhi X},
  journal={Computer Physics Communications},
  volume={291},
  pages={108842},
  year={2023},
  publisher={Elsevier}
}

Design principles in the current refactor

Recent work in this repository focuses on making DFODE-kit:

easier to use from the CLI,
easier for coding agents to operate safely,
more reproducible for scientific workflows,
more explicit about empirical setup assumptions,
more modular for experimentation with model and training changes.

Verification for contributors

This repository includes a lightweight local verification loop:

make bootstrap-harness
make verify

License

This project is distributed under the terms in LICENSE.