Table of Contents

Class HopperEnvV5

Namespace
Gym.Environments.Envs.MuJoCo
Assembly
Gym.Environments.dll

Hopper-v5: a planar one-legged hopper (torso, thigh, leg, foot) driven by 3 joint torques in [-1, 1]. The reward pays the forward velocity and staying healthy, and charges the squared torques; an unhealthy state (too low, too tilted, or any coordinate beyond ±100) ends the episode. Byte for byte what Gymnasium's Hopper-v5 computes on MuJoCo 4.0.0 (DR-61, DR-64).

[PyName("HopperEnv")]
public class HopperEnvV5 : MujocoEnv, IEnv, IDisposable, IDynamicAttributes
Inheritance
HopperEnvV5
Implements
Inherited Members
Extension Methods

Remarks

Observation (float64): the positions without the root's x (unless asked for), then the velocities clipped to ±10, 11 values by default. Reward: forward_reward_weight * x_velocity + healthy_reward * is_healthy - ctrl_cost_weight * sum(action**2); v5 pays the healthy reward only while healthy (a Python float in the info, as Gymnasium's bool * float gives). Info: x_position, z_distance_from_origin, x_velocity, reward_forward, reward_ctrl, reward_survive; the reset's info holds the first two.

Not thread-safe. Reference: gymnasium/envs/mujoco/hopper_v5.py.

Its info reads typed (DR-91): HopperInfoV5 info = step.Info; (HopperInfoV5), with the dict's own values still behind the indexer.

Constructors

HopperEnvV5(HopperEnvV5Options)

Builds the instance from its options record: the properties set, the constructor's defaults for the rest.

public HopperEnvV5(HopperEnvV5Options options)

Parameters

options HopperEnvV5Options

The options.

Exceptions

ArgumentNullException

Thrown when options is null.

HopperEnvV5(RenderMode, string, int, IReadOnlyDictionary<string, object?>?, double, double, double, bool, (double Low, double High)?, (double Low, double High)?, (double Low, double High)?, double, bool, int, int, int?, string?, int, IReadOnlyDictionary<int, bool>?, EnvViewerFactory?)

Builds the env with the render mode given as the RenderMode enum (DR-84, DR-93), as HopperEnvV5(string, int, IReadOnlyDictionary<string, object?>?, double, double, double, bool, (double Low, double High)?, (double Low, double High)?, (double Low, double High)?, double, bool, string?, int, int, int?, string?, int, IReadOnlyDictionary<int, bool>?, EnvViewerFactory?) builds it from the mode's string: new HopperEnvV5(RenderMode.RgbArray) builds what new HopperEnvV5(renderMode: "rgb_array") builds, the member reaching the env as Gymnasium's string (Name(RenderMode)), which its RenderMode property then holds.

public HopperEnvV5(RenderMode renderMode, string xmlFile = "hopper.xml", int frameSkip = 4, IReadOnlyDictionary<string, object?>? defaultCameraConfig = null, double forwardRewardWeight = 1, double ctrlCostWeight = 0.001, double healthyReward = 1, bool terminateWhenUnhealthy = true, (double Low, double High)? healthyStateRange = null, (double Low, double High)? healthyZRange = null, (double Low, double High)? healthyAngleRange = null, double resetNoiseScale = 0.005, bool excludeCurrentPositionsFromObservation = true, int width = 480, int height = 480, int? cameraId = null, string? cameraName = null, int maxGeom = 1000, IReadOnlyDictionary<int, bool>? visualOptions = null, EnvViewerFactory? viewerFactory = null)

Parameters

renderMode RenderMode

The render mode, which the env must list in its metadata["render_modes"] as for the string; it behaves exactly as its Gymnasium string does in the other constructor.

xmlFile string

The model: a bundled file name (xml_file, DR-63).

frameSkip int

Physics steps per env step (frame_skip).

defaultCameraConfig IReadOnlyDictionary<string, object>

The free camera's settings (default_camera_config); null is Gymnasium's default (tracking body 2 from 3 m, looking at (0, 0, 1.15), 20° from above), and an empty dictionary leaves MuJoCo's camera as it is.

forwardRewardWeight double

The weight of the forward velocity (forward_reward_weight).

ctrlCostWeight double

The weight of the squared torques (ctrl_cost_weight).

healthyReward double

The reward for each healthy step (healthy_reward).

terminateWhenUnhealthy bool

Whether an unhealthy state ends the episode (terminate_when_unhealthy).

healthyStateRange (double hx, double hy)?

The exclusive range every coordinate but the root's x and z must stay in (healthy_state_range); null is Gymnasium's (-100, 100).

