mdp

Modules:

Name	Description
actions
commands
rewards

Classes:

Name	Description
FlightActionMapper	Map batched normalized actions into controller targets, wrench, or RPM.
FlightMappingLimits	Per-channel limits used when mapping normalized actions to targets.
Mixer	Map thrust and moment demands to rotor commands.
FlightController	PID flight controller (batched).
VehicleParams	LAV2 vehicle parameters.
RotorDynamics	Batched rotor dynamics model.
ControlActionManager	Base class for action managers that control actuators.
PositionDebugVisualizerConfig	Defines the configuration for the debug visualizer.
PositionCommandManager	Generates a position command from uniform distribution.

Functions:

Name	Description
lin_vel_l2	Penalize base linear velocity using L2 squared kernel.
ang_vel_l2	Penalize base angular velocity using L2 squared kernel.
pos_error_l2	Penalize asset pos from its target pos using L2 squared kernel.
pos_error_tanh	Penalize asset pos from its target pos using tanh kernel.

FlightActionMapper

FlightActionMapper(control_mode: str, params: VehicleParams = VehicleParams(), limits: FlightMappingLimits = FlightMappingLimits(), *, num_envs: int = 1, device: str | device = 'cpu')

Map batched normalized actions into controller targets, wrench, or RPM.

Initialize a batched Torch flight action mapper for the selected mode.

Methods:

Name	Description
map_action	Map a normalized batched action into RPM commands and intermediates.

Attributes:

Name	Type	Description
requires_controller	bool	Whether this mode needs a controller target expansion step.

requires_controller property

requires_controller: bool

Whether this mode needs a controller target expansion step.

map_action

map_action(action: Tensor, mixer: Mixer, *, state: Tensor | None = None, flight_controller: ControllerBase | None = None) -> FlightMappingResult

Map a normalized batched action into RPM commands and intermediates.

FlightMappingLimits dataclass

FlightMappingLimits(vel_limits: tuple[float, float, float] = (5.0, 5.0, 5.0), att_limits: tuple[float, float, float] = (1.0, 1.0, math.pi), br_limits: tuple[float, float, float] = (2.0, 2.0, 2.0))

Per-channel limits used when mapping normalized actions to targets.

Mixer

Mixer(params: VehicleParams = VehicleParams(), num_envs: int = 1, device: str | device = 'cpu')

Map thrust and moment demands to rotor commands.

Note

电机推力分配： 电机1 = 推力 - 横滚(roll) + 俯仰(pitch) + 偏航(yaw) 电机2 = 推力 + 横滚(roll) - 俯仰(pitch) + 偏航(yaw) 电机3 = 推力 + 横滚(roll) + 俯仰(pitch) - 偏航(yaw) 电机4 = 推力 - 横滚(roll) - 俯仰(pitch) - 偏航(yaw)

Initialize the torch mixer with vehicle parameters and device.

Methods:

Name	Description
randomize	Randomize mixer runtime parameters from nominal values.
apply_thrust_curve	Apply thrust curve to normalized thrust command.
calculate_rotor_commands	Allocate thrust and moments into rotor speeds.

randomize

randomize(env_ids=None, randomization=None)

Randomize mixer runtime parameters from nominal values.

apply_thrust_curve

apply_thrust_curve(normalized_thrust: Tensor, mode: int = 1) -> torch.Tensor

Apply thrust curve to normalized thrust command.

References

cmd_ctatt: https://github.com/PX4/PX4-Autopilot/blob/e5a483e4b71ab4b994cb0121fe28992d8ce0c8cd/src/modules/mc_att_control/mc_att_control_main.cpp#L111-L137 cmd_ctbr: https://github.com/PX4/PX4-Autopilot/blob/e5a483e4b71ab4b994cb0121fe28992d8ce0c8cd/src/modules/mc_rate_control/MulticopterRateControl.cpp#L156-L179

Parameters:

Name	Type	Description	Default
normalized_thrust	Tensor	Normalized thrust command [-1, 1]. Shape: arbitrary, e.g. (num_envs, n_motors). Applied elementwise.	required
mode	int	Thrust curve mode.	1

