ensim.core.flight_6dof

Six-degree-of-freedom flight of a Rocket. The model is described under flight dynamics.

Six-degree-of-freedom rigid-body flight simulation.

State vector (14 elements)::

[x, y, z, vx, vy, vz, q0, q1, q2, q3, wx, wy, wz, m_prop]

position        x, y, z     m      inertial frame (local ENU, or ECI in WGS-84 mode)
velocity        vx, vy, vz  m/s    inertial frame
attitude        q0..q3             unit quaternion, body -> inertial, scalar first
angular rate    wx, wy, wz  rad/s  body frame
propellant      m_prop      kg

Equations of motion::

dr/dt = v
dv/dt = R(q) (F_thrust + F_aero) / m + g(r)
dq/dt = 1/2 q (x) [0, w]
dw/dt = I^-1 (M - w x I w)
dm/dt = -mdot while burning

Every Runge-Kutta stage re-evaluates thrust, aerodynamics, mass, inertia and gravity from that stage's state, so the integrators keep their nominal order.

Body axes: x forward through the nose, y and z complete a right-handed set. Positions along the airframe (CG, CP) are measured aft from the nose tip.

References

Stevens, Lewis & Johnson, "Aircraft Control and Simulation", 3rd ed. Zipfel, "Modeling and Simulation of Aerospace Vehicle Dynamics", 3rd ed.

FlightResult6DOF dataclass

Time histories and summary values of one 6-DOF run.

Positions and velocities are reported in the local ENU frame of the launch site in both integration modes.

PhysicsViolationError

Bases: Exception

Raised when the inputs or the integrated state are not physical.

SimulationCancelled

Bases: Exception

Raised inside a long calculation when the caller's cancel callback returns True.

simulate_flight_6dof

simulate_flight_6dof(rocket: Rocket, thrust_vac: float, isp_vac: float, burn_time: float, exit_area: float = 0.0, dt: float = 0.01, max_time: float = 300.0, launch_angle_deg: float = 85.0, launch_azimuth_deg: float = 0.0, rail_length: float = 3.0, wind_speed: float = 0.0, wind_direction_deg: float = 0.0, use_adaptive: bool = False, rtol: float = 1e-06, atol: float = 1e-06, h_min: float = 1e-05, h_max: float = 1.0, output_dt: float = 0.01, throttle: float = 1.0, cd_factor: float = 1.0, fin_misalignment_deg: float = 0.0, chute_diameter: float = 0.0, deploy_at_apogee: bool = True, nozzle_exit_pressure: float | None = None, use_wgs84: bool = False, launch_latitude_deg: float = 0.0, launch_longitude_deg: float = 0.0, launch_altitude_m: float = 0.0, chute_cd: float = 1.5, main_deploy_altitude_m: float = 300.0, wind_profile_top_m: float = 1000.0, cancel: Callable[[], bool] | None = None, drogue_diameter: float = 0.0, progress: Callable[[float], None] | None = None, drogue_cd: float = 1.2, parachute_fill_time: float = 1.0) -> FlightResult6DOF

Simulate a single-stage flight with 6-DOF rigid-body dynamics.

Parameters:

Name	Type	Description	Default
rocket	Rocket	Vehicle definition. It is not modified.	required
thrust_vac	float	Vacuum thrust, N.	required
isp_vac	float	Vacuum specific impulse, s.	required
burn_time	float	Burn duration, s. The engine also stops when the propellant is exhausted.	required
exit_area	float	Nozzle exit area, m^2. Thrust is thrust_vac minus ambient pressure times this area; the default 0 keeps the vacuum thrust at every altitude.	0.0
dt	float	Step for the fixed-step RK4 integrator, s.	0.01
max_time	float	Simulation end time, s.	300.0
launch_angle_deg	float	Rail elevation above the horizon (90 = vertical).	85.0
launch_azimuth_deg	float	Rail heading, clockwise from north.	0.0
rail_length	float	Rail length, m. Attitude is held until the vehicle clears it.	3.0
wind_speed	float	Surface wind at 10 m, m/s.	0.0
wind_direction_deg	float	Direction the wind blows from, clockwise from north.	0.0
use_adaptive	bool	Use Dormand-Prince 5(4) with error control instead of RK4.	False
rtol	float	Relative error tolerance for the adaptive integrator.	1e-06
atol	float	Absolute error tolerance for the adaptive integrator.	1e-06
h_min	float	Smallest adaptive step, s.	1e-05
h_max	float	Largest adaptive step, s.	1.0
output_dt	float	Spacing of output samples, s. Adaptive steps are not limited by it; samples are interpolated from the step polynomial.	0.01
throttle	float	Thrust and mass-flow multiplier in [0, 1].	1.0
cd_factor	float	Multiplier on the vehicle drag coefficient.	1.0
fin_misalignment_deg	float	Fin incidence error in the pitch plane. Produces a normal force and a trim moment proportional to dynamic pressure.	0.0
chute_diameter	float	Recovery parachute diameter, m (0 = no parachute).	0.0
deploy_at_apogee	bool	Deploy at apogee; otherwise deploy after apogee once below main_deploy_altitude_m.	True
nozzle_exit_pressure	float | None	Nozzle exit pressure, Pa, for the expansion-regime label. Does not change thrust.	None
use_wgs84	bool	Integrate in ECI with WGS-84 J2 gravity and Earth rotation.	False
launch_latitude_deg	float	Geodetic latitude of the pad in WGS-84 mode.	0.0
launch_longitude_deg	float	Longitude of the pad in WGS-84 mode.	0.0
launch_altitude_m	float	Height of the pad above the WGS-84 ellipsoid, m.	0.0
chute_cd	float	Main parachute drag coefficient on its nominal area.	1.5
drogue_diameter	float	Drogue diameter, m (0 = none). With a drogue the drogue opens at apogee and the main at main_deploy_altitude_m; both then stay attached.	0.0
drogue_cd	float	Drogue drag coefficient.	1.2
parachute_fill_time	float	Time for a canopy to inflate, s. Drag area grows linearly over it; zero means instant inflation and overstates the opening load.	1.0
main_deploy_altitude_m	float	Height above the pad for a delayed deployment.	300.0
wind_profile_top_m	float	The 1/7 power-law wind profile grows up to this height and stays constant above it.	1000.0
cancel	Callable[[], bool] | None	Optional callable polled once per step; return True to stop.	None
progress	Callable[[float], None] | None	Optional callable receiving t / max_time every 200 steps.	None

