Other modules

Units

units

Unit conversion for display and data exchange.

Calculations inside EnSim are SI. This module converts values at the edges (input fields, tables, exported files). Units are grouped by physical quantity, so a symbol only has to be unique within its quantity: "g" is a gram for MASS and standard gravity for ACCELERATION.

Conversion factors are exact where a definition exists (international foot and pound, standard gravity, standard atmosphere).

Quantity

Bases: Enum

UnitSystem

Bases: Enum

to_si

to_si(value: float, quantity: Quantity, unit: str) -> float

Convert value expressed in unit to the SI unit of quantity.

from_si

from_si(value: float, quantity: Quantity, unit: str) -> float

Convert an SI value of quantity to unit.

convert

convert(value: float, quantity: Quantity, from_unit: str, to_unit: str) -> float

Convert between two units of the same quantity.

display_unit

display_unit(quantity: Quantity, system: UnitSystem = UnitSystem.SI) -> str

Unit the interface uses for quantity in system.

Projects

project_manager

Reading and writing .ensim project files.

A project is JSON with five sections: meta, engine, rocket, recovery, environment and an optional results cache. Files written by EnSim 1.x (flat engine keys) and 3.x load unchanged; missing fields take their defaults and unknown fields are ignored with a log message, so newer files still open in older versions.

ProjectManager

Holds the open project and its file path.

save

save(path: Path | str | None = None) -> Path

Write the project and return the path written.

Raises:

Type	Description
ProjectFileError	No path is known or the file cannot be written.

load

load(path: Path | str) -> ProjectData

Read a project file.

Raises:

Type	Description
ProjectFileError	The file cannot be read or is not a valid project.

update_inputs

update_inputs(fuel: str, oxidizer: str, of_ratio: float, chamber_pressure_bar: float, throat_area_cm2: float, expansion_ratio: float, ambient_pressure_bar: float) -> None

Set the main engine inputs.

update_from_ui

update_from_ui(engine_params: dict, rocket_params: dict, recovery_params: dict, environment_params: dict) -> None

Copy matching keys from the UI dictionaries into the project.

build_rocket

build_rocket() -> Rocket

Rocket described by the project.

build_recovery

build_recovery() -> tuple[Parachute, Parachute | None]

Main parachute and, with dual deployment, the drogue.

ProjectData dataclass

Everything stored in one project file.

ProjectFileError

Bases: Exception

A project file could not be read or written. The message is user-facing.

Equilibrium

chemistry

Chemical equilibrium by Gibbs free energy minimisation.

The minimum is found in two passes: SLSQP on the mole numbers subject to element balance, then a least-squares polish of the optimality conditions (element potentials). The adiabatic flame temperature is the root of the enthalpy balance, bracketed and solved with Brent's method.

References

• Gordon, S. & McBride, B.J. (1994). NASA RP-1311.

CombustionProblem

Combustion equilibrium problem solver.

add_fuel

add_fuel(species_name: str, moles: float = 1.0, temperature: float = 298.15, *, formula: str | None = None, molar_enthalpy: float | None = None) -> None

Add a fuel. formula and molar_enthalpy describe reactants not in the database.

add_oxidizer

add_oxidizer(species_name: str, moles: float = 1.0, temperature: float = 298.15, *, formula: str | None = None, molar_enthalpy: float | None = None) -> None

Add an oxidizer; see :meth:add_fuel.

calculate_input_enthalpy

calculate_input_enthalpy() -> float

Total enthalpy of the reactants at their inlet temperatures, J.

solve

solve(pressure: float = P_ATM, initial_temp_guess: float = 3000.0, max_iterations: int = 50, tolerance: float = 1e-05) -> EquilibriumResult

Solve for equilibrium.

Cooling

cooling

Regenerative cooling thermal analysis module.

Provides detailed thermal modeling for rocket engine cooling: - Regenerative cooling channel design - Heat transfer calculations (gas-side and coolant-side) - Wall temperature prediction - Thermal stress analysis

References

