Boeing 747 — Longitudinal Dynamics¶

The Boeing 747 is a double-deck wide-body passenger aircraft. The library provides its longitudinal flight channel as a linear state-space model together with a Gymnasium environment for training control agents.

Quick start

Launch the environment or the model within minutes.

See example
Model API

Python class documentation for the B747 longitudinal dynamics.

Go to API
Gymnasium environment

Ready environment for RL agents.

Explore
Theory

State equations and numerical parameters.

Learn more

Performance specs (reference)¶

Parameter	Value
Length, m	70.7
Wingspan, m	64.4
Aircraft height, m	19.4
Wing area, m²	541.2
Normal takeoff weight, kg	11467

Control object structure¶

The model is defined in the state space and describes the evolution of longitudinal motion variables when controlled by the elevator.

\[\dot{x} = A x + B u, \quad y = C x + D u\]

where the state vector and control input are:

\[ x = \begin{bmatrix} u & w & q & \theta \end{bmatrix}^{\top}, \quad u_{in} = \eta \]

The typical matrix structure is:

\[ \begin{bmatrix} \dot{u} \\ \dot{w} \\ \dot{q} \\ \dot{\theta} \end{bmatrix} = \begin{bmatrix} +x_u & x_w & x_q & x_{\theta} \\ +z_u & z_w & z_q & z_{\theta} \\ +m_u & m_w & m_q & m_{\theta} \\ +0 & 0 & 1 & 0 \end{bmatrix} \begin{bmatrix} u \\ w \\ q \\ \theta \end{bmatrix} + \begin{bmatrix} x_{\eta} \\ z_{\eta} \\ m_{\eta} \\ 0 \end{bmatrix} \eta \]

VariablesCoefficients

u: longitudinal speed, m/s
w: normal (vertical) speed, m/s
q: pitch rate, rad/s
θ: pitch angle, rad
η: elevator (stabilator) deflection, rad

x_u, x_w, x_q, x_θ — partial derivatives of longitudinal force \(X\) with respect to \(u, w, q, \theta\)
z_u, z_w, z_q, z_θ — partial derivatives of normal force \(Z\) with respect to \(u, w, q, \theta\)
m_u, m_w, m_q, m_θ — partial derivatives of pitch moment \(M\) with respect to \(u, w, q, \theta\)
x_η, z_η, m_η — partial derivatives with respect to the control input \(\eta\) (stabilator deflection)

Units

Inside the models, angles and angular rates are in radians. API methods allow retrieving data in degrees.

Mathematical model¶

\[ \dot{x} = A x + B u, \qquad y = C x + D u \]

Because the plant has no internal disturbances, the output \(y\) is not used (\(C\) is diagonal, \(D\) is zero).

Numerical matrices (example linearization):

\[ \begin{bmatrix} \dot{u} \\ \dot{w} \\ \dot{q} \\ \dot{\theta} \end{bmatrix} = \begin{bmatrix} -0.0069 & -0.0139 & 0 & -9.81 \\ -0.0905 & -0.6975 & 235.8928 & 0 \\ 0.0004 & -0.0034 & 0 & 0.0911 \\ 0 & 0 & 1 & 0 \end{bmatrix} \begin{bmatrix} u \\ w \\ q \\ \theta \end{bmatrix} + \begin{bmatrix} -0.0001 \\ -5.5079 \\ -1.1569 \\ 0 \end{bmatrix} \eta \]

Actuator limits

The default control limits are:

Maximum magnitude: \(\pm 25^\circ\)
Maximum rate: \(60^\circ/\text{s}\)

Internal computations use radians; the limits are converted accordingly.

Sources¶

Heffley R. K., Jewell W. F. Aircraft handling qualities data. – NASA, 1972. – No. AD‑A277031. Link
Abd Elwahab S. et al. Evaluation of Boeing 747‑E lateral autopilot using flying and handling qualities specifications // ICCCCEE 2017. IEEE. Link

Quick start¶

GymnasiumModel only

import gymnasium as gym
import numpy as np

from tensoraerospace.envs import LinearLongitudinalB747
from tensoraerospace.utils import generate_time_period
from tensoraerospace.signals.standard import unit_step

dt = 0.01
tp = generate_time_period(tn=20, dt=dt)
number_time_steps = len(tp)
reference_signals = unit_step(degree=5, tp=tp, time_step=10, output_rad=True).reshape(1, -1)

env = gym.make(
    'LinearLongitudinalB747-v0',
    number_time_steps=number_time_steps,
    initial_state=[[0],[0],[0],[0]],  # u, w, q, theta (will be mapped)
    reference_signal=reference_signals,
)

state, info = env.reset()
for _ in range(200):
    action = np.array([[0.1]])
    state, reward, terminated, truncated, info = env.step(action)
    if terminated or truncated:
        break

import numpy as np
from tensoraerospace.aerospacemodel import LongitudinalB747

dt = 0.01
number_time_steps = 200