Returns:

Type	Description
Tensor	torch.Tensor: Thrust in Newtons with the same shape as normalized_thrust.

Raises:

Type	Description
NotImplementedError	If the specified mode is not implemented.

calculate_rotor_commands

calculate_rotor_commands(control: Tensor) -> torch.Tensor

Allocate thrust and moments into rotor speeds.

Parameters:

Name	Type	Description	Default
control	Tensor	Desired total thrust and roll/pitch/yaw moments. Shape: (num_envs, 4)	required

Returns:

Type	Description
Tensor	torch.Tensor: The amplitude of each motor's rotational speed (calculated using sqrt(clip(rpm_sq))). Shape: (num_envs, 4)

FlightController

FlightController(params: VehicleParams = VehicleParams(), control_mask: list[int] = [1, 1, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0], gains: dict | None = None, limits: dict | None = None, num_envs: int = 1, device: str | device = 'cpu')

Bases: ControllerBase

PID flight controller (batched).

Initialize the batched flight PID controller.

Methods:

Name	Description
randomize	Randomize configured PID gains and command limits for selected environments.
reset	Reset PID loops for selected environments.
update	Update controller.

Attributes:

Name	Type	Description
params	VehicleParams	Vehicle parameters for the controller.
control_mask	ndarray | Tensor	unified control mask for target/state channels, used in update(). e.g. using 9~11 for attitude yaw control.

params instance-attribute

params: VehicleParams = params

Vehicle parameters for the controller.

control_mask instance-attribute

control_mask: ndarray | Tensor = control_mask

unified control mask for target/state channels, used in update(). e.g. using 9~11 for attitude yaw control.

randomize

randomize(env_ids=None, gains=None, limits=None)

Randomize configured PID gains and command limits for selected environments.

reset

reset(env_ids)

Reset PID loops for selected environments.

update

update(target: Tensor, state: Tensor) -> torch.Tensor

Update controller.

Parameters:

Name	Type	Description	Default
target	Tensor	(N, 12) desired [x, y, z, vx, vy, vz, roll, pitch, yaw, wx, wy, wz]	required
state	Tensor	(N, 12) current state same ordering.	required

Returns:

Type	Description
Tensor	torch.Tensor: Tensor of shape (N, 4): [thrust, roll_moment, pitch_moment, yaw_moment].

VehicleParams dataclass

VehicleParams(rho: float = 1.184, g: float = 9.81, sim_dt: float = 0.01, step_dt: float = 0.01, randomization: dict[str, dict[str, tuple[float, float]]] = dict(), mass: float = 2.1, inertia: list = (lambda: np.diag([0.11, 0.108, 0.215]).tolist())(), diameter: float = 0.476, Cdx: float = 0.5, x: float = 0.0952, y: float = 0.114423, h: float = -0.0125, alpha: float = 8 * (np.pi / 180), r_p: float = 0.0775, J_m: float = 1e-05, Ct: float = 0.666, Cq: float = 0.0716, theta0: float = 14.6 * (np.pi / 180), thetaTip: float = 6.8 * (np.pi / 180), lock: float = 0.6051, max_rpm: float = 10000.0, init_rpm: float = -1.0, rotor_rpm_rate_limit: float = 50000.0, tau_f: float = 0.01, tau_m: float = 0.05, tau_up: float = -1.0, tau_down: float = -1.0, r_w: float = 0.0285, n_w: int = 4, B: float = 0.136, L: float = 0.23, h_cg: float = 0.078, f: float = 0.01, mu0: float = 0.8, K: float = 20, track_cmd_rate_limit: float = 100, min_throttle_manual: float = 0.08, min_throttle: float = 0.12, max_throttle: float = 1.0, hover_throttle: float = -1)

LAV2 vehicle parameters.

Methods:

Name	Description
__post_init__	Calculate derived parameters.

Attributes:

