Python API reference

Python API reference#

The CPU backend is imported from mjorbit. Prefer model.make_data(...) to construct runtime state. See GPU simulation for the corresponding mjorbit_warp lifecycle and synchronization functions.

Model and data#

class mjorbit.MjoModel(native, *, raw_xml=None)#

Compiled mjorbit model.

The underlying mjModel is owned by C++ and intentionally not exposed as a Python MuJoCo object. Public fields mirror the parts of MuJoCo’s Python API that mjorbit supports directly.

Parameters:

native (_bindings.MjoModel)
raw_xml (str | None)

classmethod from_xml_path(xml_path, *, mj_timestep=None, **kwargs)#

Parameters:

xml_path (str)
mj_timestep (float | None)
kwargs (Any)

Return type:

MjoModel

property backend: str#

property central_body#

body_id(name)#

Parameters:: name (str)
Return type:: int

sensor(name)#

Parameters:: name (str)

make_data(*, orbit=None, rng_seed=None)#

Parameters:: rng_seed (int | None)

class mjorbit.MjoData(model, *, orbit=None, rng_seed=None)#

Runtime state for one simulation run.

One MjoData owns one C++ mjData plus one thread-local orbit plugin instance and associated actuator/sensor buffers.

Parameters:

model (MjoModel)
orbit (OrbitInit | None)
rng_seed (int | None)

reset(orbit=None)#

Parameters:: orbit (OrbitInit | None)
Return type:: None

eci_position_from_world(position_world_m)#

Parameters:: position_world_m (Any)
Return type:: ndarray

eci_velocity_from_world(velocity_world_m_s)#

Parameters:: velocity_world_m_s (Any)
Return type:: ndarray

world_position_from_lvlh(position_lvlh_m)#

Parameters:: position_lvlh_m (Any)
Return type:: ndarray

world_velocity_from_lvlh(position_lvlh_m, velocity_lvlh_m_s)#

Parameters:

position_lvlh_m (Any)
velocity_lvlh_m_s (Any)

Return type:

ndarray

lvlh_position_from_world(position_world_m)#

Parameters:: position_world_m (Any)
Return type:: ndarray

lvlh_velocity_from_world(position_world_m, velocity_world_m_s)#

Parameters:

position_world_m (Any)
velocity_world_m_s (Any)

Return type:

ndarray

contact_force(contact_id)#

Parameters:: contact_id (int)
Return type:: ndarray

The wrappers forward supported native arrays and dimensions, including model.nq, model.nv, model.nu, data.qpos, data.qvel, data.ctrl, data.time, data.orbit, and data.actuators. Array units and frames are specified in frames and units.

mjorbit.mjo_forward(model, data)#

Synchronize derived runtime state after direct mutation.

Parameters:

model (MjoModel)
data (MjoData)

Return type:

None

mjorbit.mjo_step(model, data)#

Advance one fully coupled simulation step in-place.

Parameters:

model (MjoModel)
data (MjoData)

Return type:

None

Configuration#

class mjorbit.OrbitInit(R_eci, V_eci, t=0.0, frame='ECI', epoch=None)#

Initial chief orbit state (km, km/s).

By default R_eci/V_eci are interpreted directly as mjorbit’s canonical Earth-centered inertial frame — GCRF (J2000-aligned axes), with t measured as seconds since the J2000.0 epoch. Set frame (and epoch) to supply state in another standard realization (e.g. "TEME" from a TLE/SGP4 propagation, or an Earth-fixed "ITRF"/"ECEF" state — the ω×r velocity term is applied explicitly); it is rotated into the canonical frame at construction via mjorbit.frames, which requires the optional frames extra (pip install 'mjorbit[frames]').

Parameters:

