CEA (Chemical Equilibrium with Applications)

A modernized version of NASA's Chemical Equilibrium with Applications.

Online documentation and examples are located at https://nasa.github.io/cea/

Overview

The NASA software package CEA (Chemical Equilibrium with Applications) enables
the rapid solution of chemical equilibrium problems for complex mixtures.
The core solver computes equilibrium product concentrations given a set
of reactants and thermodynamic states. These product concentrations are then
used to compute the thermodynamic and transport properties of the equilibrium
mixture. Applications include estimation of theoretical rocket performance,
Chapman-Jouguet detonation characteristics, and shock-tube parameters for
incident and reflected shocks. Associated with the program are independent
databases with transport and thermodynamic properties of individual species. Over
2000 species are contained in the thermodynamic database.

This software repository is a complete re-implementation of the original CEA
software, with initial development supported by the NASA Engineering & Safety
Center (NESC). The software represents the latest evolution of a series of
computer programs that developed at the NASA Glenn (formerly Lewis) Research
Center since the 1950s. The primary goals of the re-implementation were to modernize
the CEA code base to adopt modern software engineering practices and improve
CEA's ability to interface with other software packages and analysis environments
via well-defined programming APIs in multiple languages.

Install (Recommended)

For most users, install the published Python package directly:

python -m pip install cea

This is the fastest path to start using the Python API (import cea) without
building from source.

If you need the legacy CLI executable (cea) or C/Fortran build artifacts, use
the source build path below.

Prebuilt release assets are also available on the GitHub Releases page,
including platform executables and shared libraries (.so, .dll, .lib,
.dll.a).

Build and Install from Source

The CEA software package is compiled and installed using CMake v3.19+. The core
software has no external dependencies, and is known to build successfully on a
wide range of platforms and using the Intel and GNU Fortran compilers. The basic
installation process is as follows:

cd <cea_source_dir>
mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX=<cea_install_dir> -DCEA_BUILD_TESTING=OFF ..
cmake --build .
cmake --install .

This will build and install the cea executable, libcea library, default
thermodynamic and transport property databases, documentation, and sample
problems to the user-specified cea_install_dir.

Upon installation, all that is required to use the cea applications is to add
the CEA install directory to the user's PATH environment variable, e.g.:

export PATH="<cea_install_dir>/bin:$PATH"

Once properly configured, you should be able to run the provided sample problems
from any working directory as follows:

cea <cea_source_dir>/samples/rp1311_examples

Build Prerequisites

To build the Python bindings from source, Ninja is required (scikit-build-core
uses the Ninja generator). Ensure ninja is available on your PATH before
running pip install . or pip install -e ..

Minimal Builds

If you want a Fortran-only build or a Fortran+C build without Python/Cython/NumPy
dependencies, use the presets below.

Fortran-only (no C/Python bindings):

cmake --preset core
cmake --build build-core
cmake --install build-core

Fortran + C (no Python bindings):

cmake --preset core-c
cmake --build build-core-c
cmake --install build-core-c

If you are not using presets, set -DCEA_ENABLE_BIND_PYTHON=OFF and also disable
the MATLAB wrapper (it forces Python on). For Fortran-only, also set
-DCEA_ENABLE_BIND_C=OFF.

Python Binding from a Source Checkout

The new Python binding provides direct access to compiled CEA routines.
If you are developing locally or want to build from a checkout, use:

cd <cea_source_dir>
pip install .

A binary wheel distribution can also be generated with the following:

cd <cea_source_dir>
pip wheel --no-deps -w dist .

This will build a standalone binary wheel distribution in the ./dist
directory. This distribution can then be installed on compatible local hosts
with:

pip install path/to/wheel/<wheel-file-name>

The Python binding to CEA has been successfully compiled and executed on macOS,
Linux, and Windows systems.

Examples

Legacy CLI (classic .inp deck - run this from the build/source directory):

./cea ../samples/example1

Note that specifying the .inp extension for input files is optional.

Python example (runs the H2/O2 case after installing the Python bindings):

python source/bind/python/cea/samples/h2_o2.py

Database Generation

CEA requires thermodynamic and transport property databases. When using the
provided CMake build system, these databases are automatically compiled from
data/thermo.inp and data/trans.inp during the build process and installed
alongside the cea executable.

Custom Database Generation

In many applications it is necessary to perform calculations with modified
versions of the provided databases. To generate custom databases, run the cea
program in compilation mode with your modified input files:

./cea --compile-thermo path/to/thermo.inp
./cea --compile-trans path/to/trans.inp

This will produce thermo.lib and trans.lib in the current directory.

To use the customized databases, copy them into the working directory where you
will be executing the cea program (usually the same directory as the .inp
problem definition file). Database files in the working directory will take
precedence over the installed database files in <cea_install_dir>/data/.

Database Lookup

CEA locates thermo.lib and trans.lib in the following order:

• For the CLI and C/Fortran APIs: current working directory, CEA_DATA_DIR (if
  set), ./data, then <cea_install_dir>/data.
• For Python (cea.init() with no path): current working directory,
  CEA_DATA_DIR (if set), packaged cea/data, then the repo data/ directory
  when running from a source checkout.

You can override the search path by setting CEA_DATA_DIR or by passing explicit
paths:

export CEA_DATA_DIR=/path/to/cea/data

import cea
cea.init("/path/to/cea/data")

References

1. McBride, B.J., Zehe, M. J., Gordon, S., "NASA Glenn Coefficients for Calculating Thermodynamic Properties of Individual Species",
   NASA TP-2002-211556, 2002. NTRS
2. McBride, B.J., Gordon, S., and Reno, M.A., "Thermodynamic Data for Fifty Reference Elements",
   NASA TP-3287/REV1, 2001. NTRS
3. Gordon, S., McBride, B.J., "Thermodynamic Data to 20 000 K for Monatomic Gases",
   NASA TP-1999-208523, 1999. NTRS
4. Svehla, R.A., "Transport Coefficients for the NASA Lewis Chemical Equilibrium Program",
   NASA TM-4647, 1995. NTRS
5. McBride, B.J., and Gordon, S., "Computer Program for Calculating and Fitting Thermodynamic Functions",
   NASA RP-1271, 1992. NTRS