pycontrails.physics.jet

Jet aircraft trajectory and performance parameters.

This module includes common functions to calculate jet aircraft trajectory and performance parameters, including fuel quantities, mass, thrust setting, propulsion efficiency and load factors.

Functions

acceleration(true_airspeed, segment_duration)

Calculate the acceleration/deceleration at each waypoint.

air_to_fuel_ratio(thrust_setting, *[, ...])

Calculate air-to-fuel ratio from thrust setting.

aircraft_payload(*, max_payload[, ...])

Estimate the payload mass based on the aircraft role.

cargo_load_factor([origin_airport_icao, ...])

Estimate cargo load factor carried by passenger aircraft and dedicated freighters.

climb_descent_angle(true_airspeed, rocd)

Calculate angle between the horizontal plane and the actual flight path.

clip_mach_number(true_airspeed, ...)

Compute the Mach number from the true airspeed and ambient temperature.

combustor_inlet_pressure(pressure_ratio, ...)

Calculate combustor inlet pressure, \(P_{3}\).

combustor_inlet_temperature(comp_efficiency, ...)

Calculate combustor inlet temperature, \(T_{3}\).

compressor_inlet_pressure(p, mach_num)

Calculate compressor inlet pressure for Jet engine, \(P_{2}\).

compressor_inlet_temperature(T, mach_num)

Calculate compressor inlet temperature for Jet engine, \(T_{2}\).

dedicated_freighter_payload(max_payload, ...)

Estimate payload for passenger aircraft.

density_ratio(rho)

Calculate the ratio of air density relative to the air density at mean-sea-level.

equivalent_fuel_flow_rate_at_cruise(...)

Convert fuel mass flow rate at sea level to equivalent fuel flow rate at cruise conditions.

equivalent_fuel_flow_rate_at_sea_level(...)

Convert fuel mass flow rate at cruise conditions to equivalent flow rate at sea level.

fuel_burn(fuel_flow, segment_duration)

Calculate the fuel consumption at each waypoint.

initial_aircraft_mass(*, amass_oew, ...[, ...])

Estimate initial aircraft mass as a function of load factor and fuel requirements.

number_of_seats([aircraft_type])

Estimate number of seats for the provided aircraft type.

overall_propulsion_efficiency(true_airspeed, ...)

Calculate the overall propulsion efficiency (OPE).

passenger_aircraft_payload(max_payload, ...)

Estimate payload for passenger aircraft.

passenger_load_factor([origin_airport_icao, ...])

Estimate passenger load factor based on historical data.

pressure_ratio(p)

Calculate the ratio of ambient pressure relative to the surface pressure.

reserve_fuel_requirements(rocd, altitude_ft, ...)

Estimate reserve fuel requirements.

temperature_ratio(T)

Calculate the ratio of ambient temperature relative to the temperature at mean sea level.

thrust_force(altitude, true_airspeed, ...)

Calculate the thrust force at each waypoint.

thrust_setting_nd(true_airspeed, ...[, ...])

Calculate the non-dimensionalized thrust setting of a Jet engine.

turbine_inlet_temperature(afr, T_comb_inlet, ...)

Calculate turbine inlet temperature, \(T_{4}\).

update_aircraft_mass(*, amass_oew, ...)

Update aircraft mass based on the simulated total fuel consumption.
pycontrails.physics.jet.acceleration(true_airspeed, segment_duration)

Calculate the acceleration/deceleration at each waypoint.

Parameters:

  • true_airspeed (npt.NDArray[np.floating]) – True airspeed, [\(m \ s^{-1}\)]

  • segment_duration (npt.NDArray[np.floating]) – Time difference between waypoints, [\(s\)]

Returns:

npt.NDArray[np.floating] – Acceleration/deceleration, [\(m \ s^{-2}\)]

See also

pycontrails.Flight.segment_duration

pycontrails.physics.jet.air_to_fuel_ratio(thrust_setting, *, cruise=False, T_compressor_inlet=None)