Name	Type	Description
rho	float	空气密度 (kg/m^3)
g	float	重力加速度 (m/s^2)
sim_dt	float	仿真步长 (s)
step_dt	float	控制步长 (s)
randomization	dict[str, dict[str, tuple[float, float]]]	运行时参数随机化配置，按组件 (e.g. rotor/mixer) 划分为多个 scale 相对范围子表
mass	float	质量 (kg)
inertia	list	惯性矩阵 (kg*m^2)
diameter	float	直径 (m)
Cdx	float	空气阻力系数
x	float	x方向臂长 (m)
y	float	y方向臂长 (m)
h	float	重心高度 (m)
alpha	float	y方向涵道外倾角度 (rad)
r_p	float	螺旋桨半径 (m)
J_m	float	电机转动惯量 (kg*m^2)
Ct	float	推力系数
Cq	float	扭矩系数
theta0	float	桨根角 (rad)
thetaTip	float	桨尖角 (rad)
theta1	float	桨叶扭转角 (rad)
lock	float	Lock number
max_rpm	float	最大转速
init_rpm	float	初始转速
rotor_rpm_rate_limit	float	旋翼转速变化率限制 (rpm/s)
cT	float	转速平方到推力增益 (N/(rpm^2))
cM	float	转速平方到扭矩增益 (N*m/(rpm^2))
tau_f	float	电机滤波时间常数 (s)
tau_m	float	兼容保留的电机时间常数 (s)
tau_up	float	电机升速时间常数 (s)
tau_down	float	电机降速时间常数 (s)
r_w	float	主动轮半径 (m)
n_w	int	负重轮个数
B	float	两侧履带中心距 (m)
L	float	履带节点接地部分长度 (m)
h_cg	float	车体质心高度 (m)
f	float	滚动阻力系数(以干燥混凝土路面或沥青路面为例)
mu0	float	滑转率为1时的摩擦系数
K	float	依赖于土壤黏聚系数和摩擦特性的常数
track_cmd_rate_limit	float	履带主动轮指令变化率限制 (rad/s^2)
min_throttle_manual	float	MPC_MANTHR_MIN: Minimum manual thrust (0.0 - 1.0). Default: 0.08
min_throttle	float	MPC_THR_MIN: Minimum thrust in auto thrust control (0.05 - 1.0). Default: 0.12
max_throttle	float	MPC_THR_MAX: Maximum thrust in auto thrust control (0.0 - 1.0). Default: 1.0
hover_throttle	float	MPC_THR_HOVER: Hover throttle manual (0.1 - 0.8). Default: 0.5 in PX4, calculated hover throttle in LAV2

rho class-attribute instance-attribute

rho: float = 1.184

空气密度 (kg/m^3)

g class-attribute instance-attribute

g: float = 9.81

重力加速度 (m/s^2)

sim_dt class-attribute instance-attribute

sim_dt: float = 0.01

仿真步长 (s)

step_dt class-attribute instance-attribute

step_dt: float = 0.01

控制步长 (s)

randomization class-attribute instance-attribute

randomization: dict[str, dict[str, tuple[float, float]]] = field(default_factory=dict)

运行时参数随机化配置，按组件 (e.g. rotor/mixer) 划分为多个 scale 相对范围子表

mass class-attribute instance-attribute

mass: float = 2.1

质量 (kg)

inertia class-attribute instance-attribute

inertia: list = field(default_factory=lambda: tolist())

惯性矩阵 (kg*m^2)

diameter class-attribute instance-attribute

diameter: float = 0.476

直径 (m)

Cdx class-attribute instance-attribute

Cdx: float = 0.5

空气阻力系数

x class-attribute instance-attribute

x: float = 0.0952

x方向臂长 (m)

y class-attribute instance-attribute

y: float = 0.114423

y方向臂长 (m)

h class-attribute instance-attribute

h: float = -0.0125

重心高度 (m)

alpha class-attribute instance-attribute

alpha: float = 8 * (pi / 180)

y方向涵道外倾角度 (rad)

r_p class-attribute instance-attribute