healthyZRange (double hx, double hy)?

The exclusive range of a healthy height (healthy_z_range); null is (0.7, inf).

healthyAngleRange (double hx, double hy)?

The exclusive range of a healthy torso angle (healthy_angle_range); null is (-0.2, 0.2).

resetNoiseScale double

The scale of the reset's noise (reset_noise_scale).

excludeCurrentPositionsFromObservation bool

Whether the root's x leaves the observation (exclude_current_positions_from_observation).

width int

The rendered frame's width (width).

height int

The rendered frame's height (height).

cameraId int?

The camera to render from (camera_id).

cameraName string

The camera to render from by name (camera_name).

maxGeom int

The most geoms a frame draws (max_geom).

visualOptions IReadOnlyDictionary<int, bool>

MuJoCo visual flags to switch (visual_options).

viewerFactory EnvViewerFactory

Gym.NET's viewer_factory (DR-20) for human mode.

Remarks

The mode is required and comes first, so new HopperEnvV5() keeps meaning the other constructor, without a mode; leave the mode out there for no rendering. Every other parameter means what it means there.

Exceptions

ArgumentOutOfRangeException

Thrown for a value RenderMode does not declare (a cast integer such as (RenderMode)99).

NotSupportedException

xmlFile is not a bundled model.

OverflowError