Calculate air-to-fuel ratio from thrust setting.

Parameters:

  • thrust_setting (ArrayScalarLike) – Engine thrust setting, unitless

  • cruise (bool) – Estimate thrust setting for cruise conditions. Defaults to False.

  • T_compressor_inlet (None | ArrayScalarLike) – Compressor inlet temperature, [\(K\)] Required if cruise is True. Defaults to None

Returns:

ArrayScalarLike – Air-to-fuel ratio, unitless

References

pycontrails.physics.jet.aircraft_payload(*, max_payload, aircraft_role='Passenger', n_seats=0, pax_lf=0.8, pax_mass=100.0, cargo_lf=0.2)

Estimate the payload mass based on the aircraft role.

Parameters:

  • max_payload (float) – Aircraft maximum payload, [\(kg\)]

  • aircraft_role (str) – Aircraft role, i.e., “Passenger”, “Cargo”, “Others”, etc. Assumes passenger aircraft (i.e., “Passenger”) by default. For dedicated freighters, the aircraft role should be set to “Cargo”.

  • n_seats (int) – Total number of seats in passenger aircraft

  • pax_lf (float) – Passenger load factor (between 0 and 1). Refer to passenger_load_factor() for historical values. Otherwise, defaults to 0.8

  • pax_mass (float) – Assumed passenger plus baggage mass, [\(kg\)] Defaults to the ICAO-recommend value of 100 kg

  • cargo_lf (float) – Cargo load factor (between 0 and 1) For “Passenger” aircraft, this is the assumed cargo load factor in the passenger hold. For “Cargo” aircraft, this is the assumed cargo load factor for dedicated freighters. Refer to cargo_load_factor() for reference values for passenger aircraft and freighters.

Returns:

float – Estimated aircraft payload, [\(kg\)]

References

pycontrails.physics.jet.cargo_load_factor(origin_airport_icao=None, destination_airport_icao=None, total_flight_dist=None, passenger_aircraft=True)

Estimate cargo load factor carried by passenger aircraft and dedicated freighters.

Accounts for regional asymmetries in freight flow and distance-specific variability

Parameters:

  • origin_airport_icao (str | None) – ICAO code of origin airport. If None is provided, then assume global mean values.

  • destination_airport_icao (str | None) – ICAO code of destination airport. If None is provided, then assume global mean values.

  • total_flight_dist (float) – Total flight distance flown, [\(km\)] Use great-circle distance between first and last known waypoint for consistency with the cargo database.

  • passenger_aircraft (bool) – Use cargo load factors for the passenger hold if true, otherwise use cargo load factors for dedicated freighters

Returns:

float – Passenger load factor [0 - 1], unitless

pycontrails.physics.jet.climb_descent_angle(true_airspeed, rocd)

Calculate angle between the horizontal plane and the actual flight path.

Parameters:

  • true_airspeed (npt.NDArray[np.floating]) – True airspeed, [\(m \ s^{-1}\)]

  • rocd (npt.NDArray[np.floating]) – Rate of climb/descent, [\(ft min^{-1}\)]

Returns:

npt.NDArray[np.floating] – Climb (positive value) or descent (negative value) angle, [\(\deg\)]

See also

pycontrails.Flight.segment_rocd, pycontrails.Flight.segment_true_airspeed

pycontrails.physics.jet.clip_mach_number(true_airspeed, air_temperature, max_mach_number)

Compute the Mach number from the true airspeed and ambient temperature.

This method clips the computed Mach number to the value of max_mach_number.

If no mach number exceeds max_mach_number, the original array true_airspeed and the computed Mach number are returned.

Parameters:

  • true_airspeed (npt.NDArray[np.floating]) – Array of true airspeed, [\(m \ s^{-1}\)]

  • air_temperature (npt.NDArray[np.floating]) – Array of ambient temperature, [:math: K]

  • max_mach_number (ArrayOrFloat) – Maximum mach number associated to aircraft. If no clipping is desired, this can be set tp np.inf.

