Language

unilab.tasks.locomotion.common.gait_terms¶

mjlab-aligned gait-quality terms shared by locomotion families.

These are the window-form feet_air_time and the clearance / swing-height / slip / angular-momentum reward terms that mjlab ships in its velocity task, plus the privileged per-foot observation terms (foot_height / foot_air_time / foot_contact / foot_contact_forces) its velocity critic consumes. mjlab reads feet through a ContactSensor (primaries with per-slot any-reduce) and a TerrainHeightSensor; the UniLab port binds one named contact sensor group per foot through the SensorTermBase cold-path contract (any sensor in the group above the threshold means foot contact, mirroring the slot reduce) and reads foot heights/velocities from body_link_pos_w / body_link_lin_vel_w through asset_cfg.body_ids, which is exact on flat terrain without raycast.

Functions

`feet_clearance`(env, target_height[, ...])	Penalize clearance-height deviation weighted by planar foot velocity.
`foot_height`(env[, asset_cfg])	Per-foot vertical clearance above the terrain, shape `(num_envs, num_feet)`.

Classes

`angular_momentum_penalty`	Penalize whole-body angular momentum read from a named vec3 sensor.
`feet_air_time`	Count feet whose current air time sits inside the rewarded window.
`feet_slip`	Penalize foot sliding: squared xy velocity while the foot is in contact.
`feet_swing_height`	Penalize peak-swing-height deviation from the target, evaluated at landing.
`foot_air_time`	Current per-foot air time in seconds, shape `(num_envs, num_feet)`.
`foot_contact`	Per-foot contact flag as float, shape `(num_envs, num_feet)`.
`foot_contact_forces`	Log-compressed per-foot contact forces, shape `(num_envs, 3 * num_feet)`.
`self_collision_cost`	Count monitored self-collision geom pairs reporting contact.

class unilab.tasks.locomotion.common.gait_terms.angular_momentum_penalty[source]¶

Bases: SensorTermBase

Penalize whole-body angular momentum read from a named vec3 sensor.

Parameters:

cfg (ManagerTermBaseCfg)
env (ManagerBasedRlEnv)

__init__(cfg, env)[source]¶

Parameters:

cfg (ManagerTermBaseCfg)
env (ManagerBasedRlEnv)

class unilab.tasks.locomotion.common.gait_terms.feet_air_time[source]¶

Bases: _FootContactTerm

Count feet whose current air time sits inside the rewarded window.

Mirrors mjlab feet_air_time: air time accumulates env.step_dt while the foot has no contact and resets to zero on contact; a foot scores while threshold_min < air_time < threshold_max. When command_name is set the count is gated by the command gate.

Parameters:

cfg (ManagerTermBaseCfg)
env (ManagerBasedRlEnv)

__init__(cfg, env)[source]¶

Parameters:

cfg (ManagerTermBaseCfg)
env (ManagerBasedRlEnv)

reset(env_ids=None)[source]¶

Resets the manager term.

Parameters:: env_ids (ndarray | slice | None)
Return type:: None

unilab.tasks.locomotion.common.gait_terms.feet_clearance(env, target_height, command_name=None, command_threshold=0.01, asset_cfg=SceneEntityCfg(name='robot', joint_names=None, joint_ids=slice(None, None, None), body_names=None, body_ids=slice(None, None, None), geom_names=None, geom_ids=slice(None, None, None), site_names=None, site_ids=slice(None, None, None), actuator_names=None, actuator_ids=slice(None, None, None), tendon_names=None, tendon_ids=slice(None, None, None), camera_names=None, camera_ids=slice(None, None, None), light_names=None, light_ids=slice(None, None, None), material_names=None, material_ids=slice(None, None, None), texture_names=None, texture_ids=slice(None, None, None), pair_names=None, pair_ids=slice(None, None, None), preserve_order=False))[source]¶

Penalize clearance-height deviation weighted by planar foot velocity.

Mirrors mjlab feet_clearance with foot heights taken from world-frame foot body z (exact on flat terrain) instead of a terrain height sensor.

Parameters:

env (ManagerBasedRlEnv)
target_height (float)
command_name (str | None)
command_threshold (float)
asset_cfg (SceneEntityCfg)

Return type:

ndarray

class unilab.tasks.locomotion.common.gait_terms.feet_slip[source]¶

Bases: _FootContactTerm