r_p: float = 0.0775

螺旋桨半径 (m)

J_m class-attribute instance-attribute

J_m: float = 1e-05

电机转动惯量 (kg*m^2)

Ct class-attribute instance-attribute

Ct: float = 0.666

推力系数

Cq class-attribute instance-attribute

Cq: float = 0.0716

扭矩系数

theta0 class-attribute instance-attribute

theta0: float = 14.6 * (pi / 180)

桨根角 (rad)

thetaTip class-attribute instance-attribute

thetaTip: float = 6.8 * (pi / 180)

桨尖角 (rad)

theta1 class-attribute instance-attribute

theta1: float = field(init=False)

桨叶扭转角 (rad)

lock class-attribute instance-attribute

lock: float = 0.6051

Lock number

max_rpm class-attribute instance-attribute

max_rpm: float = 10000.0

最大转速

init_rpm class-attribute instance-attribute

init_rpm: float = -1.0

初始转速

rotor_rpm_rate_limit class-attribute instance-attribute

rotor_rpm_rate_limit: float = 50000.0

旋翼转速变化率限制 (rpm/s)

cT class-attribute instance-attribute

cT: float = field(init=False)

转速平方到推力增益 (N/(rpm^2))

cM class-attribute instance-attribute

cM: float = field(init=False)

转速平方到扭矩增益 (N*m/(rpm^2))

tau_f class-attribute instance-attribute

tau_f: float = 0.01

电机滤波时间常数 (s)

tau_m class-attribute instance-attribute

tau_m: float = 0.05

兼容保留的电机时间常数 (s)

tau_up class-attribute instance-attribute

tau_up: float = -1.0

电机升速时间常数 (s)

tau_down class-attribute instance-attribute

tau_down: float = -1.0

电机降速时间常数 (s)

r_w class-attribute instance-attribute

r_w: float = 0.0285

主动轮半径 (m)

n_w class-attribute instance-attribute

n_w: int = 4

负重轮个数

B class-attribute instance-attribute

B: float = 0.136

两侧履带中心距 (m)

L class-attribute instance-attribute

L: float = 0.23

履带节点接地部分长度 (m)

h_cg class-attribute instance-attribute

h_cg: float = 0.078

车体质心高度 (m)

f class-attribute instance-attribute

f: float = 0.01

滚动阻力系数(以干燥混凝土路面或沥青路面为例)

mu0 class-attribute instance-attribute

mu0: float = 0.8

滑转率为1时的摩擦系数

K class-attribute instance-attribute

K: float = 20

依赖于土壤黏聚系数和摩擦特性的常数

track_cmd_rate_limit class-attribute instance-attribute

track_cmd_rate_limit: float = 100

履带主动轮指令变化率限制 (rad/s^2)

min_throttle_manual class-attribute instance-attribute

min_throttle_manual: float = 0.08

MPC_MANTHR_MIN: Minimum manual thrust (0.0 - 1.0). Default: 0.08

min_throttle class-attribute instance-attribute

min_throttle: float = 0.12

MPC_THR_MIN: Minimum thrust in auto thrust control (0.05 - 1.0). Default: 0.12

max_throttle class-attribute instance-attribute

max_throttle: float = 1.0

MPC_THR_MAX: Maximum thrust in auto thrust control (0.0 - 1.0). Default: 1.0

hover_throttle class-attribute instance-attribute

hover_throttle: float = -1

MPC_THR_HOVER: Hover throttle manual (0.1 - 0.8). Default: 0.5 in PX4, calculated hover throttle in LAV2

__post_init__

__post_init__()

Calculate derived parameters.

RotorDynamics

RotorDynamics(params: VehicleParams = VehicleParams(), num_envs: int = 1, device: str | device = 'cpu')

Bases: DynamicsBase

Batched rotor dynamics model.

Initialize batched rotor dynamics on the specified device.

Methods:

Name	Description
randomize	Randomize rotor runtime parameters from nominal values.
update	Calculate the output thrust and torque for each motor based on the motor commands.
reset	Resets the rotor model to initial conditions.

