aerodynamics

Batched aerodynamic-effect models for multirotor simulation.

Each implemented equation is tied to the literature cited beside the relevant method. Their composition order and the analytic-plane geometry are LAV2 integration choices, not claims made by a downstream benchmark or simulator.

类：

名称	描述
AerodynamicEffectsCfg	Environment-specific aerodynamic-effect configuration.
AerodynamicEffects	Compute drag, ground effect, and planar near-wall effect in batches.

AerodynamicEffectsCfg dataclass

AerodynamicEffectsCfg(*, enable_drag: bool = False, enable_external_force: bool = False, enable_ground_effect: bool = False, enable_wall_effect: bool = False, external_force_w: tuple[float, float, float] = (0.0, 0.0, 0.0), ground_height: float = 0.0, max_ground_effect_gain: float = 2.0, wall_plane_point_w: tuple[float, float, float] = (0.0, 0.0, 0.0), wall_plane_normal_w: tuple[float, float, float] = (1.0, 0.0, 0.0), max_surface_distance: float = 5.0)

Environment-specific aerodynamic-effect configuration.

Plane coordinates use each simulator environment's local world frame. Effects default to disabled so existing tasks retain their current physics.

属性：

名称	类型	描述
enable_drag	bool	Apply body-axis linear drag.
enable_external_force	bool	Apply the configured world-frame external force.
enable_ground_effect	bool	Augment per-rotor thrust near a horizontal ground plane.
enable_wall_effect	bool	Apply per-rotor forces near the configured wall plane.
external_force_w	tuple[float, float, float]	Constant environment-local world-frame external force (N).
ground_height	float	Height of the analytic horizontal ground plane (m).
max_ground_effect_gain	float	Maximum ground-effect thrust multiplier used near the model singularity.
wall_plane_point_w	tuple[float, float, float]	One point on the analytic wall plane (m).
wall_plane_normal_w	tuple[float, float, float]	Wall-plane unit-normal direction; either side of the plane is valid.
max_surface_distance	float	Distance beyond which surface effects are exactly disabled (m).

enable_drag class-attribute instance-attribute

enable_drag: bool = False

Apply body-axis linear drag.

enable_external_force class-attribute instance-attribute

enable_external_force: bool = False

Apply the configured world-frame external force.

enable_ground_effect class-attribute instance-attribute

enable_ground_effect: bool = False

Augment per-rotor thrust near a horizontal ground plane.

enable_wall_effect class-attribute instance-attribute

enable_wall_effect: bool = False

Apply per-rotor forces near the configured wall plane.

external_force_w class-attribute instance-attribute

external_force_w: tuple[float, float, float] = (0.0, 0.0, 0.0)

Constant environment-local world-frame external force (N).

ground_height class-attribute instance-attribute

ground_height: float = 0.0

Height of the analytic horizontal ground plane (m).

max_ground_effect_gain class-attribute instance-attribute

max_ground_effect_gain: float = 2.0

Maximum ground-effect thrust multiplier used near the model singularity.

wall_plane_point_w class-attribute instance-attribute

wall_plane_point_w: tuple[float, float, float] = (0.0, 0.0, 0.0)

One point on the analytic wall plane (m).

wall_plane_normal_w class-attribute instance-attribute

wall_plane_normal_w: tuple[float, float, float] = (1.0, 0.0, 0.0)

Wall-plane unit-normal direction; either side of the plane is valid.

max_surface_distance class-attribute instance-attribute

max_surface_distance: float = 5.0

Distance beyond which surface effects are exactly disabled (m).

AerodynamicEffects

AerodynamicEffects(params: VehicleParams = VehicleParams(), cfg: AerodynamicEffectsCfg | None = None, num_envs: int = 1, num_rotors: int = 4, device=None, *, backend: BackendName | None = None, xp: ModuleType | None = None)

Compute drag, ground effect, and planar near-wall effect in batches.

