pterasoftware.problems

Contains the SteadyProblem, UnsteadyProblem, AeroelasticUnsteadyProblem, and FreeFlightUnsteadyProblem classes.

Classes

SteadyProblem	A class used to contain steady aerodynamics problems.
UnsteadyProblem	A class used to contain unsteady aerodynamics problems.
FreeFlightUnsteadyProblem	A class used to contain problems with coupled unsteady aerodynamics and rigid body dynamics.
AeroelasticUnsteadyProblem	A subclass of _CoupledUnsteadyProblem used to couple aeroelastic wing deformations with unsteady aerodynamics.

Module Contents

class pterasoftware.problems.SteadyProblem(

airplanes: list[pterasoftware.geometry.airplane.Airplane],

operating_point: pterasoftware.operating_point.OperatingPoint,

)

A class used to contain steady aerodynamics problems.

Contains the following methods:

reynolds_numbers: A tuple of Reynolds numbers, one for each Airplane in the SteadyProblem.

Parameters:

• airplanes – The list of the Airplanes for this SteadyProblem.

• operating_point – The OperatingPoint for this SteadyProblem.

Returns:

None

property reynolds_numbers: tuple[float, Ellipsis]

A tuple of Reynolds numbers, one for each Airplane in the SteadyProblem.

Notes:

The Reynolds number is calculated as: Re = (V x L) / nu, where V is the freestream speed, observed from the Earth frame (vCg__E from OperatingPoint, m/s), L is the characteristic length (c_ref from Airplane, m), and nu is the kinematic viscosity (nu from OperatingPoint, m^2/s).

These Reynolds numbers only consider the freestream speed, not any apparent velocity due to prescribed motion, so be careful interpreting it for cases where this SteadyProblem corresponds to one time step in an UnsteadyProblem.

Returns:

A tuple of Reynolds numbers, one for each Airplane.

class pterasoftware.problems.UnsteadyProblem(

movement: pterasoftware.movements.movement.Movement,

only_final_results: bool | numpy.bool_ = False,

)

A class used to contain unsteady aerodynamics problems.

Contains the following methods:

only_final_results: Determines whether the solver will only calculate loads for the final time step or final cycle.

num_steps: The number of time steps.

delta_time: The time step size in seconds.

first_averaging_step: The first time step included in cycle averaging.

first_results_step: The first time step for which loads are calculated.

max_wake_rows: The maximum chordwise wake rows per Wing.

movement: The Movement that contains this UnsteadyProblem’s OperatingPointMovement and AirplaneMovements.

steady_problems: A tuple of SteadyProblems, one for each time step.

Parameters:

• movement – The Movement that contains this UnsteadyProblem’s OperatingPointMovement and AirplaneMovements.

• only_final_results – Determines whether the Solver will only calculate loads for the final time step (for static Movements) or (for non static Movements) for will only calculate loads for the time steps in the final complete motion cycle (of the Movement’s sub Movement with the longest period), which increases simulation speed. Can be a bool or a numpy bool and will be converted internally to a bool. The default is False.

Returns:

None

class pterasoftware.problems.FreeFlightUnsteadyProblem(

movement: pterasoftware.movements.free_flight_movement.FreeFlightMovement,

mass: float | int,

I_BP1_CgP1: numpy.ndarray | collections.abc.Sequence[collections.abc.Sequence[float | int]],

external_loads_fn: collections.abc.Callable[[pterasoftware.operating_point.OperatingPoint, pterasoftware.geometry.airplane.Airplane], tuple[numpy.ndarray, numpy.ndarray]] | None = None,

k_max: int = 20,

integrator: str = 'RK4',

extra_xml: dict[str, str] | None = None,

mujoco_assets: dict[str, bytes] | None = None,

)

Bases: _CoupledUnsteadyProblem

A class used to contain problems with coupled unsteady aerodynamics and rigid body dynamics.

Contains the following methods:

only_final_results: Determines whether the solver will only calculate loads for the final time step or final cycle.

num_steps: The number of time steps.

delta_time: The time step size in seconds.

first_averaging_step: The first time step included in cycle averaging.

first_results_step: The first time step for which loads are calculated.

max_wake_rows: The maximum chordwise wake rows per Wing.

movement: The FreeFlightMovement that defines the motion parameters for this FreeFlightUnsteadyProblem.

steady_problems: A tuple of SteadyProblems, one for each time step that has been initialized so far.

get_steady_problem: Gets the SteadyProblem at a specified time step.

initialize_next_problem: Initializes the next time step’s SteadyProblem from rigid body dynamics.

mass: The mass of the Airplane in kilograms.