Raises:

Type	Description
PhysicsViolationError	Invalid inputs or a non-finite state.
SimulationCancelled	cancel returned True.

Vehicle

rocket

Rocket Component Definitions.

Defines the structural components of a rocket vehicle for flight simulation and stability analysis.

Rocket dataclass

Complete rocket vehicle definition.

Combines all components and provides aggregate properties.

total_length property

total_length: float

Total rocket length (m).

reference_diameter property

reference_diameter: float

Reference diameter for aerodynamics (m).

reference_area property

reference_area: float

Reference area for aerodynamics (m²).

dry_mass property

dry_mass: float

Total dry mass without propellant (kg).

wet_mass property

wet_mass: float

Total mass with full propellant (kg).

initial_propellant_mass property

initial_propellant_mass: float

Propellant loaded at liftoff, kg (initial value of state[13]).

propellant_at_time

propellant_at_time(t: float) -> float

Propellant left at time t after ignition, kg.

Uses engine.mass_flow_rate and engine.burn_time when they are set. Without a burn definition the tanks are reported full, which is the liftoff configuration stability checks need.

get_mass_at_time

get_mass_at_time(t: float) -> float

Total mass at time t after ignition, kg.

get_cg_at_time

get_cg_at_time(t: float) -> float

CG position from the nose tip at time t after ignition, m.

get_mass_from_propellant

get_mass_from_propellant(m_prop: float) -> float

Total mass for a given remaining propellant mass, kg.

get_cg_from_propellant

get_cg_from_propellant(m_prop: float) -> float

CG position from the nose tip for a given remaining propellant mass, m.

The propellant is lumped at engine.position (the tank centre).

NoseShape

Bases: Enum

Nose cone shape types.

NoseCone dataclass

Nose cone component.

Attributes:

Name	Type	Description
shape	NoseShape	Aerodynamic shape type
length	float	Total length (m)
diameter	float	Base diameter (m)
mass	float	Component mass (kg)
material	str	Material name for reference

fineness_ratio property

fineness_ratio: float

Length to diameter ratio.

volume property

volume: float

Enclosed volume, m³ (tangent ogive approximated by the paraboloid value).

position_cg property

position_cg: float

CG distance from the tip, m, for a thin shell of uniform thickness.

Laid-up and printed noses are shells, so the surface centroid is the better estimate: 2/3 L for a cone, about 0.6 L for the rounder shapes.

BodyTube dataclass

Cylindrical body tube component.

Attributes:

Name	Type	Description
length	float	Tube length (m)
diameter	float	Outer diameter (m)
wall_thickness	float	Wall thickness (m)
mass	float	Component mass (kg)

inner_diameter property

inner_diameter: float

Inner diameter (m).

cross_section_area property

cross_section_area: float

Reference cross-section area (m²).

wetted_area property

wetted_area: float

External surface area (m²).

FinSet dataclass

Set of fins around the body.

Attributes:

Name	Type	Description
fin	Fin	Single fin geometry
count	int	Number of fins (typically 3 or 4)
position	float	Distance from nose tip to fin root leading edge (m)
mass	float	Total mass of all fins (kg)

total_area property

total_area: float

Total planform area of all fins (m²).

EngineMount dataclass

Engine mount and propellant configuration.

Links the engine simulation results to the vehicle.

propellant_mass property

propellant_mass: float

Total propellant mass (kg).

total_mass property

total_mass: float

Total mass including propellant (kg).

create_default_rocket

create_default_rocket() -> Rocket

A small liquid-propellant sounding rocket, 9 kg at liftoff.

The tank holds 3.2 kg of LOX/kerosene at O/F 3 in 0.45 m of a 0.12 m airframe, and the static margin is about 1.4 calibers with full tanks.

Atmosphere

mission

Atmosphere and steady altitude-performance analysis.

Implements the U.S. Standard Atmosphere 1976 and engine altitude sweeps.

AtmosphereState dataclass

Atmospheric conditions at an altitude.

atmosphere_properties

atmosphere_properties(z: float) -> tuple[float, float, float, float]

Temperature, pressure, density and speed of sound at geometric altitude z.

Negative altitudes are clamped to sea level. Returns (T [K], P [Pa], rho [kg/m³], a [m/s]). Numba-compiled so the flight kernel can call it.

get_atmosphere

get_atmosphere(altitude: float) -> AtmosphereState

Atmospheric state at a geometric altitude (m), US Standard Atmosphere 1976.

geopotential_altitude

geopotential_altitude(z: float) -> float

Convert geometric altitude z (m) to US76 geopotential altitude (m').