Surface geometry is represented in each environment's local world frame. Rotor-force increments, body forces, and force telemetry are represented in the vehicle body frame. The model owns no simulator objects and can therefore be shared by NumPy, Torch, JAX, and CuPy callers.

Initialize coefficients, plane geometry, and telemetry buffers.

参数：

名称	类型	描述	默认
params	VehicleParams	Vehicle physical and aerodynamic coefficients.	VehicleParams()
cfg	AerodynamicEffectsCfg | None	Environment-specific switches, wind, and plane geometry.	None
num_envs	int	Number of parallel simulation environments.	1
num_rotors	int	Number of rotors per environment.	4
device		Optional backend device, mainly used by Torch.	None
backend	BackendName | None	Explicit Array API backend name.	None
xp	ModuleType | None	Pre-resolved Array API namespace. Overrides backend.	None

方法：

名称	描述
randomize	Sample per-environment aerodynamic state for selected environments.
set_external_force	Set one shared or per-environment world-frame external force.
set_wall_plane	Set one shared or per-environment wall plane.
update	Compute rotor-force increments and root-body force for one simulation step.

属性：

名称	类型	描述
enabled	bool	Whether any aerodynamic effect is enabled.

enabled property

enabled: bool

Whether any aerodynamic effect is enabled.

randomize

randomize(env_ids: ArrayLike | list[int] | slice | None = None, parameter_ranges: dict[str, tuple[ArrayLike, ArrayLike]] | None = None, effect_probabilities: dict[str, float] | None = None, effect_scale_ranges: dict[str, tuple[ArrayLike, ArrayLike]] | None = None) -> None

Sample per-environment aerodynamic state for selected environments.

Parameter ranges are absolute values rather than multipliers. Effect probabilities create exact per-episode on/off masks, while scale ranges multiply the corresponding computed force increment. If every optional argument is omitted, configuration is read from params.randomization["aerodynamics"].

参数：

名称	类型	描述	默认
env_ids	ArrayLike | list[int] | slice | None	Environment indices to resample, or all environments.	None
parameter_ranges	dict[str, tuple[ArrayLike, ArrayLike]] | None	Absolute ranges for aerodynamic coefficients.	None
effect_probabilities	dict[str, float] | None	Bernoulli probability for each effect.	None
effect_scale_ranges	dict[str, tuple[ArrayLike, ArrayLike]] | None	Multiplicative force-scale range per effect.	None

引发：

类型	描述
ValueError	If a key, probability, or physical range is invalid.

set_external_force

set_external_force(external_force_w: ArrayLike) -> None

Set one shared or per-environment world-frame external force.

set_wall_plane

set_wall_plane(point_w: ArrayLike, normal_w: ArrayLike) -> None

Set one shared or per-environment wall plane.

Moving-surface scenarios can call this before :meth:update to update the analytic plane pose.

引发：

类型	描述
ValueError	If any wall normal is zero, near-zero, or non-finite.

update

update(rotor_thrusts: ArrayLike, rotor_positions_w: ArrayLike, rotor_axes_b: ArrayLike, body_velocity_b: ArrayLike, body_rotation_wb: ArrayLike) -> tuple[ArrayLike, ArrayLike]

Compute rotor-force increments and root-body force for one simulation step.

参数：

名称	类型	描述	默认
rotor_thrusts	ArrayLike	Positive rotor thrust magnitudes, shape (N, R).	必需
rotor_positions_w	ArrayLike	Rotor centers in environment-local world frame, shape (N, R, 3).	必需
rotor_axes_b	ArrayLike	Rotor positive-thrust axes in vehicle body frame, shape (N, R, 3).	必需
body_velocity_b	ArrayLike	Root-body velocity in the vehicle body frame, shape (N, 3).	必需
body_rotation_wb	ArrayLike	Body-to-world rotation matrices, shape (N, 3, 3).	必需

返回：

类型	描述
ArrayLike	Tuple of per-rotor vehicle-body-frame force increments (N, R, 3)
ArrayLike	and root-body-frame drag plus prescribed force (N, 3).