Returns:

  • true_airspeed (npt.NDArray[np.floating]) – Array of true airspeed, [\(m \ s^{-1}\)]. All values are clipped at max_mach_number.

  • mach_num (npt.NDArray[np.floating]) – Array of Mach numbers, [\(Ma\)]. All values are clipped at max_mach_number.

pycontrails.physics.jet.combustor_inlet_pressure(pressure_ratio, p_comp_inlet, thrust_setting)

Calculate combustor inlet pressure, \(P_{3}\).

Parameters:

  • pressure_ratio (float) – Engine pressure ratio, unitless

  • p_comp_inlet (ArrayScalarLike) – Compressor inlet pressure, [\(Pa\)]

  • thrust_setting (ArrayScalarLike) – Engine thrust setting, unitless

Returns:

ArrayScalarLike – Combustor inlet pressure, [\(Pa\)]

References

pycontrails.physics.jet.combustor_inlet_temperature(comp_efficiency, T_comp_inlet, p_comp_inlet, p_comb_inlet)

Calculate combustor inlet temperature, \(T_{3}\).

Parameters:

  • comp_efficiency (float) – Engine compressor efficiency, [\(0 - 1\)]

  • T_comp_inlet (ArrayScalarLike) – Compressor inlet temperature, [\(K\)]

  • p_comp_inlet (ArrayScalarLike) – Compressor inlet pressure, [\(Pa\)]

  • p_comb_inlet (ArrayScalarLike) – Compressor inlet pressure, [\(Pa\)]

Returns:

ArrayScalarLike – Combustor inlet temperature, [\(K\)]

References

pycontrails.physics.jet.compressor_inlet_pressure(p, mach_num)

Calculate compressor inlet pressure for Jet engine, \(P_{2}\).

Parameters:
Returns:

ArrayScalarLike – Compressor inlet pressure, [\(Pa\)]

References

pycontrails.physics.jet.compressor_inlet_temperature(T, mach_num)

Calculate compressor inlet temperature for Jet engine, \(T_{2}\).

Parameters:
Returns:

ArrayScalarLike – Compressor inlet temperature, [\(K\)]

References

pycontrails.physics.jet.dedicated_freighter_payload(max_payload, cargo_lf)

Estimate payload for passenger aircraft.

Parameters:

  • max_payload (float) – Aircraft maximum payload, [\(kg\)]

  • cargo_lf (float) – Cargo load factor for dedicated freighters (between 0 and 1). Refer to cargo_load_factor() for origin-destination specific reference values.

Returns:

float – Estimated cargo aircraft payload, [\(kg\)]

References

  • cite:

    Teoh et al. (2026), in preparation

pycontrails.physics.jet.density_ratio(rho)

Calculate the ratio of air density relative to the air density at mean-sea-level.

Parameters:

rho (npt.NDArray[np.floating]) – Air density, [\(kg \ m^{3}\)]

Returns:

npt.NDArray[np.floating] – Ratio of the density to the air density at mean sea-level (MSL).

pycontrails.physics.jet.equivalent_fuel_flow_rate_at_cruise(fuel_flow_sls, theta_amb, delta_amb, mach_num)

Convert fuel mass flow rate at sea level to equivalent fuel flow rate at cruise conditions.

Refer to Eq. (40) in [DuBois and Paynter, 2006].

Parameters:

  • fuel_flow_sls (npt.NDArray[np.floating] | float) – Fuel mass flow rate, [\(kg s^{-1}\)]

  • theta_amb (ArrayOrFloat) – Ratio of the ambient temperature to the temperature at mean sea-level.

  • delta_amb (ArrayOrFloat) – Ratio of the pressure altitude to the surface pressure.

  • mach_num (ArrayOrFloat) – Mach number

Returns:

npt.NDArray[np.floating] – Estimate of fuel mass flow rate at sea level, [\(kg \ s^{-1}\)]

References

pycontrails.physics.jet.equivalent_fuel_flow_rate_at_sea_level(fuel_flow_cruise, theta_amb, delta_amb, mach_num)

