fastoad.model_base.flight_point module

Structure for managing flight point data.

class fastoad.model_base.flight_point.FlightPoint(time: float = 0.0, altitude: float = None, isa_offset: float = 0.0, ground_distance: float = 0.0, mass: float = None, consumed_fuel: float = 0.0, true_airspeed: float = None, equivalent_airspeed: float = None, calibrated_airspeed: float = None, mach: float = None, engine_setting: EngineSetting = None, CL: float = None, CD: float = None, lift: float = None, drag: float = None, thrust: float = None, thrust_rate: float = None, thrust_is_regulated: bool = None, sfc: float = None, slope_angle: float = None, acceleration: float = None, alpha: float = 0.0, slope_angle_derivative: float = None, name: str = None)

Bases: object

Dataclass for storing data for one flight point.

This class is meant for:

• pandas friendliness: data exchange with pandas DataFrames is simple

• extensibility: any user might add fields to the class using add_field()

Exchanges with pandas DataFrame

A pandas DataFrame can be generated from a list of FlightPoint instances:

>>> import pandas as pd
>>> from fastoad.model_base import FlightPoint

>>> fp1 = FlightPoint(mass=70000., altitude=0.)
>>> fp2 = FlightPoint(mass=60000., altitude=10000.)
>>> df = pd.DataFrame([fp1, fp2])

And FlightPoint instances can be created from DataFrame rows:

# Get one FlightPoint instance from a DataFrame row
>>> fp1bis = FlightPoint.create(df.iloc[0])

# Get a list of FlightPoint instances from the whole DataFrame
>>> flight_points = FlightPoint.create_list(df)

Extensibility

FlightPoint class is bundled with several fields that are commonly used in trajectory assessment, but one might need additional fields.

Python allows to add attributes to any instance at runtime, but for FlightPoint to run smoothly, especially when exchanging data with pandas, you have to work at class level. This can be done using add_field(), preferably outside any class or function:

# Adding a float field with None as default value
>>> FlightPoint.add_field(
...    "ion_drive_power",
...    unit="W",
...    is_cumulative=False, # Tells if quantity sums up during mission
...    )

# Adding a field and defining its type and default value
>>> FlightPoint.add_field("warp", annotation_type=int, default_value=9)

# Now these fields can be used at instantiation
>>> fp = FlightPoint(ion_drive_power=110.0, warp=12)

# Removing a field, even an original one
>>> FlightPoint.remove_field("sfc")

Time integration

For those additional user-defined fields, it is also possible to define their time derivative. If a time derivative is defined this way, the mission model will automatically perform the integration. This integration will be achieved by incrementing the field at each time step by the product of the time derivative and the length of the time step in seconds.

The order in which a field and its time derivative are defined is irrelevant. However, the existence of the field containing the time derivative will be verified when the analysis process is run:

# Adding a time-dependent field and declaring the field which contains its derivative
# using the 'integrates_from' field descriptor.
>>> FlightPoint.add_field(
...    "electric_energy",
...    unit="J",
...    default_value=0.0,
...    is_cumulative=True,
...    integrates_from="electric_power",
... )

# Now defining the field that contains the derivative. The unit of the derivative must
# be the unit of the original field *per second*
>>> FlightPoint.add_field(
...     "electric_power", default_value=0.0, unit="W", is_cumulative=False
... )

# Field will be incremented as: field[i+1] = field[i] + time_derivative[i] *
# time_step[i]

Note

All original parameters in FlightPoint instances are expected to be in SI units.

time: float = 0.0

Time in seconds.

altitude: float = None

Altitude in meters.

isa_offset: float = 0.0

temperature deviation from Standard Atmosphere

ground_distance: float = 0.0

Covered ground distance in meters.

mass: float = None

Mass in kg.

consumed_fuel: float = 0.0

Consumed fuel since mission start, in kg.

true_airspeed: float = None

True airspeed (TAS) in m/s.

equivalent_airspeed: float = None

Equivalent airspeed (EAS) in m/s.

calibrated_airspeed: float = None

Calibrated airspeed (CAS) in m/s.

mach: float = None

Mach number.

engine_setting: EngineSetting = None

Engine setting.

CL: float = None

Lift coefficient.

CD: float = None

Drag coefficient.

lift: float = None

Aircraft lift in Newtons

drag: float = None

Aircraft drag in Newtons.

thrust: float = None

Thrust in Newtons.

thrust_rate: float = None

Thrust rate (between 0. and 1.)

thrust_is_regulated: bool = None

If True, propulsion should match the thrust value. If False, propulsion should match thrust rate.

sfc: float = None

Specific Fuel Consumption in kg/N/s.

slope_angle: float = None

Slope angle in radians.

acceleration: float = None

Acceleration value in m/s**2.

alpha: float = 0.0

angle of attack in radians

slope_angle_derivative: float = None

slope angle derivative in rad/s

name: str = None

Name of current phase.

set_as_relative(field_names: Sequence[str] | str)

Makes that values for given field_names will be considered as relative when calling make_absolute().

Parameters:

field_names

set_as_absolute(field_names: Sequence[str] | str)

Makes that values for given field_names will be considered as absolute when calling make_absolute().

Parameters:

field_names

is_relative(field_name) → bool

Tells if given field is considered as relative or absolut

Parameters:

field_name

Returns:

True if it is relative

make_absolute(reference_point: FlightPoint) → FlightPoint

Computes a copy flight point where no field is relative.

Parameters:

reference_point – relative fields will be made absolute using this point.

Returns:

the copied flight point with no relative field.

scalarize()

Convenience method for converting to scalars all fields that have a one-item array-like value.

classmethod get_field_names()

Returns:

names of all fields of the flight point.

classmethod get_units() → dict

Returns (field name, unit) dict for any field that has a defined unit.

A dimensionless physical quantity will have “-” as unit.

classmethod get_unit(field_name) → str

Returns unit for asked field.

A dimensionless physical quantity will have “-” as unit.

classmethod is_cumulative(field_name) → bool | None

Tells if asked field is cumulative (sums up during mission).

Returns None if field not found.

classmethod create(data: Mapping) → FlightPoint

Instantiate FlightPoint from provided data.

data can typically be a dict or a pandas DataFrame row.

Parameters:

data – a dict-like instance where keys are FlightPoint attribute names

Returns:

the created FlightPoint instance

classmethod create_list(data: DataFrame) → list[FlightPoint]

Creates a list of FlightPoint instances from provided DataFrame.

Parameters:

data – a dict-like instance where keys are FlightPoint attribute names

Returns:

the created FlightPoint instance

classmethod add_field(name: str, annotation_type=<class 'float'>, default_value: Any = None, unit='-', *, is_cumulative=False, integrates_from: str | None = None)

Adds the named field to FlightPoint class.

If the field name already exists, the field is redefined.

Parameters:

• name – field name

• annotation_type – field type

• default_value – field default value

• unit – expected unit for the added field. “-” should be provided for a dimensionless physical quantity. Set to None, when unit concept does not apply.

• is_cumulative – True if field value is summed up during mission

• integrates_from – Name of the other field this value is integrated by (in other words, incremented by that value multiplied by the time step always in s)

classmethod remove_field(name)

Removes the named field from FlightPoint class.

Parameters:

name – field name

classmethod get_time_integrable_quantities() → dict[str, str | None]

Uses this method instead of accessing cls.__cumulative_quantity to ensure it will always be correctly populated.

classmethod get_time_integrand(field_name) → str

Returns the quantity the field integrates from.