Table of Contents

Class PusherEnvV5

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

Pusher-v5: a 7-joint arm that pushes a cylinder to a goal on a table, driven by 7 joint torques in [-2, 2]. The reward charges the cylinder's distance to the goal, half the fingertip's distance to the cylinder and the squared torques; the episode never ends on its own (make's 100-step limit truncates it). Byte for byte what Gymnasium's Pusher-v5 computes on MuJoCo 4.0.0 (DR-61, DR-64).

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

Remarks

Observation (float64, 23 values): the arm's 7 joint angles and velocities, then the positions of the fingertip, the cylinder and the goal. Reward: -|object - goal| * reward_dist_weight - sum(action**2) * reward_control_weight - |object - tips_arm| * reward_near_weight, the control term in the action's dtype. Info: reward_dist, reward_ctrl, reward_near; the reset's info is empty.

Footgun, as in Gymnasium: the reset writes the cylinder's and the goal's start into InitQpos itself (Gymnasium's qpos = self.init_qpos is no copy), so init_qpos's last four values change on every reset. The dynamics are unaffected: those four are overwritten before they are used.

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

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

Constructors

PusherEnvV5(PusherEnvV5Options)

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

public PusherEnvV5(PusherEnvV5Options options)

Parameters

options PusherEnvV5Options

The options.

Exceptions

ArgumentNullException

Thrown when options is null.

PusherEnvV5(RenderMode, string, int, IReadOnlyDictionary<string, object?>?, double, double, double, 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 PusherEnvV5(string, int, IReadOnlyDictionary<string, object?>?, double, double, double, string?, int, int, int?, string?, int, IReadOnlyDictionary<int, bool>?, EnvViewerFactory?) builds it from the mode's string: new PusherEnvV5(RenderMode.RgbArray) builds what new PusherEnvV5(renderMode: "rgb_array") builds, the member reaching the env as Gymnasium's string (Name(RenderMode)), which its RenderMode property then holds.

public PusherEnvV5(RenderMode renderMode, string xmlFile = "pusher_v5.xml", int frameSkip = 5, IReadOnlyDictionary<string, object?>? defaultCameraConfig = null, double rewardNearWeight = 0.5, double rewardDistWeight = 1, double rewardControlWeight = 0.1, 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); "pusher.xml" is v4's.

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 (trackbodyid -1, 4 m away), and an empty dictionary leaves MuJoCo's camera as it is.

rewardNearWeight double

The weight of the fingertip's distance to the cylinder (reward_near_weight).

rewardDistWeight double

The weight of the cylinder's distance to the goal (reward_dist_weight; Gymnasium's default is the int 1).

rewardControlWeight double

The weight of the squared torques (reward_control_weight).

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 PusherEnvV5() 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.

PusherEnvV5(string, int, IReadOnlyDictionary<string, object?>?, double, double, double, string?, int, int, int?, string?, int, IReadOnlyDictionary<int, bool>?, EnvViewerFactory?)

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

public PusherEnvV5(string xmlFile = "pusher_v5.xml", int frameSkip = 5, IReadOnlyDictionary<string, object?>? defaultCameraConfig = null, double rewardNearWeight = 0.5, double rewardDistWeight = 1, double rewardControlWeight = 0.1, 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); "pusher.xml" is v4's.

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 (trackbodyid -1, 4 m away), and an empty dictionary leaves MuJoCo's camera as it is.

rewardNearWeight double

The weight of the fingertip's distance to the cylinder (reward_near_weight).

rewardDistWeight double

The weight of the cylinder's distance to the goal (reward_dist_weight; Gymnasium's default is the int 1).

rewardControlWeight double

The weight of the squared torques (reward_control_weight).

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.

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

CylinderPos

The cylinder's start the last reset drew (cylinder_pos), float64 (2,), or null before the first reset. Owned by the env, replaced by each reset: do not dispose it.

[NDBorrowed]
public NDArray? CylinderPos { get; }

Property Value

NDArray

GoalPos

The goal the last reset set (goal_pos), the int64 [0, 0], or null before the first reset. Owned by the env, replaced by each reset: do not dispose it.

[NDBorrowed]
public NDArray? GoalPos { get; }

Property Value

NDArray

RewardControlWeight

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

[PyName("_reward_control_weight")]
public double RewardControlWeight { get; set; }

Property Value

double

RewardDistWeight

The weight of the cylinder's distance to the goal (_reward_dist_weight), read every step.

[PyName("_reward_dist_weight")]
public double RewardDistWeight { get; set; }

Property Value

double

RewardNearWeight

The weight of the fingertip's distance to the cylinder (_reward_near_weight), read every step.

[PyName("_reward_near_weight")]
public double RewardNearWeight { get; set; }

Property Value

double

Methods

Dispose(bool)

Closes, then releases the cylinder's and the goal's last arrays and everything MujocoEnv holds.

protected override void Dispose(bool disposing)

Parameters

disposing bool

true from Dispose().

ResetModel()

The episode's start (reset_model): the arm at init_qpos; the cylinder drawn as [uniform(-0.3, 0), uniform(-0.2, 0.2)] until it is farther than 0.17 from the goal at the origin; both written into init_qpos's last four values (see the class remarks); velocities init_qvel + uniform(-0.005, 0.005, nv) with the cylinder's and the goal's zeroed.

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 7 torques, float32 (the action space's samples) or any real dtype.

Returns

StepResult<NDArray>

The observation, the float64 reward, terminated=False, truncated=False and the info.

Exceptions

ArgumentNullException

action is null.

ValueError

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

NotSupportedException

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

KeyError

The model lacks one of the bodies object, tips_arm, goal (MuJoCo's message).