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_load_factor([origin_airport_icao, ...])	Estimate passenger/cargo load factor based on historical data.
aircraft_weight(aircraft_mass)	Calculate the aircraft weight at each waypoint.
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}\).
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(*, ...)	Estimate initial aircraft mass as a function of load factor and fuel requirements.
overall_propulsion_efficiency(true_airspeed, ...)	Calculate the overall propulsion efficiency (OPE).
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(*, ...)	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

• [Cumpsty and Heyes, 2015]

• AFR equation from [Stettler et al., 2013]

• Scaling factor to cruise from Eq. (30) of [DuBois and Paynter, 2006]

pycontrails.physics.jet.aircraft_load_factor(origin_airport_icao=None, first_waypoint_time=None, *, freighter=False)

Estimate passenger/cargo 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.

• freighter (bool) – Historical cargo load factor will be used if true, otherwise use passenger load factor.

Returns:

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

pycontrails.physics.jet.aircraft_weight(aircraft_mass)

Calculate the aircraft weight at each waypoint.

Parameters:

aircraft_mass (ArrayOrFloat) – Aircraft mass, [\(kg\)]

Returns:

ArrayOrFloat – Aircraft weight, [\(N\)]

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

• [Stettler et al., 2013]

• [Cumpsty and Heyes, 2015]

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

• [Stettler et al., 2013]

• [Cumpsty and Heyes, 2015]

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

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

Parameters:

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

• mach_num (ArrayScalarLike) – Mach number

Returns:

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

References

• [Stettler et al., 2013]

• [Cumpsty and Heyes, 2015]

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

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

Parameters:

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

• mach_num (ArrayScalarLike) – Mach number

Returns:

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

References

• [Stettler et al., 2013]

• [Cumpsty and Heyes, 2015]

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

• [DuBois and Paynter, 2006]

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

• [DuBois and Paynter, 2006]

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(*, operating_empty_weight, max_takeoff_weight, max_payload, total_fuel_burn, total_reserve_fuel, load_factor)

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

This function uses the following equation:

TOM = OEM + PM + FM_nc + TFM
    = OEM + LF * MPM + FM_nc + TFM

where: - TOM is the aircraft take-off mass - OEM is the aircraft operating empty weight - PM is the payload mass - FM_nc is the mass of the fuel not consumed - TFM is the trip fuel mass - LF is the load factor - MPM is the maximum payload mass

Parameters:

• operating_empty_weight (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\)]

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

• max_payload (float) – Aircraft maximum 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\)]

• load_factor (float) – Aircraft load factor assumption (between 0 and 1)

Returns:

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

References

• [Wasiuk et al., 2015]

See also

reserve_fuel_requirements, aircraft_load_factor

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

• [Schumann, 1996]

• [Cumpsty and Heyes, 2015]

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

• [Wasiuk et al., 2015]

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

• [Eurocontrol, 2010]

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

• [Cumpsty and Heyes, 2015]

• [Teoh et al., 2022]

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

• [Cumpsty and Heyes, 2015]

pycontrails.physics.jet.update_aircraft_mass(*, operating_empty_weight, max_takeoff_weight, max_payload, fuel_burn, total_reserve_fuel, load_factor, takeoff_mass)

Update aircraft mass based on the simulated total fuel consumption.

Used internally for finding aircraft mass iteratively.

Parameters:

• operating_empty_weight (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\)].

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

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

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

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

• load_factor (float) – Aircraft load factor assumption (between 0 and 1). This is the ratio of the actual payload weight to the maximum payload weight.

• 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