Attributes:

Name	Type	Description
params	VehicleParams	Vehicle parameters for the dynamics model.

params instance-attribute

params: VehicleParams = params

Vehicle parameters for the dynamics model.

randomize

randomize(env_ids: slice | Sequence[int] | Tensor | None = None, randomization: dict[str, tuple[float, float]] | None = None) -> None

Randomize rotor runtime parameters from nominal values.

update

update(commands: Tensor) -> torch.Tensor

Calculate the output thrust and torque for each motor based on the motor commands.

Parameters:

Name	Type	Description	Default
commands	Tensor	Command tensor for each motor. Shape: (num_envs, 4)	required

Returns:

Type	Description
Tensor	torch.Tensor: Thrust and torque tensor for each motor. Shape: (num_envs, 8)

reset

reset(env_ids: slice | Sequence[int] | Tensor) -> None

Resets the rotor model to initial conditions.

Parameters:

Name	Type	Description	Default
env_ids	slice | Sequence[int] | Tensor	The environment ids to reset.	required

ControlActionManager

ControlActionManager(env: GenesisEnv, delay_step: int = 0, params: VehicleParams = VehicleParams(), gains: dict | None = None, limits: dict | None = None, entity_attr: str = 'robot', control_mode: str = 'cmd_motor_speeds')

Bases: BaseActionManager

Base class for action managers that control actuators.

Parameters:

Name	Type	Description	Default
env	GenesisEnv	The environment to manage the DOF actuators for.	required
delay_step	int	The number of steps to delay the actions for. This is an easy way to emulate the latency in the system.	0
params	VehicleParams	Vehicle physical parameters.	VehicleParams()
entity_attr	str	Attribute name on the environment for the robot entity.	'robot'
control_mode	str	Control mode string (e.g. 'cmd_motor_speeds').	'cmd_motor_speeds'

Methods:

Name	Description
step	Handle the received actions.
reset	Reset environments.
get_actions	Get the current actions for the environments.

Attributes:

Name	Type	Description
num_actions	int	The total number of actions.
action_space	tuple[float, float]	If using the default action handler, the action space is [-1, 1].
actions	Tensor	The actions for for the current step.
raw_actions	Tensor	The actions received from the policy, before being converted.

num_actions property

num_actions: int

The total number of actions.

action_space property

action_space: tuple[float, float]

If using the default action handler, the action space is [-1, 1].

actions property

actions: Tensor

The actions for for the current step.

raw_actions property

raw_actions: Tensor

The actions received from the policy, before being converted.

step

step(actions: Tensor) -> None

Handle the received actions.

reset

reset(envs_idx: list[int] | None)

Reset environments.

get_actions

get_actions() -> torch.Tensor

Get the current actions for the environments.

PositionDebugVisualizerConfig

Bases: TypedDict

Defines the configuration for the debug visualizer.

Attributes:

Name	Type	Description
envs_idx	list[int]	The indices of the environments to visualize. If None, all environments will be visualized.
sphere_offset	float	The vertical offset of the debug arrows from the top of the robot
sphere_radius	float	The radius of the shaft of the debug arrows
commanded_color	tuple[float, float, float, float]	The color of the commanded velocity arrow

envs_idx instance-attribute

envs_idx: list[int]

The indices of the environments to visualize. If None, all environments will be visualized.

sphere_offset instance-attribute

sphere_offset: float

The vertical offset of the debug arrows from the top of the robot

sphere_radius instance-attribute

sphere_radius: float

The radius of the shaft of the debug arrows

commanded_color instance-attribute

commanded_color: tuple[float, float, float, float]

The color of the commanded velocity arrow

PositionCommandManager

PositionCommandManager(env: GenesisEnv, range: PositionCommandRange, resample_time_sec: float = 5.0, debug_visualizer: bool = False, debug_visualizer_cfg: PositionDebugVisualizerConfig = DEFAULT_VISUALIZER_CONFIG)

Bases: CommandManager