Penalize foot sliding: squared xy velocity while the foot is in contact.

Parameters:

cfg (ManagerTermBaseCfg)
env (ManagerBasedRlEnv)

__init__(cfg, env)[source]¶

Parameters:

cfg (ManagerTermBaseCfg)
env (ManagerBasedRlEnv)

class unilab.tasks.locomotion.common.gait_terms.feet_swing_height[source]¶

Bases: _FootContactTerm

Penalize peak-swing-height deviation from the target, evaluated at landing.

Mirrors mjlab feet_swing_height: the peak foot height accumulates while the foot is in the air; on first contact the squared relative error (peak / target_height - 1)^2 is charged and the peak resets.

Parameters:

cfg (ManagerTermBaseCfg)
env (ManagerBasedRlEnv)

__init__(cfg, env)[source]¶

Parameters:

cfg (ManagerTermBaseCfg)
env (ManagerBasedRlEnv)

reset(env_ids=None)[source]¶

Resets the manager term.

Parameters:: env_ids (ndarray | slice | None)
Return type:: None

class unilab.tasks.locomotion.common.gait_terms.foot_air_time[source]¶

Bases: _FootContactTerm

Current per-foot air time in seconds, shape (num_envs, num_feet).

Mirrors mjlab foot_air_time (ContactSensor.data.current_air_time): the timer accumulates env.step_dt while the foot has no contact and resets to zero on contact.

Parameters:

cfg (ManagerTermBaseCfg)
env (ManagerBasedRlEnv)

__init__(cfg, env)[source]¶

Parameters:

cfg (ManagerTermBaseCfg)
env (ManagerBasedRlEnv)

reset(env_ids=None)[source]¶

Resets the manager term.

Parameters:: env_ids (ndarray | slice | None)
Return type:: None

class unilab.tasks.locomotion.common.gait_terms.foot_contact[source]¶

Bases: _FootContactTerm

Per-foot contact flag as float, shape (num_envs, num_feet).

Mirrors mjlab foot_contact (ContactSensor.data.found > 0).

Parameters:

cfg (ManagerTermBaseCfg)
env (ManagerBasedRlEnv)

class unilab.tasks.locomotion.common.gait_terms.foot_contact_forces[source]¶

Bases: _FootContactTerm

Log-compressed per-foot contact forces, shape (num_envs, 3 * num_feet).

Mirrors mjlab foot_contact_forces: the per-foot 3-D contact forces are flattened in sensor-group order and compressed as sign(f) * log1p(|f|).

Parameters:

cfg (ManagerTermBaseCfg)
env (ManagerBasedRlEnv)

__init__(cfg, env)[source]¶

Parameters:

cfg (ManagerTermBaseCfg)
env (ManagerBasedRlEnv)

unilab.tasks.locomotion.common.gait_terms.foot_height(env, asset_cfg=SceneEntityCfg(name='robot', joint_names=None, joint_ids=slice(None, None, None), body_names=None, body_ids=slice(None, None, None), geom_names=None, geom_ids=slice(None, None, None), site_names=None, site_ids=slice(None, None, None), actuator_names=None, actuator_ids=slice(None, None, None), tendon_names=None, tendon_ids=slice(None, None, None), camera_names=None, camera_ids=slice(None, None, None), light_names=None, light_ids=slice(None, None, None), material_names=None, material_ids=slice(None, None, None), texture_names=None, texture_ids=slice(None, None, None), pair_names=None, pair_ids=slice(None, None, None), preserve_order=False))[source]¶

Per-foot vertical clearance above the terrain, shape (num_envs, num_feet).

mjlab reads this from a TerrainHeightSensor ring around each foot; the UniLab port returns the world-frame foot body z, which is identical on flat terrain.

Parameters:

env (ManagerBasedRlEnv)
asset_cfg (SceneEntityCfg)

Return type:

ndarray

class unilab.tasks.locomotion.common.gait_terms.self_collision_cost[source]¶

Bases: _FootContactTerm

Count monitored self-collision geom pairs reporting contact.

Mirrors mjlab self_collision_cost in its found-count form: each sensor group binds one contact sensor watching a geom pair, and the cost is the number of pairs with an active contact. mjlab’s force_threshold only applies when the sensor records force history, which the upstream config does not enable, so it is not ported.

Parameters:

cfg (ManagerTermBaseCfg)
env (ManagerBasedRlEnv)