R_eci (ndarray) – position, shape (3,), km, in frame.
V_eci (ndarray) – velocity, shape (3,), km/s, in frame.
t (float) – simulation clock, s. Interpreted as seconds since J2000.0 by the environment models. When epoch is given it is overridden by the epoch’s J2000 offset.
frame (str) – input frame name (case-insensitive). See mjorbit.frames.SUPPORTED_FRAMES. "ECI" (the default) means “already canonical” and performs no conversion.
epoch (object | None) – absolute time of the state, anchoring the canonical t to real wall time (ISO-UTC string, datetime, or astropy.time.Time). None keeps the relative t semantics. Required for epoch-dependent frames.

class mjorbit.MjoSpec(native)#

Editable mjorbit spec. Call compile() to create an immutable model.

Parameters:: native (Any)

classmethod from_xml_path(path)#

Parameters:: path (str)
Return type:: MjoSpec

classmethod from_xml_string(xml, assets=None)#

Parameters:

xml (str)
assets (Mapping[str, bytes | bytearray | memoryview | Iterable[int]] | None)

Return type:

MjoSpec

classmethod from_mj_spec(mj_spec, assets=None)#

Parameters:

mj_spec (Any)
assets (Mapping[str, bytes | bytearray | memoryview | Iterable[int]] | None)

Return type:

MjoSpec

copy()#

Return type:: MjoSpec

compile(*, mj_timestep=None)#

Parameters:: mj_timestep (float | None)

to_xml()#

Return type:: str

class mjorbit.MjoOrbitSpec(native)#

Mutable orbit configuration overlay held by MjoSpec.

Parameters:: native (Any)

property plugin_body: str | None#

property use_j2: bool#

property use_drag: bool#

property use_srp: bool#

property use_magnetic: bool#

property use_gravity_gradient: bool#

property orbit_dt: float | None#

property central_body: CentralBodySpec#

property surfaces: list[SurfaceSpec]#

property magnetic_bodies: list[MagneticBodySpec]#

property reaction_wheels: list[ReactionWheelSpec]#

property magnetorquers: list[MagnetorquerSpec]#

property thrusters: list[ThrusterSpec]#

property cmgs: list[ControlMomentGyroSpec]#

add_surface(spec=None, **kwargs)#

Parameters:

spec (SurfaceSpec | None)
kwargs (Any)

Return type:

str

update_surface(element_name, spec=None, **kwargs)#

Parameters:

element_name (str)
spec (SurfaceSpec | None)
kwargs (Any)

Return type:

None

remove_surface(name)#

Parameters:: name (str)
Return type:: None

add_magnetic_body(spec=None, **kwargs)#

Parameters:

spec (MagneticBodySpec | None)
kwargs (Any)

Return type:

str

update_magnetic_body(element_name, spec=None, **kwargs)#

Parameters:

element_name (str)
spec (MagneticBodySpec | None)
kwargs (Any)

Return type:

None

remove_magnetic_body(name)#

Parameters:: name (str)
Return type:: None

add_reaction_wheel(spec=None, **kwargs)#

Parameters:

spec (ReactionWheelSpec | None)
kwargs (Any)

Return type:

str

update_reaction_wheel(element_name, spec=None, **kwargs)#

Parameters:

element_name (str)
spec (ReactionWheelSpec | None)
kwargs (Any)

Return type:

None

remove_reaction_wheel(name)#

Parameters:: name (str)
Return type:: None

add_magnetorquer(spec=None, **kwargs)#

Parameters:

spec (MagnetorquerSpec | None)
kwargs (Any)

Return type:

str

update_magnetorquer(element_name, spec=None, **kwargs)#

Parameters:

element_name (str)
spec (MagnetorquerSpec | None)
kwargs (Any)

Return type:

None

remove_magnetorquer(element_name)#

Parameters:: element_name (str)
Return type:: None

add_thruster(spec=None, **kwargs)#

Parameters:

spec (ThrusterSpec | None)
kwargs (Any)

Return type:

str

update_thruster(element_name, spec=None, **kwargs)#

Parameters:

element_name (str)
spec (ThrusterSpec | None)
kwargs (Any)

Return type:

None

remove_thruster(name)#

Parameters:: name (str)
Return type:: None

add_cmg(spec=None, **kwargs)#