I_BP1_CgP1: The inertia matrix of the Airplane (in the first Airplane’s body axes, relative to the first Airplane’s CG) in kilogram square meters.

k_max: The maximum number of strongly coupled sub-iterations per free-flight time step.

external_loads_fn: A callable that computes additional forces and moments to apply to the Airplane during the simulation, or None.

Parameters:

• movement – The FreeFlightMovement that defines the prescribed Airplane geometry for this FreeFlightUnsteadyProblem. The initial Airplane and OperatingPoint are derived from the FreeFlightMovement at the first time step. The FreeFlightMovement must contain exactly one AirplaneMovement; multi-airplane free flight is not supported in this release.

• mass – A number (int or float) representing the mass of the Airplane. It must be greater than zero and will be converted internally to a float. The units are in kilograms. It must satisfy weight == mass * |g_E| within floating point tolerance, where weight is the Airplane’s weight and g_E is the OperatingPoint’s gravitational acceleration, which keeps the Airplane’s weight, the supplied mass, and the gravitational field mutually consistent.

• I_BP1_CgP1 – An array-like object of numbers (int or float) with shape (3,3) representing the inertia matrix of the Airplane (in the first Airplane’s body axes, relative to the first Airplane’s CG). It must be symmetric. Can be a tuple, list, or ndarray. Values are converted to floats internally. The units are in kilogram square meters.

• external_loads_fn – A callable that computes additional forces and moments to apply to the Airplane during the simulation. It takes an OperatingPoint and an Airplane and returns a tuple of two (3,) ndarrays of floats: the additional force (in wind axes, in Newtons) and the additional moment (in wind axes, relative to the first Airplane’s CG, in Newton meters). The return value is validated on the callable’s first invocation; a return that is not a pair of (3,) finite numeric vectors raises a descriptive error. The physical correctness of the forces and moments themselves is not checked. Setting this to None applies no additional loads. The default is None. This is the only mechanism for non-aerodynamic loads in free flight: the OperatingPoint’s externalFX_W is never applied and must be zero.

• k_max – An int giving the maximum number of strongly coupled sub- iterations per free-flight time step. Each time step drives the aerodynamic loads and the rigid body state to mutual consistency with an Aitken-relaxed fixed-point sub-iteration; this caps the iterations spent before the step is accepted. A step that reaches the cap without converging is accepted anyway, with a warning. It must be greater than zero and will be converted internally to an int. Raising it trades more work per step for a tighter solve when convergence is slow, which can happen for a very light vehicle (a large added-mass ratio). The default is 20.

• integrator – A str naming the MuJoCo integrator used to advance the rigid body dynamics. It must be one of “Euler”, “RK4”, “implicit”, or “implicitfast”. The choice is baked into the generated MuJoCo model XML, so it survives saving and loading. “RK4” is accurate for smooth dynamics but handles contacts poorly, so runs with collision geometry (injected via extra_xml) should prefer “implicit” or “implicitfast”. The default is “RK4”.

• extra_xml – A dict mapping injection point names to XML fragment strings to inject into the MuJoCo model’s XML. Supported keys are “default”, “asset”, “visual”, “worldbody”, and “body”. Setting this to None injects no extra XML. The default is None. The argument is checked to be a dict (or None) whose keys are supported injection points and whose values are strings; the XML fragments themselves are not validated, which is left to MuJoCo, so this is an advanced-user parameter.

• mujoco_assets – A dict mapping virtual filenames to their binary contents for the MuJoCo model. Setting this to None provides no extra assets. The default is None. The argument is checked to be a dict (or None) mapping string filenames to bytes; whether a referenced asset is actually supplied is left to MuJoCo, so this is an advanced-user parameter. A FreeFlightUnsteadyProblem built with mujoco_assets cannot be saved: save() raises, because the saved engine is rebuilt on load from the stored XML alone, whose asset references would be unresolvable.

Returns:

None

initialize_next_problem(

solver: pterasoftware._coupled_unsteady_ring_vortex_lattice_method.CoupledUnsteadyRingVortexLatticeMethodSolver,

step: int,

) → None

Initializes the next time step’s SteadyProblem from rigid body dynamics.

On every step except the last one, advances the MuJoCo dynamics and creates the next SteadyProblem with the new OperatingPoint and the prescribed Airplane geometry for the next step. During the prescribed phase, the loads are withheld so the body coasts at its initial trimmed condition while the wake develops, and the body advances once. During the free flight phase (once the step index reaches the movement’s prescribed_num_steps), the aerodynamic loads and the rigid body state are driven to mutual consistency by the strongly coupled sub- iteration before the next step is committed.

Parameters:

• solver – The CoupledUnsteadyRingVortexLatticeMethodSolver instance providing aerodynamic data from the current time step.

• step – The current time step index (zero indexed).

Returns:

None

get_steady_problem(

step: int,

) → SteadyProblem

Get the SteadyProblem at a given time step.

Parameters:

step – The time step index (zero indexed). Must be greater than or equal to zero and less than the total number of time steps.

Returns:

The SteadyProblem at the specified time step.

class pterasoftware.problems.AeroelasticUnsteadyProblem(

movement: pterasoftware.movements.aeroelastic_movement.AeroelasticMovement,

wing_density: float,

spring_constant_rad: float,

damping_constant_rad: float,

step_discards: int = 5,

)

Bases: _CoupledUnsteadyProblem

A subclass of _CoupledUnsteadyProblem used to couple aeroelastic wing deformations with unsteady aerodynamics.

This class couples aerodynamic loads with wing structural dynamics (spring-mass- damper system) to simulate aeroelastic deformation. Each time step, wing deformations are calculated based on the combined effects of each strip’s aerodynamic, inertial, and spring-damper restoring torsional moments, all taken as y components (in the first Airplane’s geometry axes) of moments relative to the strip’s leading edge point.

Contains the following methods:

only_final_results: Determines whether the solver will only calculate loads for the final time step or final cycle.

num_steps: The number of time steps.

delta_time: The time step size in seconds.

first_averaging_step: The first time step included in cycle averaging.

first_results_step: The first time step for which loads are calculated.

max_wake_rows: The maximum chordwise wake rows per Wing.

movement: The AeroelasticMovement that defines the motion parameters for this AeroelasticUnsteadyProblem.

steady_problems: A tuple of SteadyProblems, one for each time step that has been initialized so far.

get_steady_problem: Gets the SteadyProblem at a specified time step.

initialize_next_problem: Initializes the next time step’s SteadyProblem from the deformed geometry.

wing_density: The mass per unit span area of the wing (kg/m^2).

spring_constant_rad: The torsional spring stiffness for the spring-mass-damper model (N*m/rad).

damping_constant_rad: The torsional damping coefficient (N*m*s/rad).

step_discards: The number of initial time steps to discard for numerical stability.

Notes:

The aeroelastic coupling assumes a torsional spring-mass-damper model for each spanwise section. Wing motion is prescribed through wing flapping, and each strip’s aerodynamic moment y components (in the first Airplane’s geometry axes, relative to the strip’s leading edge point) are combined with its inertial and spring restoring moments about the same axis and point via ODE integration to produce structural deformations.

Sets up the aeroelastic problem with structural parameters for the torsional spring-mass-damper model applied to each wing spanwise section. Initializes the per-wing structural state time series.

See _CoupledUnsteadyProblem’s initialization method for descriptions of inherited parameters.

Parameters:

• movement – An AeroelasticMovement containing the prescribed motion and aerodynamic setup for the aeroelastic simulation.

• wing_density – The mass per unit span area of the wing (kg/m^2). Used to distribute wing mass across Panels for inertial calculations.

• spring_constant_rad – The torsional spring stiffness for the spring-mass- damper model (N*m/rad). Controls the restoring moment opposing deformation.

• damping_constant_rad – The torsional damping coefficient (N*m*s/rad). Controls the viscous damping in the spring-mass-damper system.

• step_discards – The number of initial time steps to discard for numerical stability (there are inconsistent startup effects from the UVLM solver). During these time steps, the solver will run but the results will not be applied to the deformation of the Wings. The default is 5.

Returns:

None

initialize_next_problem(

solver: pterasoftware._coupled_unsteady_ring_vortex_lattice_method.CoupledUnsteadyRingVortexLatticeMethodSolver,

step: int,

) → None

Initialize the next time step’s SteadyProblem and perform per step work.

Subclasses must override this method. It is invoked by the solver on every step, so subclasses are responsible for guarding any work that depends on a next step existing (such as building the next SteadyProblem) with step < self.num_steps - 1. Per step work that should run on every step (such as recording the current step’s loads) belongs outside that guard.

Parameters:

• solver – The CoupledUnsteadyRingVortexLatticeMethodSolver instance providing aerodynamic data from the current time step.

• step – The current time step index (zero indexed).

Returns:

None

Raises:

NotImplementedError – Always. Subclasses must override this method.

get_steady_problem(

step: int,

) → SteadyProblem

Get the SteadyProblem at a given time step.

Parameters:

step – The time step index (zero indexed). Must be greater than or equal to zero and less than the total number of time steps.

Returns:

The SteadyProblem at the specified time step.