Generates a position command from uniform distribution. The command comprises of a linear velocity in x and y direction and an angular velocity around the z-axis.

IMPORTANT: The position commands are interpreted as world-relative coordinates: - X-axis: x coordinate of the target position - Y-axis: y coordinate of the target position - Z-axis: z coordinate of the target position

Debug visualization:

If `debug_visualizer` is set to True, a target sphere is rendered above
the commanded position.

Visual meaning:

- GREEN: Commanded position for the robot in the world frame

Parameters:

Name	Type	Description	Default
env	GenesisEnv	The environment to control	required
range	PositionCommandRange	The ranges of linear & angular velocities	required
resample_time_sec	float	The time interval between changing the command	5.0
debug_visualizer	bool	Enable the debug arrow visualization	False
debug_visualizer_cfg	PositionDebugVisualizerConfig	The configuration for the debug visualizer	DEFAULT_VISUALIZER_CONFIG

Example::

class MyEnv(GenesisEnv):
    def config(self):
        # Create a velocity command manager
        self.command_manager = PositionCommandManager(
            self,
            visualize=True,
            range = {
                "lin_vel_x_range": (-1.0, 1.0),
                "lin_vel_y_range": (-1.0, 1.0),
                "ang_vel_z_range": (-0.5, 0.5),
            }
        )

        RewardManager(
            self,
            logging_enabled=True,
            cfg={
                "tracking_lin_vel": {
                    "weight": 1.0,
                    "fn": rewards.command_tracking_lin_vel,
                    "params": {
                        "vel_cmd_manager": self.velocity_command,
                    },
                },
                "tracking_ang_vel": {
                    "weight": 1.0,
                    "fn": rewards.command_tracking_ang_vel,
                    "params": {
                        "vel_cmd_manager": self.velocity_command,
                    },
                },
                # ... other rewards ...
            },
        )

        # Observations
        ObservationManager(
            self,
            cfg={
                "velocity_cmd": {"fn": self.velocity_command.observation},
                # ... other observations ...
            },
        )

Methods:

Name	Description
resample_command	Overwrites commands for environments that should be standing still.
build	Build the position command manager
step	Render the command arrows
use_gamepad	Use a connected gamepad to control the command.

Attributes:

Name	Type	Description
command	Tensor	The desired command value. Shape is (num_envs, num_ranges).

command property

command: Tensor

The desired command value. Shape is (num_envs, num_ranges).

resample_command

resample_command(env_ids: list[int])

Overwrites commands for environments that should be standing still.

build

build()

Build the position command manager

step

step()

Render the command arrows

use_gamepad

use_gamepad(gamepad: Gamepad, pos_x_axis: int = 0, pos_y_axis: int = 1, pos_z_axis: int = 2)

Use a connected gamepad to control the command.

Parameters:

Name	Type	Description	Default
gamepad	Gamepad	The gamepad to use.	required
pos_x_axis	int	Map this gamepad axis index to the position in the x-direction.	0
pos_y_axis	int	Map this gamepad axis index to the position in the y-direction.	1
pos_z_axis	int	Map this gamepad axis index to the position in the z-direction.	2

lin_vel_l2

lin_vel_l2(env: GenesisEnv, entity_attr: str = 'robot', entity_manager: EntityManager = None) -> torch.Tensor

Penalize base linear velocity using L2 squared kernel.

ang_vel_l2

ang_vel_l2(env: GenesisEnv, entity_attr: str = 'robot', entity_manager: EntityManager = None) -> torch.Tensor

Penalize base angular velocity using L2 squared kernel.

pos_error_l2

pos_error_l2(env: GenesisEnv, target_pose: Tensor = None, pose_command: CommandManager = None) -> torch.Tensor

Penalize asset pos from its target pos using L2 squared kernel.

pos_error_tanh

pos_error_tanh(env: GenesisEnv, target_pose: Tensor = None, std: float = 0.8, pose_command: CommandManager = None) -> torch.Tensor

Penalize asset pos from its target pos using tanh kernel.