Parameters:

spec (ControlMomentGyroSpec | None)
kwargs (Any)

Return type:

str

update_cmg(element_name, spec=None, **kwargs)#

Parameters:

element_name (str)
spec (ControlMomentGyroSpec | None)
kwargs (Any)

Return type:

None

remove_cmg(name)#

Parameters:: name (str)
Return type:: None

class mjorbit.CentralBodySpec(*, name='earth', gm=398600.4418, radius=6378.137, j2=0.00108262668, omega=(0.0, 0.0, 7.292115e-05), magnetic_b0=3.12e-05, magnetic_axis=(0.0, 0.0, -1.0), atmosphere_h0=400.0, atmosphere_rho0=2.62e-13, atmosphere_scale_height=58.2)#

Central-body and environment constants used by compiled orbit models.

Parameters:

name (str)
gm (float)
radius (float)
j2 (float)
omega (Iterable[float])
magnetic_b0 (float)
magnetic_axis (Iterable[float])
atmosphere_h0 (float)
atmosphere_rho0 (float)
atmosphere_scale_height (float)

class mjorbit.SurfaceSpec(body_name, center_of_pressure_body, normal_body, area, drag_coeff=2.2, srp_coeff=1.8, use_drag=True, use_srp=True, name=None)#

Metadata for one flat-plate aerodynamic / SRP surface.

Parameters:

body_name (str)
center_of_pressure_body (ndarray)
normal_body (ndarray)
area (float)
drag_coeff (float)
srp_coeff (float)
use_drag (bool)
use_srp (bool)
name (str | None)

class mjorbit.MagneticBodySpec(body_name, dipole_body, name=None)#

Magnetic dipole source attached to a MuJoCo body.

Parameters:

body_name (str)
dipole_body (ndarray)
name (str | None)

class mjorbit.ReactionWheelSpec(body_name, axis_body, inertia, speed_limit=None, torque_limit=None, name=None)#

Configuration for one reaction wheel.

Parameters:

body_name (str)
axis_body (ndarray)
inertia (float)
speed_limit (float | None)
torque_limit (float | None)
name (str | None)

class mjorbit.MagnetorquerSpec(body_name, axis_body, dipole_limit, name=None)#

Configuration for one magnetorquer.

Parameters:

body_name (str)
axis_body (ndarray)
dipole_limit (float)
name (str | None)

class mjorbit.ThrusterSpec(body_name, position_body, direction_body, force_limit, name=None)#

Configuration for one thruster.

Parameters:

body_name (str)
position_body (ndarray)
direction_body (ndarray)
force_limit (float)
name (str | None)

class mjorbit.ControlMomentGyroSpec(body_name, gimbal_axis_body, spin_axis_body_0, rotor_momentum, gimbal_rate_limit=None, gimbal_angle_limit=None, name=None)#

Configuration for one single-gimbal control moment gyro (SGCMG).

The rotor is idealized as spinning at constant angular momentum rotor_momentum about the spin axis spin_axis_body_0 (at gimbal angle θ = 0). The gimbal axis gimbal_axis_body is body-fixed and must be orthogonal to spin_axis_body_0. As the gimbal rotates by angle θ about gimbal_axis_body, the spin axis rotates within the plane orthogonal to the gimbal axis, and the rotor momentum vector in the body frame becomes:

ŝ(θ) = cos(θ) · spin_axis_body_0 + sin(θ) · (gimbal_axis_body × spin_axis_body_0)
h(θ) = rotor_momentum · ŝ(θ)

The controllable output torque on the spacecraft body from gimbaling at rate θ̇ is -rotor_momentum · θ̇ · t̂(θ) where t̂(θ) = gimbal_axis_body × ŝ(θ).

Parameters:

body_name (str)
gimbal_axis_body (ndarray)
spin_axis_body_0 (ndarray)
rotor_momentum (float)
gimbal_rate_limit (float | None)
gimbal_angle_limit (float | None)
name (str | None)

Rollout and planning#

