# nasa/cea architecture

> Architecture diagram of the GitHub repository nasa/cea, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nasa/cea
- Repository: https://github.com/nasa/cea

## Overview

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: [`source/bind/c/bindc.F90`](https://github.com/nasa/cea/blob/main/source/bind/c/bindc.F90) (C API), [`CMakeLists.txt`](https://github.com/nasa/cea/blob/main/CMakeLists.txt) (CMake build), [`source/bind/python/cea`](https://github.com/nasa/cea/tree/main/source/bind/python/cea) (cea package), [`source/input.f90`](https://github.com/nasa/cea/blob/main/source/input.f90) (Input parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Fortran core"]
  node_cea_orchestrator["CEA driver<br/>orchestration<br/>[cea.f90]"]
  node_input_parser["Input parser<br/>parsing<br/>[input.f90]"]
  node_equilibrium_core["Equilibrium<br/>solver<br/>[equilibrium.f90]"]
  node_rocket_core["Rocket<br/>solver<br/>[rocket.f90]"]
  node_shock_core["Shock<br/>solver<br/>[shock.f90]"]
  node_detonation_core["Detonation<br/>solver<br/>[detonation.f90]"]
  node_mixture_core["Mixture<br/>properties<br/>[mixture.f90]"]
  node_thermo_core["Thermo<br/>properties<br/>[thermo.f90]"]
  node_transport_core["Transport<br/>properties<br/>[transport.f90]"]
  node_fbasics["fbasics<br/>utility library"]
end

subgraph group_data["Data assets"]
  node_thermo_db_src["Thermo data<br/>database source<br/>[thermo.inp]"]
  node_trans_db_src["Transport data<br/>database source<br/>[trans.inp]"]
  node_thermo_db[("thermo.lib<br/>runtime database")]
  node_trans_db[("trans.lib<br/>runtime database")]
end

subgraph group_interfaces["Interface layers"]
  node_main_cli["CEA CLI<br/>executable<br/>[main.f90]"]
  node_c_api["C API<br/>binding<br/>[bindc.F90]"]
  node_c_header["cea.h<br/>header<br/>[cea.h]"]
  node_python_ext["Python ext<br/>binding<br/>[CEA.pyx]"]
  node_python_pkg["cea package"]
  node_matlab_bridge["MATLAB bridge<br/>compat layer"]
  node_excel_scaffold["Excel scaffold<br/>binding scaffold"]
end

subgraph group_build["Build system"]
  node_cmake_build["CMake build<br/>build system<br/>[CMakeLists.txt]"]
  node_cmake_helpers["CMake helpers<br/>build modules"]
  node_pyproject["Python packaging<br/>[pyproject.toml]"]
end

subgraph group_tests["Validation"]
  node_native_tests["CLI tests<br/>integration tests"]
  node_python_tests["Python tests<br/>binding tests"]
end

subgraph group_docs["Docs and examples"]
  node_docs_site["Docs site<br/>documentation"]
  node_samples_cli["CLI samples<br/>examples"]
  node_samples_python["Python samples<br/>examples"]
  node_samples_c["C samples<br/>examples"]
  node_samples_matlab["MATLAB samples<br/>examples"]
end

node_main_cli -->|"launches"| node_cea_orchestrator
node_cea_orchestrator -->|"parses"| node_input_parser
node_input_parser -->|"dispatches"| node_equilibrium_core
node_input_parser -->|"dispatches"| node_rocket_core
node_input_parser -->|"dispatches"| node_shock_core
node_input_parser -->|"dispatches"| node_detonation_core
node_equilibrium_core -->|"uses"| node_mixture_core
node_equilibrium_core -->|"uses"| node_thermo_core
node_rocket_core -->|"uses"| node_thermo_core
node_rocket_core -->|"uses"| node_transport_core
node_shock_core -->|"uses"| node_thermo_core
node_detonation_core -->|"uses"| node_thermo_core
node_thermo_core -->|"loads"| node_thermo_db
node_transport_core -->|"loads"| node_trans_db
node_thermo_db_src -->|"builds"| node_thermo_db
node_trans_db_src -->|"builds"| node_trans_db
node_fbasics -->|"supports"| node_cea_orchestrator
node_fbasics -->|"supports"| node_equilibrium_core
node_fbasics -->|"supports"| node_rocket_core
node_cmake_build -->|"builds"| node_main_cli
node_cmake_build -->|"builds"| node_c_api
node_cmake_build -->|"builds"| node_python_ext
node_cmake_build -->|"installs"| node_thermo_db
node_cmake_build -->|"installs"| node_trans_db
node_cmake_helpers -->|"extends"| node_cmake_build
node_pyproject -->|"packages"| node_python_ext
node_c_api -->|"exposes"| node_c_header
node_c_api -->|"calls"| node_cea_orchestrator
node_python_ext -->|"bridges"| node_c_api
node_python_pkg -->|"imports"| node_python_ext
node_python_pkg -->|"exposes"| node_matlab_bridge
node_matlab_bridge -->|"routes through"| node_python_pkg
node_excel_scaffold -.->|"adapts"| node_c_api
node_native_tests -->|"verifies"| node_main_cli
node_python_tests -->|"verifies"| node_python_pkg
node_docs_site -->|"documents"| node_main_cli
node_docs_site -->|"documents"| node_python_pkg
node_docs_site -->|"documents"| node_c_api
node_samples_cli -->|"drives"| node_main_cli
node_samples_python -->|"drives"| node_python_pkg
node_samples_c -->|"drives"| node_c_api
node_samples_matlab -->|"drives"| node_matlab_bridge

click node_main_cli "https://github.com/nasa/cea/blob/main/source/main.f90"
click node_cea_orchestrator "https://github.com/nasa/cea/blob/main/source/cea.f90"
click node_input_parser "https://github.com/nasa/cea/blob/main/source/input.f90"
click node_equilibrium_core "https://github.com/nasa/cea/blob/main/source/equilibrium.f90"
click node_rocket_core "https://github.com/nasa/cea/blob/main/source/rocket.f90"
click node_shock_core "https://github.com/nasa/cea/blob/main/source/shock.f90"
click node_detonation_core "https://github.com/nasa/cea/blob/main/source/detonation.f90"
click node_mixture_core "https://github.com/nasa/cea/blob/main/source/mixture.f90"
click node_thermo_core "https://github.com/nasa/cea/blob/main/source/thermo.f90"
click node_transport_core "https://github.com/nasa/cea/blob/main/source/transport.f90"
click node_fbasics "https://github.com/nasa/cea/tree/main/extern/fbasics/source"
click node_thermo_db_src "https://github.com/nasa/cea/blob/main/data/thermo.inp"
click node_trans_db_src "https://github.com/nasa/cea/blob/main/data/trans.inp"
click node_c_api "https://github.com/nasa/cea/blob/main/source/bind/c/bindc.F90"
click node_c_header "https://github.com/nasa/cea/blob/main/source/bind/c/cea.h"
click node_python_ext "https://github.com/nasa/cea/blob/main/source/bind/python/CEA.pyx"
click node_python_pkg "https://github.com/nasa/cea/tree/main/source/bind/python/cea"
click node_matlab_bridge "https://github.com/nasa/cea/tree/main/source/bind/matlab"
click node_excel_scaffold "https://github.com/nasa/cea/tree/main/source/bind/excel"
click node_cmake_build "https://github.com/nasa/cea/blob/main/CMakeLists.txt"
click node_cmake_helpers "https://github.com/nasa/cea/tree/main/cmake"
click node_pyproject "https://github.com/nasa/cea/blob/main/pyproject.toml"
click node_native_tests "https://github.com/nasa/cea/tree/main/test/main_interface"
click node_python_tests "https://github.com/nasa/cea/tree/main/source/bind/python/tests"
click node_docs_site "https://github.com/nasa/cea/tree/main/docs/source"
click node_samples_cli "https://github.com/nasa/cea/tree/main/samples"
click node_samples_python "https://github.com/nasa/cea/tree/main/source/bind/python/cea/samples"
click node_samples_c "https://github.com/nasa/cea/tree/main/source/bind/c/samples"
click node_samples_matlab "https://github.com/nasa/cea/tree/main/source/bind/matlab/samples"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cea_orchestrator,node_input_parser,node_equilibrium_core,node_rocket_core,node_shock_core,node_detonation_core,node_mixture_core,node_thermo_core,node_transport_core,node_fbasics toneBlue
class node_thermo_db_src,node_trans_db_src,node_thermo_db,node_trans_db toneAmber
class node_main_cli,node_c_api,node_c_header,node_python_ext,node_python_pkg,node_matlab_bridge,node_excel_scaffold toneMint
class node_cmake_build,node_cmake_helpers,node_pyproject toneRose
class node_native_tests,node_python_tests toneIndigo
class node_docs_site,node_samples_cli,node_samples_python,node_samples_c,node_samples_matlab toneTeal
```

## Components

### Fortran core

Scientific solver, orchestration, and shared utilities.

- [CEA driver](https://github.com/nasa/cea/blob/main/source/cea.f90): orchestration · Main problem coordination and mode selection between input handling and solver modules. · `source/cea.f90`
- [Input parser](https://github.com/nasa/cea/blob/main/source/input.f90): parsing · Reads classic problem decks and maps them into solver-ready state. · `source/input.f90`
- [Equilibrium](https://github.com/nasa/cea/blob/main/source/equilibrium.f90): solver · Chemical equilibrium composition and state solving. · `source/equilibrium.f90`
- [Rocket](https://github.com/nasa/cea/blob/main/source/rocket.f90): solver · Rocket performance and related flow property calculations. · `source/rocket.f90`
- [Shock](https://github.com/nasa/cea/blob/main/source/shock.f90): solver · Shock-state calculations and conservation handling. · `source/shock.f90`
- [Detonation](https://github.com/nasa/cea/blob/main/source/detonation.f90): solver · Detonation and related high-energy state calculations. · `source/detonation.f90`
- [Mixture](https://github.com/nasa/cea/blob/main/source/mixture.f90): properties · Mixture thermodynamics and composition helpers. · `source/mixture.f90`
- [Thermo](https://github.com/nasa/cea/blob/main/source/thermo.f90): properties · Thermodynamic property evaluation and lookup logic. · `source/thermo.f90`
- [Transport](https://github.com/nasa/cea/blob/main/source/transport.f90): properties · Transport-property evaluation and lookup logic. · `source/transport.f90`
- [fbasics](https://github.com/nasa/cea/tree/main/extern/fbasics/source): utility library · Vendored low-level helper library used by the Fortran core. · `extern/fbasics/source`

### Data assets

Source databases and runtime property artifacts.

- [Thermo data](https://github.com/nasa/cea/blob/main/data/thermo.inp): database source · Source thermodynamic database compiled during build/install. · `data/thermo.inp`
- [Transport data](https://github.com/nasa/cea/blob/main/data/trans.inp): database source · Source transport database compiled during build/install. · `data/trans.inp`
- **thermo.lib**: runtime database · Compiled thermodynamic database consumed by the solver at runtime.
- **trans.lib**: runtime database · Compiled transport database consumed by the solver at runtime.

### Interface layers

CLI and language bindings exposed to users.

- [CEA CLI](https://github.com/nasa/cea/blob/main/source/main.f90): executable · Legacy command-line entry point that reads input decks and prints CEA-style output. · `source/main.f90`
- [C API](https://github.com/nasa/cea/blob/main/source/bind/c/bindc.F90): binding · Native ABI layer exposing the Fortran kernel to C and other languages. · `source/bind/c/bindc.F90`
- [cea.h](https://github.com/nasa/cea/blob/main/source/bind/c/cea.h): header · C-facing declarations for the compiled interface. · `source/bind/c/cea.h`
- [Python ext](https://github.com/nasa/cea/blob/main/source/bind/python/CEA.pyx): binding · Cython extension layer bridging Python to the compiled interface. · `source/bind/python/CEA.pyx`
- [cea package](https://github.com/nasa/cea/tree/main/source/bind/python/cea): package · Primary Python API and helpers for programmatic use. · `source/bind/python/cea`
- [MATLAB bridge](https://github.com/nasa/cea/tree/main/source/bind/matlab): compat layer · MATLAB-facing layer that routes through the Python package. · `source/bind/matlab`
- [Excel scaffold](https://github.com/nasa/cea/tree/main/source/bind/excel): binding scaffold · Placeholder integration surface for spreadsheet-based use. · `source/bind/excel`

### Build system

CMake, packaging, and generated artifacts.

- [CMake build](https://github.com/nasa/cea/blob/main/CMakeLists.txt): build system · Primary build orchestration for Fortran, bindings, and install targets. · `CMakeLists.txt`
- [CMake helpers](https://github.com/nasa/cea/tree/main/cmake): build modules · Reusable CMake logic for compiler flags, Cython, Python, and linking. · `cmake`
- [Python packaging](https://github.com/nasa/cea/blob/main/pyproject.toml): packaging · Python build configuration integrated with the source tree and CMake. · `pyproject.toml`

### Validation

Integration and binding tests.

- [CLI tests](https://github.com/nasa/cea/tree/main/test/main_interface): integration tests · Fortran-level tests that compare legacy CLI runs against reference outputs. · `test/main_interface`
- [Python tests](https://github.com/nasa/cea/tree/main/source/bind/python/tests): binding 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](https://github.com/nasa/cea/tree/main/docs/source): documentation · Sphinx documentation covering theory, installation, interfaces, and examples. · `docs/source`
- [CLI samples](https://github.com/nasa/cea/tree/main/samples): examples · Example input decks for the legacy executable. · `samples`
- [Python samples](https://github.com/nasa/cea/tree/main/source/bind/python/cea/samples): examples · Programmatic usage examples for the Python API. · `source/bind/python/cea/samples`
- [C samples](https://github.com/nasa/cea/tree/main/source/bind/c/samples): examples · Usage examples for the C interface. · `source/bind/c/samples`
- [MATLAB samples](https://github.com/nasa/cea/tree/main/source/bind/matlab/samples): examples · MATLAB usage examples that route through Python. · `source/bind/matlab/samples`

## Connections

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