How nasa/cea works
1. What this repository is
- This is a multi-language reimplementation of NASA CEA, centered on a Fortran scientific core that solves chemical equilibrium and derived performance problems.
- Everything else in the repo exists to package, expose, test, document, or drive that core.
2. Core computational layer
- The main solver logic lives in source/ as Fortran modules such as equilibrium.f90, rocket.f90, shock.f90, detonation.f90, mixture.f90, thermo.f90, and transport.f90.
- These modules form the computational engine for equilibrium composition, rocket performance, shock states, detonation calculations, thermodynamic properties, and transport properties.
3. Program entry and orchestration
- source/main.f90 provides the legacy CLI executable.
- source/cea.f90 and source/input.f90 are the main orchestration and input-processing boundaries between user-facing problem definitions and the physics/solver modules.
- The CLI primarily consumes classic .inp problem decks and produces textual output compatible with the historical CEA workflow.
4. Database and property-data pipeline
- The repository includes source databases in data/thermo.inp and data/trans.inp.
- During build/install, these are compiled into runtime database artifacts (thermo.lib, trans.lib) used by the solver.
- The database files are a major architectural dependency: solver correctness depends on loading the right thermodynamic/transport data from the working directory, CEA_DATA_DIR, packaged data, or installed data.
5. Language bindings as separate interface layers
- The repo exposes the same core through multiple bindings under source/bind/:
- C binding in source/bind/c/ with headers like cea.h
- Python binding in source/bind/python/ built from Cython sources (CEA.pyx, libcea.pyx)
- MATLAB compatibility layer in source/bind/matlab/, which routes through Python rather than a separate native MATLAB extension
- Excel binding scaffolding in source/bind/excel/
- These bindings are thin adaptation layers around the compiled Fortran/C interface, not alternate implementations.
6. Python package structure
- The Python package is source/bind/python/cea/, with runtime modules, type hints, typed package markers, and small helper namespaces such as cea.lib, cea.units, and cea.matlab.
- The Python API is intended to be a first-class entry point for programmatic use, including sample scripts and wrappers for equilibrium, rocket, shock, and detonation solvers.
7. C/Fortran ABI boundary
- The architecture uses a compiled interface boundary so the core can be consumed from non-Fortran languages without duplicating solver logic.
- This is where bindc.F90, generated C headers, and Cython wrappers meet the Fortran implementation.
- The design is intentionally layered: language-specific APIs depend on the compiled kernel, not the reverse.
8. Build and packaging system
- The primary build system is CMake, with presets and custom modules under cmake/.
- Python packaging is integrated through the source build path (pyproject.toml and CMake/Cython integration), with Ninja required for editable/source Python builds.
- Makefile, CMakePresets.json, and the CMake helper modules control build variants such as Fortran-only, C-enabled, and Python-enabled configurations.
9. Tests as architecture validation
- There are two main test styles:
- Native/Fortran interface tests in test/main_interface/ that compare CLI output against reference outputs.
- Python tests in source/bind/python/tests/ that validate bindings, reuse behavior, string handling, validation, and solver smoke cases.
- The test suite reflects the repo’s main boundaries: CLI behavior, compiled solver behavior, and binding correctness.
10. Documentation and examples as usage surfaces
- docs/ contains the Sphinx documentation, API/interface references, theory, installation, and example walkthroughs.
- samples/ and the many source/bind/python/cea/samples/ and source/bind/c/samples/ files are important because they demonstrate the expected inputs and outputs for each entry point.
- The docs also describe database lookup rules and how to override them, which is operationally important to the architecture.
11. Vendored utility dependency
- extern/fbasics/ is a bundled utility library used by the main codebase.
- It is a supporting subsystem rather than a product-facing component, but it matters because the core Fortran code depends on it for shared low-level functionality.
12. Operational flow to show in a diagram
- A typical flow is: user input deck or API call → interface layer (CLI/C/Python/MATLAB) → input parsing and mode selection → core thermodynamics/equilibrium solvers → property/database lookup → formatted results back to the caller.
- For build time, the flow is: source databases and Fortran code → CMake/Cython build → compiled executables, shared libraries, Python package, and installed data files.
13. External-facing integration points
- The main external touchpoints are the command-line executable cea, the Python package cea, the C API, and MATLAB via Python.
- GitHub Actions workflows support build, docs, and wheel publication, but they are CI/distribution concerns rather than runtime dependencies.
Main entry points: bindc.F90 C API · CMakeLists.txt CMake build · cea cea package · input.f90 Input parser
Components 31
Fortran core
Scientific solver, orchestration, and shared utilities.
- CEA driver · Main problem coordination and mode selection between input handling and solver modules.
source/cea.f90 - Input parser · Reads classic problem decks and maps them into solver-ready state.
source/input.f90 - Equilibrium · Chemical equilibrium composition and state solving.
source/equilibrium.f90 - Rocket · Rocket performance and related flow property calculations.
source/rocket.f90 - Shock · Shock-state calculations and conservation handling.
source/shock.f90 - Detonation · Detonation and related high-energy state calculations.
source/detonation.f90 - Mixture · Mixture thermodynamics and composition helpers.
source/mixture.f90 - Thermo · Thermodynamic property evaluation and lookup logic.
source/thermo.f90 - Transport · Transport-property evaluation and lookup logic.
source/transport.f90 - fbasics · Vendored low-level helper library used by the Fortran core.
extern/fbasics/source
Data assets
Source databases and runtime property artifacts.
- Thermo data · Source thermodynamic database compiled during build/install.
data/thermo.inp - Transport data · Source transport database compiled during build/install.
data/trans.inp - thermo.lib · Compiled thermodynamic database consumed by the solver at runtime.
- trans.lib · Compiled transport database consumed by the solver at runtime.
Interface layers
CLI and language bindings exposed to users.
- CEA CLI · Legacy command-line entry point that reads input decks and prints CEA-style output.
source/main.f90 - C API · Native ABI layer exposing the Fortran kernel to C and other languages.
source/bind/c/bindc.F90 - cea.h · C-facing declarations for the compiled interface.
source/bind/c/cea.h - Python ext · Cython extension layer bridging Python to the compiled interface.
source/bind/python/CEA.pyx - cea package · Primary Python API and helpers for programmatic use.
source/bind/python/cea - MATLAB bridge · MATLAB-facing layer that routes through the Python package.
source/bind/matlab - Excel scaffold · Placeholder integration surface for spreadsheet-based use.
source/bind/excel
Build system
CMake, packaging, and generated artifacts.
- CMake build · Primary build orchestration for Fortran, bindings, and install targets.
CMakeLists.txt - CMake helpers · Reusable CMake logic for compiler flags, Cython, Python, and linking.
cmake - Python packaging · Python build configuration integrated with the source tree and CMake.
pyproject.toml
Validation
Integration and binding tests.
- CLI tests · Fortran-level tests that compare legacy CLI runs against reference outputs.
test/main_interface - Python tests · Tests for package behavior, reuse, validation, strings, and smoke cases.
source/bind/python/tests
Docs and examples
User-facing documentation and sample workflows.
- Docs site · Sphinx documentation covering theory, installation, interfaces, and examples.
docs/source - CLI samples · Example input decks for the legacy executable.
samples - Python samples · Programmatic usage examples for the Python API.
source/bind/python/cea/samples - C samples · Usage examples for the C interface.
source/bind/c/samples - MATLAB samples · MATLAB usage examples that route through Python.
source/bind/matlab/samples
Connections 42
- CEA CLI → CEA driver: launches · Executable hands control to the legacy orchestration layer.
- CEA driver → Input parser: parses · Coordinates input deck reading and mode selection.
- Input parser → Equilibrium: dispatches · Routes equilibrium problems to the core solver.
- Input parser → Rocket: dispatches · Routes rocket problems to the core solver.
- Input parser → Shock: dispatches · Routes shock problems to the core solver.
- Input parser → Detonation: dispatches · Routes detonation problems to the core solver.
- Equilibrium → Mixture: uses · Shares composition and mixture state helpers.
- Equilibrium → Thermo: uses · Relies on thermodynamic property evaluation.
- Rocket → Thermo: uses · Depends on thermodynamic properties for performance calculations.
- Rocket → Transport: uses · Uses transport properties where needed.
- Shock → Thermo: uses · Depends on thermodynamic property evaluation.
- Detonation → Thermo: uses · Depends on thermodynamic property evaluation.
- Thermo → thermo.lib: loads · Consumes compiled thermodynamic database artifacts.
- Transport → trans.lib: loads · Consumes compiled transport database artifacts.
- Thermo data → thermo.lib: builds · Source thermodynamic data is compiled into the runtime database.
- Transport data → trans.lib: builds · Source transport data is compiled into the runtime database.
- fbasics → CEA driver: supports · Provides shared low-level utilities to the Fortran codebase.
- fbasics → Equilibrium: supports · Provides shared low-level utilities to the solver modules.
- fbasics → Rocket: supports · Provides shared low-level utilities to the solver modules.
- CMake build → CEA CLI: builds · Produces the legacy executable.
- CMake build → C API: builds · Builds the native interface layer.
- CMake build → Python ext: builds · Builds the Python extension modules.
- CMake build → thermo.lib: installs · Installs compiled database artifacts for runtime use.
- CMake build → trans.lib: installs · Installs compiled database artifacts for runtime use.
- CMake helpers → CMake build: extends · Provides reusable build logic and dependency discovery.
- Python packaging → Python ext: packages · Drives editable/source Python builds through the extension layer.
- C API → cea.h: exposes · Declares the C-facing ABI.
- C API → CEA driver: calls · Calls into the compiled Fortran kernel through the ABI boundary.
- Python ext → C API: bridges · Python extension wraps the native C ABI.
- cea package → Python ext: imports · Runtime package is backed by the compiled extension.
- cea package → MATLAB bridge: exposes · Provides MATLAB compatibility helpers from Python.
- MATLAB bridge → cea package: routes through · MATLAB uses the Python package as its execution path.
- Excel scaffold → C API: adapts · Spreadsheet integration is scaffolded around the native interface.
- CLI tests → CEA CLI: verifies · Checks legacy CLI behavior against reference outputs.
- Python tests → cea package: verifies · Validates package behavior and solver bindings.
- Docs site → CEA CLI: documents · Documents legacy command-line usage.
- Docs site → cea package: documents · Documents the Python API.
- Docs site → C API: documents · Documents the C interface.
- CLI samples → CEA CLI: drives · Example decks for CLI workflows.
- Python samples → cea package: drives · Example scripts for programmatic workflows.
- C samples → C API: drives · Example programs for C consumption.
- MATLAB samples → MATLAB bridge: drives · Example scripts for MATLAB compatibility.