mjorbit.mjo_state_size(model)#

Return the length of a full mjo rollout state vector.

Parameters:: model (MjoModel)
Return type:: int

mjorbit.mjo_control_size(model, control_spec=64)#

Return the length of one open-loop mjo control vector.

Parameters:

model (MjoModel)
control_spec (int)

Return type:

int

mjorbit.mjo_get_state(model, data, out=None)#

Pack data into a full mjo rollout state vector.

Parameters:

model (MjoModel)
data (MjoData)
out (ndarray | None)

Return type:

ndarray

mjorbit.mjo_set_state(model, data, state)#

Unpack a full mjo rollout state vector into data.

Parameters:

model (MjoModel)
data (MjoData)
state (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes])

Return type:

None

mjorbit.rollout(model, data, initial_state=None, control=None, *, control_spec=64, nstep=None, initial_warmstart=None, state=None, sensordata=None, nthread=None)#

Roll out batched open-loop trajectories and return states and sensors.

When nthread is None or 1, the rollout runs on the calling thread using the supplied data as workspace. When nthread > 1, the function allocates nthread - 1 additional MjoData instances sharing model, splits the batch across a ThreadPoolExecutor, and joins the results.

Parameters:

model (MjoModel)
data (MjoData)
initial_state (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None)
control (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None)
control_spec (int)
nstep (int | None)
initial_warmstart (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None)
state (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None)
sensordata (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None)
nthread (int | None)

Return type:

tuple[ndarray, ndarray]

class mjorbit.planning.MppiConfig(horizon=2.0, num_rollouts=32, num_nodes=4, spline_order='linear', sigma=0.1, temperature=0.05, use_noise_ramp=False, noise_ramp=2.5, nthread=1, seed=None)#

MPPI hyperparameters (judo’s MPPIConfig defaults, except a larger num_rollouts).

Parameters:

horizon (float)
num_rollouts (int)
num_nodes (int)
spline_order (str)
sigma (float | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes])
temperature (float)
use_noise_ramp (bool)
noise_ramp (float)
nthread (int)
seed (int | None)

class mjorbit.planning.MppiPlanner(model, config, cost_fn, *, ctrl_low=None, ctrl_high=None)#

Receding-horizon MPPI over spline control knots.

Usage:

planner = MppiPlanner(model, MppiConfig(...), cost_fn)
planner.reset(data)
...
planner.update_action(data)        # replan from data's current state
u = planner.action(data.time)      # query the plan as time advances

Parameters:

model (MjoModel)
config (MppiConfig)
cost_fn (CostFn)
ctrl_low (ArrayLike | None)
ctrl_high (ArrayLike | None)

reset(data, nominal_knots=None)#

Anchor the plan at data’s current time, optionally seeding the knots.

Parameters:

data (MjoData)
nominal_knots (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None)

Return type:

None

action(time)#

Evaluate the current nominal plan at time (clamped to the horizon).

Parameters:: time (float)
Return type:: ndarray

update_action(data)#

Run one MPPI update from data’s current state.

Samples knot perturbations around the time-shifted nominal plan, rolls them out with mjorbit.rollout, reweights, and rebuilds the nominal spline. data is used as the rollout workspace; its physics and orbit state (qpos/qvel/act/time/orbit) and data.ctrl are restored (including a forward pass) before returning. Orbital actuator commands and applied-force buffers are reset by the rollout, so re-apply inputs (e.g. from action()) before stepping the plant. Returns the per-rollout costs.

Parameters:: data (MjoData)
Return type:: ndarray

mjorbit.planning.make_spline(times, knots, spline_order)#

Interpolate (possibly batched) (..., num_nodes, ncontrol) knots over time.

Queries outside times clamp to the edge knots, so a stale spline can be re-queried at shifted times when the plan is re-anchored each replan.

Parameters:

times (ndarray)
knots (ndarray)
spline_order (str)

Return type:

interp1d

Python API reference

Contents

Python API reference#

Model and data#

Configuration#

Rollout and planning#