Convert fuel mass flow rate at cruise conditions to equivalent flow rate at sea level.

Refer to Eq. (40) in [DuBois and Paynter, 2006].

Parameters:

  • fuel_flow_cruise (npt.NDArray[np.floating]) – Fuel mass flow rate per engine, [\(kg s^{-1}\)]

  • theta_amb (npt.NDArray[np.floating]) – Ratio of the ambient temperature to the temperature at mean sea-level.

  • delta_amb (npt.NDArray[np.floating]) – Ratio of the pressure altitude to the surface pressure.

  • mach_num (npt.NDArray[np.floating]) – Mach number, [:math: Ma]

Returns:

npt.NDArray[np.floating] – Estimate of fuel flow per engine at sea level, [\(kg \ s^{-1}\)].

References

pycontrails.physics.jet.fuel_burn(fuel_flow, segment_duration)

Calculate the fuel consumption at each waypoint.

Parameters:

  • fuel_flow (npt.NDArray[np.floating]) – Fuel mass flow rate, [\(kg s^{-1}\)]

  • segment_duration (npt.NDArray[np.floating]) – Time difference between waypoints, [\(s\)]

Returns:

npt.NDArray[np.floating] – Fuel consumption at each waypoint, [\(kg\)]

pycontrails.physics.jet.initial_aircraft_mass(*, amass_oew, amass_mtow, payload, total_fuel_burn, total_reserve_fuel, oew_uplift=1.03)

Estimate initial aircraft mass as a function of load factor and fuel requirements.

This function uses the following equation:

TOM = (OEM * OEM_uplift) + PM + FM_res + TFM
TOM = min(TOM, MTOW)

where: - TOM is the aircraft take-off mass - OEM is the aircraft operating empty weight - OEM_uplift is a multiple applied to the operating empty weight to account for biases - PM is the payload mass - FM_res is the mass of the reserve fuel - TFM is the trip fuel mass - MTOW is the aircraft maximum take-off weight

Parameters:

  • amass_oew (float) – Aircraft operating empty weight, i.e. the basic weight of an aircraft including the crew and necessary equipment, but excluding usable fuel and payload, [\(kg\)]

  • amass_mtow (float) – Aircraft maximum take-off weight, [\(kg\)]

  • payload (float) – Aircraft payload, [\(kg\)]

  • total_fuel_burn (float) – Total fuel consumption for the flight, obtained from prior iterations, [\(kg\)]

  • total_reserve_fuel (float) – Total reserve fuel requirements, [\(kg\)]

  • oew_uplift (float) – Multiple to increase operational empty weight. Defaults to 1.03, following Cirium (2025).

Returns:

float – Aircraft mass at the initial waypoint, [\(kg\)]

References

  • [Wasiuk et al., 2015]

  • Cirium EmeraldSky Emissions Methodology 2025: Detailed Description v1.8, p. 9.

https://assets.fta.cirium.com/wp-content/uploads/2025/11/11122423/Cirium-EmeraldSky-Emissions-Methodology-2025-Detailed-Description-v1.8.pdf

See also

reserve_fuel_requirements()

pycontrails.physics.jet.number_of_seats(aircraft_type=None)

Estimate number of seats for the provided aircraft type.

Parameters:

aircraft_type (str) – ICAO aircraft type designator

Returns:

int – Reference values for the number of seats

pycontrails.physics.jet.overall_propulsion_efficiency(true_airspeed, F_thrust, fuel_flow, q_fuel, is_descent, threshold=0.5)

Calculate the overall propulsion efficiency (OPE).

Negative OPE values can occur during the descent phase and is clipped to a lower bound of 0, while an upper bound of threshold is also applied. The most efficient engines today do not exceed this value.

