Excel

The Excel interface provides worksheet user-defined functions (UDFs) for CEA from a macro-enabled workbook. The worksheet functions are implemented in VBA and call a native cea_excel.dll that wraps the C and Fortran CEA APIs.

This interface is beta/experimental. It is included as a complete optional interface for this release path, but future releases may refine workbook conventions or UDF signatures as users exercise the interface.

For most spreadsheet-oriented workflows, prefer the Python interface with Pandas: run CEA from Python, collect results in a pandas.DataFrame, and export with DataFrame.to_csv() or DataFrame.to_excel(). Use the Excel/VBA interface when you specifically need live worksheet formulas backed by CEA inside 64-bit Windows Excel.

Platform Support

The Excel interface should only be attempted with 64-bit Windows and 64-bit Excel/VBA. It is not an XLL add-in and it is not an Office.js add-in. macOS Excel/VBA and 32-bit Office are not supported.

The build option defaults to OFF so ordinary CEA builds are unchanged.

Build the Native Library

Run the build from a Windows developer prompt with C, C++, and Fortran compilers available. Configure with the Excel binding enabled, then build the cea_excel target. For example, with Visual Studio:

cmake -S . -B build-excel -G "Visual Studio 17 2022" -DCEA_ENABLE_BIND_EXCEL=ON
cmake --build build-excel --target cea_excel --config Release

If your shell already selects the desired CMake generator and compilers, the generator argument may be omitted:

cmake -S . -B build-excel -DCEA_ENABLE_BIND_EXCEL=ON
cmake --build build-excel --target cea_excel --config Release

The build writes cea_excel.dll below source/bind/excel/lib. With a multi-configuration generator, the DLL may be written below source/bind/excel/lib/Release.

Workbook Setup

Use source/bind/excel/cea_template.xlsm as the starting workbook, or import the VBA modules into another macro-enabled workbook:

  • source/bind/excel/vba/modCEADeclare.bas loads and declares the native DLL.

  • source/bind/excel/vba/modCEAUDF.bas exposes the worksheet UDFs.

  • source/bind/excel/vba/modCEATest.bas provides smoke-test macros.

Enable macros according to your organization's Excel security policy, then save the workbook before using the UDFs. The loader searches for cea_excel.dll relative to the workbook folder in these locations:

  • next to the workbook

  • lib\ below the workbook folder

  • lib\Release\ below the workbook folder

  • Release\ below the workbook folder

Keep required native DLL dependencies in the same folder as cea_excel.dll. Run the TestCEAVersion or TestCEAAdd macros first if formulas cannot load the native library.

Reactant Table

All solve and helper UDFs take a reactant table range. The first row must contain these headers:

name

role

base_amount

basis

H2(L)

fuel

1

weight

O2(L)

oxidizer

1

weight

role accepts fuel, oxidizer, and inert. basis accepts weight or mole. The species names must match CEA species names in the thermodynamic database.

For ratio-based solves, the table defines the fixed fuel, oxidizer, and inert vectors. The worksheet formula supplies the per-row amount mode, and the native wrapper computes the actual solve weights.

Solve UDFs

Each solve UDF spills one horizontal result row by default. The first three columns are:

  • status: native CEA status code for the call.

  • converged: TRUE when the CEA solution reports strict convergence.

  • message: OK or a diagnostic message from the wrapper/native solver.

Pass include_headers=TRUE to spill a two-row header/value block. This is useful while building a sheet or when selecting custom properties/species.

Equilibrium solves:

CEA_TP_SOLVE(reactants, T, P, [of_ratio], [phi], [r_eq],
             [pct_fuel], [weights], [T_reac], [properties],
             [species], [transport], [ions], [include_headers])
CEA_HP_SOLVE(reactants, H, P, ...)
CEA_SP_SOLVE(reactants, S, P, ...)
CEA_TV_SOLVE(reactants, T, V, ...)
CEA_UV_SOLVE(reactants, U, V, ...)
CEA_SV_SOLVE(reactants, S, V, ...)

Rocket solves:

CEA_ROCKET_IAC_SOLVE(reactants, pc, [pi_p], [subar], [supar],
                     [of_ratio], [phi], [r_eq], [pct_fuel],
                     [weights], [T_reac], [n_frz], [hc], [tc],
                     [tc_est], [omit], [insert], [properties],
                     [species], [transport], [ions], [include_headers])

CEA_ROCKET_FAC_SOLVE(reactants, pc, [pi_p], [subar], [supar],
                     [of_ratio], [phi], [r_eq], [pct_fuel],
                     [weights], [T_reac], [n_frz], [hc], [tc],
                     [mdot], [ac_at], [tc_est], [omit], [insert],
                     [properties], [species], [transport], [ions],
                     [include_headers])

