ensim.core.staging

Multi-stage sizing with the rocket equation. Thrust is given per engine; a stage's thrust is that times its engine count, scaled between sea level and vacuum with the US Standard Atmosphere pressure.

Multi-stage vehicle bookkeeping: stage masses, thrust, staging events and ideal (Tsiolkovsky) delta-v.

Engine thrust varies linearly with ambient pressure between the sea-level and vacuum values, F(h) = F_vac - (F_vac - F_sl) p(h) / p0, which is exact for a fixed nozzle running full. p(h) comes from the US Standard Atmosphere 1976.

References

Sutton & Biblarz, "Rocket Propulsion Elements", 9th ed., ch. 4.

StageEngine dataclass

Engine cluster of one stage.

Thrust is per engine; cluster values are multiplied by num_engines. Vacuum-only engines may leave the sea-level values at zero.

Attributes:

Name	Type	Description
thrust_sl_per_engine	float	Sea-level thrust of one engine, N.
thrust_vac_per_engine	float	Vacuum thrust of one engine, N.
isp_sl	float	Sea-level specific impulse, s.
isp_vac	float	Vacuum specific impulse, s.
num_engines	int	Engines in the cluster.
throttle_min	float	Deepest throttle setting while running, fraction.
throttle_max	float	Highest throttle setting, fraction.
gimbal_range_deg	float	Gimbal range, deg.
ignition_time	float	Delay between staging and full thrust, s.
shutdown_time	float	Thrust tail-off duration, s.

total_thrust_sl property

total_thrust_sl: float

Sea-level thrust of the whole cluster, N.

total_thrust_vac property

total_thrust_vac: float

Vacuum thrust of the whole cluster, N.

get_thrust

get_thrust(altitude: float, throttle: float = 1.0) -> float

Cluster thrust at an altitude and throttle setting, N.

A throttle of zero or less shuts the engines down; other values are clamped to the throttle limits.

get_isp

get_isp(altitude: float) -> float

Delivered specific impulse at an altitude, s.

get_mass_flow_rate

get_mass_flow_rate(altitude: float = 0.0, throttle: float = 1.0) -> float

Cluster propellant mass flow, kg/s.

altitude is accepted for symmetry with :meth:get_thrust; for a nozzle running full the flow does not depend on ambient pressure.

Stage dataclass

One stage of the stack.

Attributes:

Name	Type	Description
name	str	Stage identifier
dry_mass	float	Stage dry mass without propellant (kg)
propellant_mass	float	Total propellant mass (kg)
engine	StageEngine	Engine parameters
staging_trigger	StagingTrigger	What triggers separation
trigger_value	float | None	Value for time/altitude/velocity triggers
fairing_mass	float	Payload fairing mass if attached (kg)
fairing_jettison_alt	float | None	Altitude to jettison fairing (m), None to keep
interstage_mass	float	Interstage adapter mass (kg)
separation_impulse	float	Separation system impulse (N·s)
ullage_thrust	float	Ullage motor thrust for settling (N)
ullage_duration	float	Ullage motor burn duration (s)

total_mass property

total_mass: float

Total stage mass including remaining propellant.

propellant_fraction property

propellant_fraction: float

Remaining propellant as fraction of initial.

mass_ratio property

mass_ratio: float

Initial to final mass ratio (for delta-v calculation).

get_ideal_delta_v

get_ideal_delta_v(payload_mass: float = 0.0) -> float

Calculate ideal delta-v using Tsiolkovsky equation.

ΔV = Isp × g0 × ln(m_initial / m_final)

Parameters:

Name	Type	Description	Default
payload_mass	float	Additional payload mass (kg)	0.0

Returns:

Type	Description
float	Ideal delta-v (m/s)

consume_propellant

consume_propellant(mass_flow: float, dt: float) -> float

Consume propellant over timestep.

Parameters:

Name	Type	Description	Default
mass_flow	float	Mass flow rate (kg/s)	required
dt	float	Timestep (s)	required

Returns:

Type	Description
float	Actual mass consumed (kg)

is_depleted

is_depleted() -> bool

Check if propellant is exhausted.

reset

reset()

Reset stage to initial state.

MultiStageVehicle dataclass

Multi-stage launch vehicle model.

Handles staging logic, mass tracking, and thrust calculations for vehicles with arbitrary number of stages.

Stages are numbered from bottom (1) to top (N), with the payload on top of stage N.

Attributes:

Name	Type	Description
name	str	Vehicle name
stages	list[Stage]	List of stages (index 0 = bottom stage)
payload_mass	float	Payload mass on top (kg)
launch_site_altitude	float	Launch site altitude MSL (m)

active_stage property

active_stage: Stage | None

Get currently active stage.

total_mass property

total_mass: float

Total vehicle mass including all attached stages and payload.

remaining_stages property

remaining_stages: int

Number of stages not yet separated.

get_thrust

get_thrust(altitude: float, throttle: float = 1.0) -> float

Get current total thrust.

Parameters:

Name	Type	Description	Default
altitude	float	Current altitude (m)	required
throttle	float	Throttle setting (0-1)	1.0

Returns:

Type	Description
float	Total thrust (N)

get_mass_flow

get_mass_flow(altitude: float, throttle: float = 1.0) -> float

Get current mass flow rate.

Parameters:

Name	Type	Description	Default
altitude	float	Current altitude (m)	required
throttle	float	Throttle setting (0-1)	1.0

Returns:

Type	Description
float	Mass flow rate (kg/s)

get_isp

get_isp(altitude: float) -> float

Get current specific impulse.

step

step(dt: float, altitude: float, velocity: float, throttle: float = 1.0) -> list[StagingEvent]

Advance vehicle state by one timestep.

Handles propellant consumption, staging checks, and fairing jettison.

Parameters:

Name	Type	Description	Default
dt	float	Timestep (s)	required
altitude	float	Current altitude (m)	required
velocity	float	Current velocity magnitude (m/s)	required
throttle	float	Throttle setting (0-1)	1.0

Returns:

Type	Description
list[StagingEvent]	List of staging events that occurred

get_total_delta_v

get_total_delta_v() -> float

Calculate total ideal delta-v of the vehicle.

Uses serial staging calculation where each stage carries upper stages as payload.

Returns:

Type	Description
float	Total delta-v (m/s)

get_stage_delta_v_breakdown

get_stage_delta_v_breakdown() -> list[tuple[str, float]]

Get delta-v contribution of each stage.

Returns:

Type	Description
list[tuple[str, float]]	List of (stage_name, delta_v) tuples

reset

reset()

Reset vehicle to launch-ready state.

StagingEvent dataclass

Record of a staging event.

StagingTrigger

Bases: Enum

Conditions that trigger stage separation.

StageStatus

Bases: Enum

Stage operational status.

create_medium_lift_reference

create_medium_lift_reference() -> MultiStageVehicle

Create an editable two-stage reference vehicle.

create_heavy_lift_reference

create_heavy_lift_reference() -> MultiStageVehicle

Create an editable three-stage reference vehicle.

create_custom_vehicle

create_custom_vehicle(stage_configs: list[dict], payload_mass: float = 0.0, name: str = 'Custom Vehicle') -> MultiStageVehicle

Build a vehicle from plain dictionaries, bottom stage first.

Keys per stage: name, dry_mass (kg), propellant_mass (kg), thrust_sl_per_engine and thrust_vac_per_engine (N), isp_sl and isp_vac (s), num_engines, throttle_min, throttle_max, fairing_mass (kg) and fairing_jettison_alt (m). Masses, vacuum thrust and vacuum Isp are required.