Parameters:

  • true_airspeed (npt.NDArray[np.floating]) – True airspeed for each waypoint, [\(m s^{-1}\)].

  • F_thrust (npt.NDArray[np.floating]) – Thrust force provided by the engine, [\(N\)].

  • fuel_flow (npt.NDArray[np.floating]) – Fuel mass flow rate, [\(kg s^{-1}\)].

  • q_fuel (float) – Lower calorific value (LCV) of fuel, [\(J \ kg_{fuel}^{-1}\)].

  • is_descent (npt.NDArray[np.floating] | None) – Boolean array that indicates if a waypoint is in a descent phase.

  • threshold (float) – Upper bound for realistic engine efficiency.

Returns:

npt.NDArray[np.floating] – Overall propulsion efficiency (OPE)

References

pycontrails.physics.jet.passenger_aircraft_payload(max_payload, n_seats, pax_lf, cargo_lf, *, pax_mass=100.0)

Estimate payload for passenger aircraft.

Parameters:

  • max_payload (float) – Aircraft maximum payload, [\(kg\)]

  • n_seats (int) – Total number of seats in passenger aircraft

  • pax_lf (float) – Passenger load factor (between 0 and 1). Refer to passenger_load_factor() for historical regional-specific values.

  • cargo_lf (float) – Cargo load factor in the passenger hold (between 0 and 1). Refer to cargo_load_factor() for origin-destination specific reference values.

  • pax_mass (float) – Assumed passenger plus baggage mass, [\(kg\)] Defaults to the ICAO-recommend value of 100 kg

Returns:

float – Estimated passenger aircraft payload, [\(kg\)]

References

pycontrails.physics.jet.passenger_load_factor(origin_airport_icao=None, first_waypoint_time=None)

Estimate passenger load factor based on historical data.

Accounts for regional and seasonal differences.

Parameters:

  • origin_airport_icao (str | None) – ICAO code of origin airport. If None is provided, then globally averaged values will be assumed at first_waypoint_time.

  • first_waypoint_time (pd.Timestamp | None) – First waypoint UTC time. If None is provided, then regionally or globally averaged values from the trailing twelve months will be used.

Returns:

float – Passenger load factor [0 - 1], unitless

pycontrails.physics.jet.pressure_ratio(p)

Calculate the ratio of ambient pressure relative to the surface pressure.

Parameters:

p (npt.NDArray[np.floating]) – Air pressure, [\(Pa\)]

Returns:

npt.NDArray[np.floating] – Ratio of the pressure altitude to the surface pressure.

pycontrails.physics.jet.reserve_fuel_requirements(rocd, altitude_ft, fuel_flow, fuel_burn)

Estimate reserve fuel requirements.

Parameters:

  • rocd (npt.NDArray[np.floating]) – Rate of climb and descent, [\(ft \ min^{-1}\)]

  • altitude_ft (npt.NDArray[np.floating]) – Altitude, [\(ft\)]

  • fuel_flow (npt.NDArray[np.floating]) – Fuel mass flow rate, [\(kg \ s^{-1}\)].

  • fuel_burn (npt.NDArray[np.floating]) – Fuel consumption for each waypoint, [\(kg\)]

Returns:

npt.NDArray[np.floating] – Reserve fuel requirements, [\(kg\)]

References

Notes

The real-world calculation of the reserve fuel requirements is highly complex (refer to Section 2.3.3 of [Wasiuk et al., 2015]). This implementation is simplified by taking the maximum between the following two conditions:

  1. Fuel required to fly +90 minutes at the main cruise altitude at the end of the cruise aircraft weight.

  2. Uplift the total fuel consumption for the flight by +15%

See also

pycontrails.Flight.segment_phase, fuel_burn

pycontrails.physics.jet.temperature_ratio(T)

Calculate the ratio of ambient temperature relative to the temperature at mean sea level.

Parameters:

T (npt.NDArray[np.floating]) – Air temperature, [\(K\)]

Returns:

npt.NDArray[np.floating] – Ratio of the temperature to the temperature at mean sea-level (MSL).

pycontrails.physics.jet.thrust_force(altitude, true_airspeed, segment_duration, aircraft_mass, F_drag)