• Huzel & Huang, "Modern Engineering for Design of Liquid-Propellant Rocket Engines"
• Sutton & Biblarz, "Rocket Propulsion Elements", 9th ed., Ch. 8
• Bartz correlation for gas-side heat transfer

CoolingSystemDesign dataclass

Complete regenerative cooling system design.

CoolingChannel dataclass

Definition of a cooling channel.

Attributes:

Name	Type	Description
width	float	Channel width (m)
height	float	Channel height (m)
wall_thickness	float	Inner wall thickness (m)
land_width	float	Width between channels (m)
num_channels	int	Number of channels around circumference
length	float	Total channel length (m)

hydraulic_diameter property

hydraulic_diameter: float

Calculate hydraulic diameter Dh = 4A/P.

flow_area property

flow_area: float

Total flow area of all channels.

surface_area property

surface_area: float

Total heat transfer surface area.

analyze_cooling_system

analyze_cooling_system(design: CoolingSystemDesign, nozzle_profile: list[tuple[float, float]], chamber_conditions: dict, num_stations: int = 50) -> list[ThermalAnalysisResult]

Perform thermal analysis along the nozzle.

Calculates wall temperatures, heat fluxes, and coolant conditions at multiple stations along the nozzle.

Parameters:

Name	Type	Description	Default
design	CoolingSystemDesign	Cooling system design parameters	required
nozzle_profile	list[tuple[float, float]]	List of (axial_position, diameter) tuples	required
chamber_conditions	dict	Dict with T_chamber, P_chamber, gamma, c_star	required
num_stations	int	Number of analysis stations	50

Returns:

Type	Description
list[ThermalAnalysisResult]	List of ThermalAnalysisResult at each station

bartz_heat_transfer_coefficient

bartz_heat_transfer_coefficient(D_throat: float, P_chamber: float, c_star: float, T_chamber: float, gamma: float, Pr: float, mu_ref: float, area_ratio: float, local_diameter: float, throat_radius_of_curvature: float | None = None, wall_temperature: float | None = None, molecular_weight: float = 22.0, supersonic: bool = True) -> float

Calculate gas-side heat transfer coefficient using Bartz correlation.

The Bartz equation is the standard correlation for rocket nozzle heat transfer, based on pipe flow correlations with modifications for acceleration and compressibility effects.

h_g = (0.026/D_t^0.2)(μ^0.2 Cp/Pr^0.6)(Pc/c*)^0.8 × (D_t/r_c)^0.1 × (A_t/A)^0.9 × σ

Parameters:

Name	Type	Description	Default
D_throat	float	Throat diameter (m)	required
P_chamber	float	Chamber pressure (Pa)	required
c_star	float	Characteristic velocity (m/s)	required
T_chamber	float	Chamber temperature (K)	required
gamma	float	Specific heat ratio	required
Pr	float	Prandtl number	required
mu_ref	float	Reference dynamic viscosity (Pa·s)	required
area_ratio	float	Local area ratio (A/At)	required
local_diameter	float	Local nozzle diameter (m)	required
throat_radius_of_curvature	float | None	Throat contour radius (m); defaults to D_t	None
wall_temperature	float | None	Gas-side wall temperature for the property correction (K)	None
molecular_weight	float	Gas molecular weight (kg/kmol)	22.0
supersonic	bool	Select the supersonic area-Mach branch	True

Returns:

Type	Description
float	Gas-side heat transfer coefficient (W/(m²·K))

Reference

Bartz, D.R. (1957). "A Simple Equation for Rapid Estimation of Rocket Nozzle Convective Heat Transfer Coefficients" Jet Propulsion, Vol. 27, No. 1, pp. 49-51.

coolant_heat_transfer_coefficient

coolant_heat_transfer_coefficient(reynolds: float, prandtl: float, conductivity: float, hydraulic_diameter: float) -> float

Return a single-phase internal-flow coefficient using Gnielinski.

Acoustics

instability

Combustion Instability Analysis Module.

Analyzes combustion chambers for acoustic instabilities including: - Longitudinal (axial) modes - Transverse (tangential and radial) modes - Low-frequency chugging

References