x0 = np.array([0.0, 0.0, 0.0, 0.0])  # [u, w, q, theta]

model = LongitudinalB747(
    x0=x0,
    number_time_steps=number_time_steps,
    selected_state_output=["u", "w", "q", "theta"],
    dt=dt,
)

for t in range(number_time_steps - 1):
    u = np.array([[0.05]])  # stabilator deflection (rad)
    x_next = model.run_step(u)

Python API¶

ModelGymnasium environment

`LongitudinalB747(x0, number_time_steps, selected_state_output=None, t0=0, dt=0.01)` ¶

Bases: ModelBase

Boeing 747 in longitudinal control channel.

Parameters:

Name	Type	Description	Default
`x0`	`ndarray`	Initial state of the control object.	required
`number_time_steps`	`int`	Number of time steps.	required
`selected_state_output`	`optional`	Selected states of the control object. Defaults to None.	`None`
`t0`	`int`	Initial time. Defaults to 0.	`0`
`dt`	`float`	Discretization frequency. Defaults to 0.01.	`0.01`

Action space

ele: elevator [deg]

State space

u: Longitudinal aircraft velocity [m/s] w: Normal aircraft velocity [m/s] q: Pitch angular velocity [deg/s] theta: Pitch [deg]

Output space

u: Longitudinal aircraft velocity [m/s] w: Normal aircraft velocity [m/s] q: Pitch angular velocity [deg/s] theta: Pitch [deg]

`import_linear_system()` ¶

Load (set) stored linearized system matrices.

Sets A, B, C, D matrices for the Boeing 747 longitudinal linear model.

`initialise_system(x0, number_time_steps)` ¶

Initialize the system and allocate history buffers.

Parameters:

Name	Type	Description	Default
`x0`	`ndarray`	Initial state.	required
`number_time_steps`	`int`	Number of simulation steps.	required

`run_step(ut_0)` ¶

Run one discrete-time simulation step.

Parameters:

Name	Type	Description	Default
`ut_0`	`ndarray`	Control vector.	required

Returns:

Type	Description
`ndarray`	np.ndarray: Next state at time t+1.

`update_system_attributes()` ¶

Update internal state and step counter after each simulation step.

`get_state(state_name, to_deg=False, to_rad=False)` ¶

Return the time history of a state.

Parameters:

Name	Type	Description	Default
`state_name`	`str`	State name.	required
`to_deg`	`bool`	Convert radians to degrees.	`False`
`to_rad`	`bool`	Convert degrees to radians.	`False`

Returns:

Type	Description
`ndarray`	np.ndarray: State history array.

`get_control(control_name, to_deg=False, to_rad=False)` ¶

Return the time history of a control input.

Parameters:

Name	Type	Description	Default
`control_name`	`str`	Control signal name.	required
`to_deg`	`bool`	Convert radians to degrees.	`False`
`to_rad`	`bool`	Convert degrees to radians.	`False`

Returns:

Type	Description
`ndarray`	np.ndarray: Control history array.

`get_output(state_name, to_deg=False, to_rad=False)` ¶

Return output time history for the specified output name.

Parameters:

Name	Type	Description	Default
`state_name`	`str`	Output name.	required
`to_deg`	`bool`	Convert radians to degrees.	`False`
`to_rad`	`bool`	Convert degrees to radians.	`False`

Returns:

Type	Description
`ndarray`	np.ndarray: Output history array.

`plot_output(output_name, time, lang='rus', to_deg=False, to_rad=False, figsize=(10, 10))` ¶

Plot an output signal over time.

Parameters:

Name	Type	Description	Default
`output_name`	`str`	Output name.	required
`time`	`ndarray`	Time vector.	required
`lang`	`str`	Axis label language ('rus' or 'eng').	`'rus'`
`to_deg`	`bool`	Convert radians to degrees.	`False`
`to_rad`	`bool`	Convert degrees to radians.	`False`
`figsize`	`tuple`	Figure size.	`(10, 10)`

Returns:

Type	Description
`Figure`	matplotlib.figure.Figure: Figure object.

Raises:

Type	Description
`Exception`	If invalid formatting is requested or the signal is not found.

`LinearLongitudinalB747(initial_state, reference_signal, number_time_steps, tracking_states=None, state_space=None, control_space=None, output_space=None, reward_func=None, use_reward=True, dt=0.01, render_mode=None)` ¶

Bases: Env

Simulation of LongitudinalB747 control object in Gym for training.

Parameters:

Name	Type	Description	Default
`initial_state`	`ndarray`	Initial state.	required
`reference_signal`	`ndarray`	Reference signal.	required
`number_time_steps`	`int`	Number of simulation steps.	required
`tracking_states`	`list[str] \| None`	Tracked states.	`None`
`state_space`	`list[str] \| None`	State space.	`None`
`control_space`	`list[str] \| None`	Control space.	`None`
`output_space`	`list[str] \| None`	Full output space (including noise).	`None`
`reward_func`	`Callable \| None`	Reward function (WIP status).	`None`
`use_reward`	`bool`	Whether to use reward.	`True`
`dt`	`float`	Discretization frequency.	`0.01`

