bam.mjlab

BAM actuator models for mjlab (MuJoCo Warp).

Wraps any BAM Model (m1–m6) into mjlab’s actuator framework. All friction computations are fully vectorized over the (num_envs, num_joints) batch dimension using PyTorch.

Usage example — bundled motor:

from bam.mjlab import make_bam_actuator_cfg

actuator_cfg = make_bam_actuator_cfg(
    motor_name="xl330",
    model="m6",
    target_names_expr=(r".*",),
)

Usage example — custom JSON path:

actuator_cfg = make_bam_actuator_cfg(
    json_path="params/xl330/m6.json",
    target_names_expr=(r".*",),
)

Classes

BamActuatorCfg	Configuration for a BAM actuator compatible with mjlab.
BamActuator	BAM actuator for mjlab — fully vectorized over all parallel environments.

Module Contents

class bam.mjlab.BamActuatorCfg

Bases: mjlab.actuator.actuator.ActuatorCfg

Configuration for a BAM actuator compatible with mjlab.

Specify the model with one of two mutually exclusive approaches:

• Bundled motor: set motor_name (e.g. “xl330”) and model (e.g. “m6”). The path is resolved automatically from the params/ directory bundled with the library.

• Custom JSON: set json_path to a BAM params JSON file produced by bam.fit.

Parameters:

• motor_name – Name of the bundled motor. Currently supported: “xl330”, “xl320”, “mx106”, “mx64”, “erob80:50”, and “erob80:100”. Mutually exclusive with json_path.

• model – Model variant to use with motor_name, one of “m1”–“m6”. Mutually exclusive with json_path.

• json_path – Path to a custom BAM params JSON file produced by bam.fit. Mutually exclusive with motor_name and model.

• target_names_expr – Tuple of regex patterns to match actuated joint names.

• vin – Supply voltage override [V]. None → uses the value in the JSON.

• kp_fw – Firmware P-gain override. None → uses the value in the JSON.

• vin_range – If set, a per-env battery voltage is sampled uniformly from this range at startup and held constant across resets. Takes precedence over vin.

• vin_drop_gain_range – If set, a per-env internal-resistance gain [V/Nm] is sampled uniformly from this range at startup. Models the voltage drop V_drop = gain * Σ|τ| due to battery + cable resistance. Gain should be approximately resistance / Kt. Held constant across resets.

• vin_min – Hard lower bound on the effective supply voltage [V] after applying the voltage drop. Ensures vin never falls below this value regardless of the load. None → no lower bound.

• max_current – Firmware current limit [A]. If set, the motor current is clipped to [-max_current, max_current] (equivalently the motor torque is clipped to ±max_current * kt), reproducing the firmware-side current saturation of the motor. None → no current clipping.

• delay_min_lag – Minimum command delay in simulation steps. Models the latency between the policy output and the motor response. 0 → no delay.

• delay_max_lag – Maximum command delay in simulation steps. Set greater than delay_min_lag to randomize the delay across environments.

• delay_hold_prob – Probability of keeping the same lag value at each step. 0.0 → lag is resampled every delay_update_period steps.

• delay_update_period – Number of steps between lag updates. 0 → updated every step.

• delay_per_env_phase – Whether each environment starts with an independent delay phase offset. True → environments are not synchronized.

motor_name: str | None = None

model: str | None = None

json_path: str | None = None

vin: float | None = None

kp_fw: float | None = None

vin_range: tuple[float, float] | None = None

vin_drop_gain_range: tuple[float, float] | None = None

vin_min: float | None = None

max_current: float | None = None

build(entity: mjlab.entity.Entity, target_ids: list[int], target_names: list[str]) → BamActuator

class bam.mjlab.BamActuator(cfg: BamActuatorCfg, entity: mjlab.entity.Entity, target_ids: list[int], target_names: list[str])

Bases: mjlab.actuator.actuator.Actuator

BAM actuator for mjlab — fully vectorized over all parallel environments.

Implements the BAM torque pipeline:

1. Voltage control law — firmware P-controller (position error → duty cycle → voltage).

2. DC motor torque — back-EMF equation (voltage → torque).

3. Friction budget — BAM m1–m6 friction model (Coulomb, Stribeck, load-dependent, directional, quadratic).

4. Static friction clipping — BAM Algorithm 1 (prevents overshoot when the joint is nearly stopped).

Per-environment gain scaling is supported via set_gains().

cfg: BamActuatorCfg

vin_tensor: torch.Tensor | None = None

vin_drop_gain: torch.Tensor | None = None

kp_scale: torch.Tensor | None = None

kd_scale: torch.Tensor | None = None

default_kp_scale: torch.Tensor | None = None

default_kd_scale: torch.Tensor | None = None

edit_spec(spec: mujoco.MjSpec, target_names: list[str]) → None

Convert position actuators to motor mode and zero MuJoCo friction.

We handle all friction ourselves inside compute(), so MuJoCo’s built-in frictionloss and damping are zeroed out here.

initialize(mj_model: mujoco.MjModel, model: mujoco_warp.Model, data: mujoco_warp.Data, device: str) → None

reset(env_ids: torch.Tensor | slice | None = None) → None

property command_field: mjlab.actuator.actuator.CommandField

set_gains(env_ids: torch.Tensor | slice, kp_scale: torch.Tensor | None = None, kd_scale: torch.Tensor | None = None) → None

Scale firmware gains for a subset of environments.

reset_gains(env_ids: torch.Tensor | slice) → None

Restore default gains for a subset of environments.

compute(cmd: mjlab.actuator.actuator.ActuatorCmd) → torch.Tensor

Compute output torques for all environments — shape (N, J).