1. Harrje & Reardon, "Liquid Propellant Rocket Combustion Instability", NASA SP-194, 1972.
2. Yang & Anderson, "Liquid Rocket Engine Combustion Instability", AIAA Progress in Astronautics, 1995.

InstabilityResult dataclass

Complete combustion instability analysis.

is_stable property

is_stable: bool | None

Return modal stability, or None when response data was not supplied.

most_critical_mode property

most_critical_mode: StabilityMargin | None

Find the mode with smallest stability margin.

get_modes_in_range

get_modes_in_range(f_min: float, f_max: float) -> list[AcousticMode]

Get all modes within a frequency range.

AcousticMode dataclass

An acoustic mode of the combustion chamber.

name property

name: str

Standard mode name (e.g., 1L, 1T, 2R).

analyze_combustion_instability

analyze_combustion_instability(chamber_length: float, chamber_diameter: float, gamma: float, T_chamber: float, mean_mw: float, feed_line_length: float = 1.0, feed_line_area: float | None = None, propellant_density: float | None = None, feed_system_compliance: float | None = None, modal_rate_data: dict[str, tuple[float, float]] | None = None) -> InstabilityResult

Perform complete combustion instability analysis.

Calculates ideal cylindrical-chamber acoustic modes. Stability margins are only evaluated when measured or independently modelled modal driving and damping rates are supplied in consistent units of 1/s.

Parameters:

Name	Type	Description	Default
chamber_length	float	Combustion chamber length (m)	required
chamber_diameter	float	Chamber diameter (m)	required
gamma	float	Ratio of specific heats	required
T_chamber	float	Chamber temperature (K)	required
mean_mw	float	Mean molecular weight (g/mol)	required
feed_line_length	float	Propellant feed line length (m)	1.0
feed_line_area	float | None	Feed-line flow area (m²)	None
propellant_density	float | None	Feed propellant density (kg/m³)	None
feed_system_compliance	float | None	Lumped feed/chamber compliance (m³/Pa)	None
modal_rate_data	dict[str, tuple[float, float]] | None	Mapping from mode name to (driving, damping) rates (1/s)	None

Returns:

Type	Description
InstabilityResult	Complete InstabilityResult with all modes and stability analysis

calculate_chugging_frequency

calculate_chugging_frequency(propellant_density: float, feed_line_length: float, feed_line_area: float, system_compliance: float) -> float

Estimate low-frequency chugging frequency.

Chugging occurs when feed system hydraulics couple with chamber pressure oscillations. Typical range: 50-500 Hz.

Lumped inertance-compliance model: f_chug = (1/2π) sqrt(A / (ρ L C))

Parameters:

Name	Type	Description	Default
propellant_density	float	Propellant density (kg/m³)	required
feed_line_length	float	Feed line length (m)	required
feed_line_area	float	Feed line cross-section area (m²)	required
system_compliance	float	Combined feed/chamber volume compliance (m³/Pa)	required

Returns:

Type	Description
float	Estimated chugging frequency (Hz)

Engine uncertainty

engine_uq

Reduced-order uncertainty propagation for ideal rocket-engine performance.

EngineUQInput dataclass

Nominal ideal-nozzle inputs and fractional one-sigma uncertainties.

EngineUQAnalyzer

Propagate aleatory input uncertainty through the ideal frozen-nozzle model.

run

run(inputs: EngineUQInput, n_samples: int = 1000, ambient_pressure: float = 0.0, thrust_threshold: float | None = None, seed: int | None = None) -> EngineUQResult

Draw independent samples and propagate them through the reduced-order model.

run_sequential

run_sequential(inputs: EngineUQInput, n_samples: int = 1000, ambient_pressure: float = 0.0, seed: int | None = None) -> EngineUQResult

Run without child processes for GUI and constrained environments.

EngineUQResult dataclass

Samples and descriptive statistics from engine uncertainty propagation.

get_confidence_interval

get_confidence_interval(confidence: float = 0.95) -> dict[str, tuple[float, float]]

Return central empirical intervals for thrust, Isp, and c*.