Calculate the thrust force at each waypoint.

Parameters:

  • altitude (npt.NDArray[np.floating]) – Waypoint altitude, [\(m\)]

  • true_airspeed (npt.NDArray[np.floating]) – True airspeed, [\(m \ s^{-1}\)]

  • segment_duration (npt.NDArray[np.floating]) – Time difference between waypoints, [\(s\)]

  • aircraft_mass (npt.NDArray[np.floating]) – Aircraft mass, [\(kg\)]

  • F_drag (npt.NDArray[np.floating]) – Draft force, [\(N\)]

Returns:

npt.NDArray[np.floating] – Thrust force, [\(N\)]

References

Notes

The model balances the rate of forces acting on the aircraft with the rate in increase in energy.

This estimate of thrust force is used in the BADA Total-Energy Model (Eq. 3.2-1).

Negative thrust must be corrected.

pycontrails.physics.jet.thrust_setting_nd(true_airspeed, thrust_setting, T, p, pressure_ratio, q_fuel, *, comp_efficiency=0.9, cruise=False)

Calculate the non-dimensionalized thrust setting of a Jet engine.

Result is in terms of the ratio of turbine inlet to the compressor inlet temperature (t4_t2)

Parameters:

  • true_airspeed (ArrayScalarLike) – True airspeed, [\(m \ s^{-1}\)]

  • thrust_setting (ArrayScalarLike) – Engine thrust setting, unitless

  • T (ArrayScalarLike) – Ambient temperature, [\(K\)]

  • p (ArrayScalarLike) – Ambient pressure, [\(Pa\)]

  • pressure_ratio (float) – Engine pressure ratio, unitless

  • q_fuel (float) – Lower calorific value (LCV) of fuel, \([J \ kg_{fuel}^{-1}]\)

  • comp_efficiency (float, optional) – Engine compressor efficiency, [\(0 - 1\)]. Defaults to 0.9

  • cruise (bool, optional) – Defaults to False

Returns:

ArrayScalarLike – Ratio of turbine inlet to the compressor inlet temperature, unitless

References

pycontrails.physics.jet.turbine_inlet_temperature(afr, T_comb_inlet, q_fuel)

Calculate turbine inlet temperature, \(T_{4}\).

Parameters:

  • afr (ArrayScalarLike) – Air-to-fuel ratio, unitless

  • T_comb_inlet (ArrayScalarLike) – Combustor inlet temperature, [\(K\)]

  • q_fuel (float) – Lower calorific value (LCV) of fuel, \([J \ kg_{fuel}^{-1}]\)

Returns:

ArrayScalarLike – Tubrine inlet temperature, [\(K\)]

References

pycontrails.physics.jet.update_aircraft_mass(*, amass_oew, amass_mtow, payload, fuel_burn, total_reserve_fuel, takeoff_mass)

Update aircraft mass based on the simulated total fuel consumption.

Used internally for finding aircraft mass iteratively.

Parameters:

  • amass_oew (float) – Aircraft operating empty weight, i.e. the basic weight of an aircraft including the crew and necessary equipment, but excluding usable fuel and payload, [\(kg\)].

  • ref_mass (float) – Aircraft reference mass, [\(kg\)].

  • amass_mtow (float) – Aircraft maximum take-off weight, [\(kg\)].

  • payload (float) – Aircraft payload, [\(kg\)]

  • fuel_burn (npt.NDArray[np.floating]) – Fuel consumption for each waypoint, [\(kg\)]

  • total_reserve_fuel (float) – Total reserve fuel requirements, [\(kg\)]

  • takeoff_mass (float | None) – Initial aircraft mass, [\(kg\)]. If None, the initial mass is calculated using initial_aircraft_mass(). If supplied, all other parameters except fuel_burn are ignored.

Returns:

npt.NDArray[np.floating] – Updated aircraft mass, [\(kg\)]

See also

fuel_burn, reserve_fuel_requirements, initial_aircraft_mass, aircraft_load_factor