Examples

Purpose

Use this page after a successful install to look up the exact observation, action, reward, termination, configuration, and scene identity contracts for the three built-in example environments: CartPole, Ant, and HalfCheetah.

How to use this page

1. Use Quick comparison to choose an environment and confirm its default vector sizes, reward-term count, and termination behavior.
2. See the environment section for exact configuration defaults, flattened observation order, action bounds, reward terms, termination behavior, and scene identity.
3. Read Environment Class API before slicing vectors or sending actions, and use its runtime inspection example when configuration variants can change a size.

Every environment also inherits the shared MochiEnvCfg fields documented in Authoring a Custom Environment.

Quick comparison

Environment	Observation	Action	Reward terms	Terminates?
CartPole	4	1	1	yes
Ant	81	8	4	yes
HalfCheetah	17	6	2	no

CartPole

superdex_gym/CartPole-v0 · CLI cart_pole · superdex.lab.gym.envs.benchmarks.cartpole_env.CartPoleEnv

CartPole balances a pole on a cart moving along a linear rail. It is the smallest environment and the best smoke test. It requires only the benchmark scene assets (assets/benchmarks/cart_pole/) and no bot asset.

The superdex-robotics package is required by every environment

All environments require superdex-robotics, including CartPole and Ant. If its import fails, follow Verifying the Install.

from superdex.lab.gym.envs.benchmarks.cartpole_env import CartPoleEnv, CartPoleEnvCfg

env = CartPoleEnv(CartPoleEnvCfg())
env.close()

Configuration

Field	Default	Meaning
control_frequency	25	Hz
simulation_frequency	50	Hz — 2 substeps per control step
steps_per_episode	1000
reset_noise_scale	0.1
render_control	True	Stored on the environment but currently unused
actuate_on_pole	False	Apply the control force to the pole instead of the cart
use_damping	True	Joint viscous friction
use_gravity	True
free_pole	False	Remove the pole's joint limits

Observation — 4 elements

Key	Shape	Meaning
angular_vel	1	Angular velocity of the pole (rad/s)
linear_vel	1	Linear velocity of the cart (m/s)
position	1	Cart position along the rail (m)
vertical_ang	1	Vertical angle of the pole (rad)

Listed in flattened order.

Action — 1 element

control, bounded [-3.0, 3.0], is scaled by 100 and applied as a linear force on the prismatic cart DOF 0, or as a torque on the revolute pole DOF 1 when actuate_on_pole=True.

Reward

One term, upright_reward: 1.0 while |vertical_ang| <= 0.2, else 0.0.

Termination

Terminates with terminated_reason = "Pole angle exceeded threshold" once the pole leaves the upright band. Truncates at steps_per_episode.

Scene identity

uid_fields = (use_damping, use_gravity, free_pole) contains the three fields that change how the prefab is built. When use_shared_scenes=True, environments in the same process with matching values share one physics scene. Otherwise, each environment creates its own scene.

Ant

superdex_gym/Ant-v0 · CLI ant · superdex.lab.gym.envs.benchmarks.ant_env.AntEnv

Ant provides quadrupedal locomotion. Its reward favors forward progress and penalizes control effort and contact-wrench magnitude.

Configuration

Field	Default	Meaning
control_frequency	20	Hz
simulation_frequency	100	Hz — 5 substeps per control step
steps_per_episode	1000
reset_noise_scale	0.1
forward_reward_weight	1
control_cost_weight	0.5
contact_cost_weight	5e-4
healthy_reward	1.0	Per-step bonus while healthy
terminate_when_unhealthy	True
healthy_y_range	(0.2, 1.0)	Torso height band, in metres
contact_force_range	(-1.0, 1.0)	Per-component clipping range for each body's contact wrench (force and torque) before the cost
exclude_current_positions_from_observation	True	Omit x and z, keeping policies translation-invariant
include_contact_in_observation	True
use_rotation_vector	False
use_damping	True
use_gravity	True
use_low_friction	False
use_high_friction	False
init_dist_from_ground	0.55	m
init_ankle_angle	radians(57.30)	≈ 1.0 rad

Ant uses the plural field name exclude_current_positions_from_observation; HalfCheetah uses the singular form.

Observation — 81 elements (default config)

Key	Shape	Meaning
contact_forces	54	Six contact-wrench components (force and torque) for each of 9 bodies. Omitted when include_contact_in_observation=False
pose	13	num_dofs (14) - 2 for the excluded positions, +1 for the quaternion representation
vel	14	One per DOF

The table lists flattened order. Turning off exclude_current_positions_from_observation adds 2, turning off include_contact_in_observation removes 54, and setting use_rotation_vector=True removes 1.

Action — 8 elements

control, bounded [-1.0, 1.0]. Applied as external forces on DOFs 6–13 with a force scale of 150.

Reward — 4 terms

Term	Value
forward	x_velocity × forward_reward_weight
ctrl	-control_cost_weight × control·control
contact	-contact_cost_weight × ‖clipped contact-wrench vector‖²
survive	healthy_reward while healthy, else 0

The scalar reward sums the four terms directly; ctrl and contact are already negative.

Termination

Terminates with "Unhealthy" when the torso height leaves healthy_y_range, unless terminate_when_unhealthy=False. Truncates at steps_per_episode.

Scene identity

uid_fields = (use_damping, use_gravity, use_low_friction, use_high_friction).

HalfCheetah

superdex_gym/HalfCheetah-v0 · CLI half_cheetah · superdex.lab.gym.envs.benchmarks.halfcheetah_env.HalfCheetahEnv

HalfCheetah provides planar (2-D) running. Its reward favors forward velocity and penalizes control effort.

Configuration

Field	Default	Meaning
control_frequency	20	Hz
simulation_frequency	100	Hz — 5 substeps per control step
steps_per_episode	1000
reset_noise_scale	0.1
forward_reward_weight	1
control_cost_weight	0.1
exclude_current_position_from_observation	True	Omit the x-coordinate
use_gravity	True
use_rest_springs	True	Apply rest springs to the joints

Observation — 17 elements (default config)

Key	Shape	Meaning
pose	8	num_dofs (9) - 1 for the excluded x-coordinate
vel	9	One per DOF

There is no contact observation.

Action — 6 elements

control, bounded [-1.0, 1.0]. Applied as external forces on DOFs 3–8 with per-joint force scales [120, 90, 60, 120, 60, 30].

Reward — 2 terms

Term	Value
forward	x_velocity × forward_reward_weight
ctrl	-control_cost_weight × control·control

Termination

HalfCheetah never terminates; it only truncates

HalfCheetah does not override _check_stop_criteria. The base class only truncates at steps_per_episode, so terminated is never True.

Scene identity

uid_fields = (use_gravity, use_rest_springs).