A frame skip of 0 (Python's OverflowError deriving the frame rate).

ValueError

Both a camera id and a camera name.

HopperEnvV5(string, int, IReadOnlyDictionary<string, object?>?, double, double, double, bool, (double Low, double High)?, (double Low, double High)?, (double Low, double High)?, double, bool, string?, int, int, int?, string?, int, IReadOnlyDictionary<int, bool>?, EnvViewerFactory?)

Creates the env (Gymnasium's HopperEnv.init): the model, its spaces and the frame rate the time step gives.

public HopperEnvV5(string xmlFile = "hopper.xml", int frameSkip = 4, IReadOnlyDictionary<string, object?>? defaultCameraConfig = null, double forwardRewardWeight = 1, double ctrlCostWeight = 0.001, double healthyReward = 1, bool terminateWhenUnhealthy = true, (double Low, double High)? healthyStateRange = null, (double Low, double High)? healthyZRange = null, (double Low, double High)? healthyAngleRange = null, double resetNoiseScale = 0.005, bool excludeCurrentPositionsFromObservation = true, string? renderMode = null, int width = 480, int height = 480, int? cameraId = null, string? cameraName = null, int maxGeom = 1000, IReadOnlyDictionary<int, bool>? visualOptions = null, EnvViewerFactory? viewerFactory = null)

Parameters

xmlFile string

The model: a bundled file name (xml_file, DR-63).

frameSkip int

Physics steps per env step (frame_skip).

defaultCameraConfig IReadOnlyDictionary<string, object>

The free camera's settings (default_camera_config); null is Gymnasium's default (tracking body 2 from 3 m, looking at (0, 0, 1.15), 20° from above), and an empty dictionary leaves MuJoCo's camera as it is.

forwardRewardWeight double

The weight of the forward velocity (forward_reward_weight).

ctrlCostWeight double

The weight of the squared torques (ctrl_cost_weight).

healthyReward double

The reward for each healthy step (healthy_reward).

terminateWhenUnhealthy bool

Whether an unhealthy state ends the episode (terminate_when_unhealthy).

healthyStateRange (double hx, double hy)?

The exclusive range every coordinate but the root's x and z must stay in (healthy_state_range); null is Gymnasium's (-100, 100).

healthyZRange (double hx, double hy)?

The exclusive range of a healthy height (healthy_z_range); null is (0.7, inf).

healthyAngleRange (double hx, double hy)?

The exclusive range of a healthy torso angle (healthy_angle_range); null is (-0.2, 0.2).

resetNoiseScale double

The scale of the reset's noise (reset_noise_scale).

excludeCurrentPositionsFromObservation bool

Whether the root's x leaves the observation (exclude_current_positions_from_observation).

renderMode string

Gymnasium's render_mode: human, rgb_array, depth_array, rgbd_tuple or null.

width int

The rendered frame's width (width).

height int

The rendered frame's height (height).

cameraId int?

The camera to render from (camera_id).

cameraName string

The camera to render from by name (camera_name).

maxGeom int

The most geoms a frame draws (max_geom).

visualOptions IReadOnlyDictionary<int, bool>

MuJoCo visual flags to switch (visual_options).

viewerFactory EnvViewerFactory

Gym.NET's viewer_factory (DR-20) for human mode.

Remarks

The ranges are tuples in C#, so Python's None (which Gymnasium fails on when it unpacks it) has no counterpart: null stands for the default.

Exceptions

NotSupportedException

xmlFile is not a bundled model.

OverflowError

A frame skip of 0 (Python's OverflowError deriving the frame rate).

ValueError

Both a camera id and a camera name.

Properties

ClassMetadata

Gymnasium's class attribute metadata: the four render modes, the frame rate set per instance. A new dict on every read.

public static Metadata ClassMetadata { get; }

Property Value

Metadata

CtrlCostWeight

The weight of the squared torques (_ctrl_cost_weight), read every step.

[PyName("_ctrl_cost_weight")]
public double CtrlCostWeight { get; set; }

Property Value

double

ExcludeCurrentPositionsFromObservation

Whether the root's x leaves the observation (_exclude_current_positions_from_observation). Footgun: changing it after construction changes the observation's length but not the observation space, as in Gymnasium.

[PyName("_exclude_current_positions_from_observation")]
public bool ExcludeCurrentPositionsFromObservation { get; set; }

Property Value

bool

ForwardRewardWeight

The weight of the forward velocity (_forward_reward_weight), read every step.

[PyName("_forward_reward_weight")]
public double ForwardRewardWeight { get; set; }

Property Value

double

HealthyAngleRange

The exclusive range of a healthy torso angle (_healthy_angle_range).

[PyName("_healthy_angle_range")]
public (double Low, double High) HealthyAngleRange { get; set; }

Property Value

(double From, double To)

HealthyReward

The healthy reward now (healthy_reward): is_healthy * _healthy_reward, a Python float.

[PyName("healthy_reward")]
public double HealthyReward { get; }

Property Value

double

HealthyRewardWeight

The reward for each healthy step (_healthy_reward), read every step.

[PyName("_healthy_reward")]
public double HealthyRewardWeight { get; set; }

Property Value

double

HealthyStateRange

The exclusive range of every coordinate but the root's x and z (_healthy_state_range).

[PyName("_healthy_state_range")]
public (double Low, double High) HealthyStateRange { get; set; }

Property Value

(double From, double To)

HealthyZRange

The exclusive range of a healthy height (_healthy_z_range).

[PyName("_healthy_z_range")]
public (double Low, double High) HealthyZRange { get; set; }

Property Value

(double From, double To)

IsHealthy

Whether the hopper is healthy now (is_healthy): every coordinate but the root's x and z inside the state range, the height inside the z range and the torso angle inside the angle range, all exclusive (a NaN is unhealthy).

[PyName("is_healthy")]
public bool IsHealthy { get; }

Property Value

bool

ObservationStructure

How the observation is laid out (observation_structure): skipped_qpos, qpos and qvel counts.

public Info ObservationStructure { get; }

Property Value

Info

ResetNoiseScale

The scale of the reset's noise (_reset_noise_scale), read every reset.

[PyName("_reset_noise_scale")]
public double ResetNoiseScale { get; set; }

Property Value

double

TerminateWhenUnhealthy

Whether an unhealthy state ends the episode (_terminate_when_unhealthy), read every step.

[PyName("_terminate_when_unhealthy")]
public bool TerminateWhenUnhealthy { get; set; }

Property Value

bool

Methods

ControlCost(NDArray)

The control cost of action (control_cost): ctrl_cost_weight * sum(action**2), computed in the action's dtype and returned widened exactly.

[PyName("control_cost")]
public double ControlCost(NDArray action)

Parameters

action NDArray

The action.

Returns

double

The cost.

Exceptions

ArgumentNullException

action is null.

NotSupportedException

An action of a dtype whose cost NumPy keeps in that dtype (float16, complex).

GetResetInfo()

The reset's info (_get_reset_info): x_position and z_distance_from_origin, np.float64s.

protected override Info GetResetInfo()

Returns

Info

The info.

ResetModel()

The episode's start (reset_model): positions init_qpos + uniform(-scale, scale, nq), then velocities init_qvel + uniform(-scale, scale, nv), drawn in that order.

protected override NDArray ResetModel()

Returns

NDArray

The first observation.

Step(NDArray)

Applies action for FrameSkip physics steps and reports the transition (step).

public override StepResult<NDArray> Step(NDArray action)

Parameters

action NDArray

The 3 torques, float32 (the action space's samples) or any real dtype.

Returns

StepResult<NDArray>

The observation, the float64 reward, whether an unhealthy state ended the episode, truncated=False and the info.

Exceptions

ArgumentNullException

action is null.

ValueError

The action is not of shape (3,), with Gymnasium's message.

NotSupportedException

An action of a dtype whose cost NumPy keeps in that dtype (float16, complex).