Notes

Action units expected by the environment are degrees (deg).
Actions are converted to radians (rad) before being passed to the underlying model.

Initialize LinearLongitudinalB747 environment.

Parameters:

Name	Type	Description	Default
`initial_state`	`ndarray`	Initial state.	required
`reference_signal`	`ndarray`	Reference signal.	required
`number_time_steps`	`int`	Number of simulation steps.	required
`tracking_states`	`list[str] \| None`	Tracked states. Defaults to ["theta", "q"].	`None`
`state_space`	`list[str] \| None`	State space. Defaults to ["theta", "q"].	`None`
`control_space`	`list[str] \| None`	Control space. Defaults to ["stab"].	`None`
`output_space`	`list[str] \| None`	Full output space. Defaults to ["theta", "q"].	`None`
`reward_func`	`Callable \| None`	Reward function. Defaults to None.	`None`
`use_reward`	`bool`	Whether to use reward. Defaults to True.	`True`
`dt`	`float`	Discretization frequency. Defaults to 0.01.	`0.01`
`render_mode`	`str \| None`	`None`, `"human"` or `"ansi"`.	`None`

`reward(state, ref_signal, ts, action=None)` `staticmethod` ¶

Control evaluation.

Parameters:

Name	Type	Description	Default
`state`	`ndarray`	Current state.	required
`ref_signal`	`ndarray`	Reference state.	required
`ts`	`int`	Time step.	required

Returns:

Name	Type	Description
`float`	`float`	Control evaluation (negative MSE).

`step(action)` ¶

Execute simulation step.

Parameters:

Name	Type	Description	Default
`action`	`ndarray`	Control signal array for selected actuators in degrees.	required

Returns:

Name	Type	Description
`next_state`	`ndarray`	Next state of control object.
`reward`	`ndarray`	Evaluation of control algorithm actions.
`done`	`bool`	Simulation status, completed or not.
`logging`	`any`	Additional information (not used).

`reset(seed=None, options=None)` ¶

Reset simulation environment to initial conditions.

Parameters:

Name	Type	Description	Default
`seed`	`int`	Seed for random number generator.	`None`
`options`	`dict`	Additional initialization options.	`None`

Returns:

Name	Type	Description
`tuple`	`Tuple[ndarray, Dict[str, Any]]`	Observation array and info dictionary.

`render(mode=None)` ¶

Render a lightweight telemetry snapshot.

The legacy B747 environment does not have a graphical viewer. To keep render_mode="human" usable, human mode prints one concise state line; ansi returns the same line as a string for tests and logs.

Boeing 747 — Longitudinal Dynamics¶

Performance specs (reference)¶

Control object structure¶

Mathematical model¶

Sources¶

Quick start¶

Python API¶

LongitudinalB747(x0, number_time_steps, selected_state_output=None, t0=0, dt=0.01) ¶

import_linear_system() ¶

initialise_system(x0, number_time_steps) ¶

run_step(ut_0) ¶

update_system_attributes() ¶

get_state(state_name, to_deg=False, to_rad=False) ¶

get_control(control_name, to_deg=False, to_rad=False) ¶

get_output(state_name, to_deg=False, to_rad=False) ¶

plot_output(output_name, time, lang='rus', to_deg=False, to_rad=False, figsize=(10, 10)) ¶

LinearLongitudinalB747(initial_state, reference_signal, number_time_steps, tracking_states=None, state_space=None, control_space=None, output_space=None, reward_func=None, use_reward=True, dt=0.01, render_mode=None) ¶

reward(state, ref_signal, ts, action=None) staticmethod ¶

step(action) ¶

reset(seed=None, options=None) ¶

render(mode=None) ¶

`LongitudinalB747(x0, number_time_steps, selected_state_output=None, t0=0, dt=0.01)` ¶

`import_linear_system()` ¶

`initialise_system(x0, number_time_steps)` ¶

`run_step(ut_0)` ¶

`update_system_attributes()` ¶

`get_state(state_name, to_deg=False, to_rad=False)` ¶

`get_control(control_name, to_deg=False, to_rad=False)` ¶

`get_output(state_name, to_deg=False, to_rad=False)` ¶

`plot_output(output_name, time, lang='rus', to_deg=False, to_rad=False, figsize=(10, 10))` ¶

`LinearLongitudinalB747(initial_state, reference_signal, number_time_steps, tracking_states=None, state_space=None, control_space=None, output_space=None, reward_func=None, use_reward=True, dt=0.01, render_mode=None)` ¶

`reward(state, ref_signal, ts, action=None)` `staticmethod` ¶

`step(action)` ¶

`reset(seed=None, options=None)` ¶

`render(mode=None)` ¶