Shock and detonation solves:

CEA_SHOCK_SOLVE(reactants, T0, p0, [u1], [Mach1], [of_ratio],
                [phi], [r_eq], [pct_fuel], [weights], [reflected],
                [incident_frozen], [reflected_frozen], [omit], [insert],
                [properties], [species], [transport], [ions],
                [include_headers])

CEA_DETONATION_SOLVE(reactants, T1, p1, [of_ratio], [phi], [r_eq],
                     [pct_fuel], [weights], [frozen], [omit], [insert],
                     [properties], [species], [transport], [ions],
                     [include_headers])

Amount Modes

Provide exactly one amount mode to each solve:

  • of_ratio: oxidizer/fuel weight ratio.

  • phi: fuel-air equivalence ratio.

  • r_eq: CEA equivalence ratio.

  • pct_fuel: percent fuel.

  • weights: explicit per-reactant weights whose length matches the reactant table.

For example, with a reactant table in A1:D3:

=CEA_TP_SOLVE($A$1:$D$3, 3000, 10, of_ratio:=6, include_headers:=TRUE)

Optional T_reac values may be a scalar or a vector matching the reactant table, depending on the solve type.

Properties and Species

If properties is omitted, each solver returns a compact default property set. Pass a worksheet range of property names to control the result columns. Transport properties are accepted only when transport=TRUE.

Supported property names are:

  • Equilibrium: T, P, volume, density, M, MW, enthalpy, energy, entropy, gibbs_energy, gamma_s, cp_fr, cv_fr, cp_eq, cv_eq, viscosity, conductivity_fr, conductivity_eq, Pr_fr, Pr_eq.

  • Rocket: all equilibrium names plus Mach, sonic_velocity, ae_at, c_star, coefficient_of_thrust, Isp, and Isp_vacuum.

  • Shock: T, P, velocity, Mach, sonic_velocity, rho12, rho52, P21, P52, T21, T52, M21, M52, v2, u5_p_v2, volume, density, M, MW, enthalpy, energy, entropy, gibbs_energy, gamma_s, cp_fr, cv_fr, cp_eq, cv_eq, viscosity, conductivity_fr, conductivity_eq, Pr_fr, Pr_eq.

  • Detonation: P1, T1, H1, M1, gamma1, sonic_velocity1, P, T, density, enthalpy, energy, gibbs_energy, entropy, Mach, velocity, sonic_velocity, gamma_s, P_P1, T_T1, M_M1, rho_rho1, cp_fr, cv_fr, cp_eq, cv_eq, M, MW, viscosity, conductivity_fr, conductivity_eq, Pr_fr, Pr_eq.

Species are omitted by default to keep sweep rows narrow. Pass a species range to append selected mass and mole fractions. Equilibrium and detonation species columns are labeled like mass_H2O and mole_H2O. Rocket and shock species columns include station labels, such as mass_H2O_throat or mole_H2O_incident.

Helper UDFs

The helper UDFs use the same reactant table convention:

  • CEA_WEIGHTS_FROM_OF computes per-reactant weights from an O/F ratio.

  • CEA_OF_FROM_EQUIVALENCE and CEA_OF_FROM_PHI convert ratio inputs to O/F.

  • CEA_EQUIVALENCE_FROM_OF and CEA_PHI_FROM_OF convert O/F to ratio outputs.

  • CEA_WEIGHTS_FROM_MOLES and CEA_MOLES_FROM_WEIGHTS convert reactant amounts.

  • CEA_PER_MOLE_FROM_PER_WEIGHT and CEA_PER_WEIGHT_FROM_PER_MOLE convert per-reactant extensive properties.

  • CEA_CALC_THERMO evaluates mixture thermodynamic properties for a set of weights and temperatures.

  • CEA_TO_SI and the CEA_PRESSURE_SI, CEA_TEMPERATURE_SI, CEA_ENERGY_SI, CEA_DENSITY_SI, and CEA_VOLUME_SI aliases convert supported unit strings to SI values.

  • CEA_VERSION returns the native wrapper version.

  • CEA_LAST_ERROR returns the last native wrapper error message.

Diagnostics and Tests

If a workbook reports a DLL load failure, check that the workbook is saved and that cea_excel.dll and its dependencies are in one of the loader search folders listed above. Then run TestCEAVersion or TestCEAAdd from modCEATest.bas.

For native validation, configure a Windows build with CEA_ENABLE_BIND_EXCEL=ON and run:

ctest -R "cea_excel_(version|api)_test" --output-on-failure