Table of Contents

Class PendulumEnv

Namespace
Gym.Environments.Envs.Classic
Assembly
Gym.Environments.dll

Pendulum-v1: a pendulum hanging from a pivot, swung up and balanced by a torque in [-2, 2]. The reward is the negative cost θ² + 0.1·θ̇² + 0.001·u² (θ normalized to [-π, π)), so it is at most 0, reached upright and at rest; the env never terminates. Byte for byte what Gymnasium's Pendulum computes, errors included.

public class PendulumEnv : Env<NDArray, NDArray>, IEnv, IDisposable, IDynamicAttributes
Inheritance
PendulumEnv
Implements
Inherited Members
Extension Methods

Remarks

The torque keeps the action's precision, as NumPy's scalar does: a float32 action (the action space's dtype) is clipped, squared and scaled in float32 before it joins the float64 dynamics, a float64 one in float64, and an integer or boolean one is clipped as float64 (NumPy's clip with Python-float bounds). The state is float64 [θ, θ̇] throughout; the observation is the float32 [cos θ, sin θ, θ̇].

Rendering is Gymnasium's pixel for pixel: the rod, its joints, and the clockwise arrow image (embedded from Gymnasium, DR-19) shrunk with Smoothscale(Surface, int, int) to the last torque's size and mirrored by its sign. Any render mode other than "human" returns the frame, as Gymnasium's else branch does. Human mode renders into the window from viewer_factory or Gymnasium.HumanViewerFactory (DR-20) at 30 frames per second.

Not thread-safe. Reference: gymnasium/envs/classic_control/pendulum.py.

Its info is always {}, as Gymnasium's, so it has no typed info record (DR-95).

Constructors

PendulumEnv(PendulumEnvOptions)

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

public PendulumEnv(PendulumEnvOptions options)

Parameters

options PendulumEnvOptions

The options.

Exceptions

ArgumentNullException

Thrown when options is null.

PendulumEnv(RenderMode, double, EnvViewerFactory?)

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

public PendulumEnv(RenderMode renderMode, double g = 10, 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.

g double

Gymnasium's g: the gravitational acceleration, 10.0 by default (Gravity).

viewerFactory EnvViewerFactory

Gym.NET's viewer_factory (DR-20) for human mode; null uses Gymnasium.HumanViewerFactory.

Remarks

The mode is required and comes first, so new PendulumEnv() 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).

PendulumEnv(string?, double, EnvViewerFactory?)

Creates the env.

public PendulumEnv(string? renderMode = null, double g = 10, EnvViewerFactory? viewerFactory = null)

Parameters

renderMode string

Gymnasium's render_mode: null, "human" or "rgb_array"; not validated, as in Gymnasium (make checks it against the metadata).

g double

Gymnasium's g: the gravitational acceleration, 10.0 by default (Gravity).

viewerFactory EnvViewerFactory

Gym.NET's viewer_factory (DR-20) for human mode; null uses Gymnasium.HumanViewerFactory.

Properties

ClassMetadata

Gymnasium's class attribute metadata: {"render_modes": ["human", "rgb_array"], "render_fps": 30}. Every env starts with a copy as its instance metadata.

public static Metadata ClassMetadata { get; }

Property Value

Metadata

Remarks

A new dict on every read, so editing one env's metadata never reaches another (Python's is one shared dict).

Clock

Gymnasium's clock: paces human rendering, null until the first render.

public Clock? Clock { get; }

Property Value

Clock

Dt

Gymnasium's dt, 0.05 s per step.

public double Dt { get; set; }

Property Value

double

Gravity

Gymnasium's g: the gravitational acceleration, from the constructor.

[PyName("g")]
public double Gravity { get; set; }

Property Value

double

IsOpen

Gymnasium's isopen: true until Close() shuts a render window down.

[PyName("isopen")]
public bool IsOpen { get; set; }

Property Value

bool

LastU

Gymnasium's last_u: the last step's clipped torque, which the next render draws as the arrow; null after a reset (no arrow) and before the first one. Assigning a value draws that torque's arrow as a float64.

[PyName("last_u")]
public double? LastU { get; set; }

Property Value

double?

Remarks

Python's attribute is missing until the first reset or step, so a render of an env whose state was injected before any reset raises AttributeError; reading it here gives null then.

Length

Gymnasium's l, 1.0: the rod's length.

[PyName("l")]
public double Length { get; set; }

Property Value

double

Mass

Gymnasium's m, 1.0: the pendulum's mass.

[PyName("m")]
public double Mass { get; set; }

Property Value

double

MaxSpeed

Gymnasium's max_speed, 8: the clamp of the angular velocity, read every step.

public double MaxSpeed { get; set; }

Property Value

double

MaxTorque

Gymnasium's max_torque, 2.0: the clamp of the torque, read every step (the action space keeps its construction-time bounds).

public double MaxTorque { get; set; }

Property Value

double

Screen

Gymnasium's screen: the surface every frame is blitted onto, null until the first render. Close() keeps it, as Python's close does.

public Surface? Screen { get; }

Property Value

Surface

ScreenDim

Gymnasium's screen_dim, 500: the frame's width and height in pixels, read when a frame is rendered.

public int ScreenDim { get; set; }

Property Value

int

State

Gymnasium's state, the float64 [θ, θ̇]: a new array on every read, or null before the first reset (and after null was assigned). Assigning injects a state, as env.state = np.array([...]) does, of any length: the next step or render checks it with Python's errors.

public double[]? State { get; set; }

Property Value

double[]

Remarks

Assigning null stands for Python's None: the next step or render raises the TypeError Python raises for it.

Surf

Gymnasium's surf: the last frame drawn before it was blitted onto Screen, or null.

public Surface? Surf { get; }

Property Value

Surface

Methods

AngleNormalize(double)

Gymnasium's module function angle_normalize: ((x + π) % 2π) - π, the angle in [-π, π) with NumPy's float remainder (the divisor's sign).

public static double AngleNormalize(double x)

Parameters

x double

The angle.

Returns

double

The normalized angle; NaN for a NaN or infinite one.

Remarks

Close()

Once something was rendered, shuts the human-mode window down and marks the env closed (IsOpen). Like Gymnasium's, it keeps Screen, so a later render reuses it.

public override void Close()

Remarks

Render()

Draws Gymnasium's frame with the same primitives in the same order: the rod rotated by θ + π/2, its two round ends, the torque arrow when there is one, and the axle, in a y-up world flipped at the end.

public override RenderResult Render()

Returns

RenderResult

For any mode but human: the (500, 500, 3) uint8 frame, a new array the caller owns (Gymnasium's render returns it from its else branch). human: nothing.

Remarks

The arrow's size is float(scale * np.abs(last_u) / 2), computed in the torque's precision and truncated as pygame's C code truncates it (CInt(double)). Reference: gymnasium/envs/classic_control/pendulum.py.

Exceptions

AssertionError

Thrown without a render mode when the env has no spec (assert self.spec is not None).

AttributeError

Thrown before the first reset (no state), and for an injected state before any reset or step (no last_u, after the rod was drawn), as in Gymnasium.

TypeError

Thrown when State was assigned null.

IndexError

Thrown when an assigned state is empty.

KeyError

Thrown in human mode when metadata["render_fps"] was removed.

ValueError

Thrown for a NaN coordinate (a NaN state), with pygame's message, and for an arrow of no valid size (a NaN LastU: Cannot scale to negative size).

OverflowError

Thrown, as pygame's OverflowError, for a coordinate pygame cannot draw.

NotSupportedException

Thrown when a torque beyond the image's size (a raised MaxTorque) would make smoothscale grow the arrow, which Gym.NET does not implement yet (P7).

DependencyNotInstalled

Thrown on the first human render when no viewer factory is set (DR-20).

Reset(BigInteger?, IReadOnlyDictionary<string, object?>?)

Starts an episode: reseeds the generator when a seed is given, then draws [θ, θ̇] from uniform(-high, high) with high = [π, 1.0], or [x_init, y_init] from the options, and clears the arrow. Renders in human mode.

public override ResetResult<NDArray> Reset(BigInteger? seed = null, IReadOnlyDictionary<string, object?>? options = null)

Parameters

seed BigInteger?

The seed of a fresh Generator(PCG64(SeedSequence(seed))), or null to keep the generator.

options IReadOnlyDictionary<string, object>

Gymnasium's reset options: "x_init" and "y_init", anything Python's float() accepts; a missing key keeps its default. Custom bounds can put the state outside the observation space, as in Gymnasium.

Returns

ResetResult<NDArray>

The float32 observation [cos θ, sin θ, θ̇] and an empty info.

Remarks

The seed is applied before the options are read, as super().reset(seed=seed) runs first; a failed reset leaves the freshly seeded generator, undrawn, and the old state. Reference: gymnasium/envs/classic_control/pendulum.py.

Exceptions

Error

Thrown for a negative seed, with Gymnasium's message.

ValueError

Thrown for an option float() rejects (An option (None) could not be converted to a float.), and by the generator for a negative bound (high - low < 0).

OverflowError

Thrown, as Python's OverflowError, for a NaN or infinite bound (Range exceeds valid bounds).

DependencyNotInstalled

Thrown in human mode by the first render when no viewer factory is set (DR-20).

Step(NDArray)

Applies the clipped torque for Dt seconds: θ̇ += (3g/(2l)·sin θ + 3/(m·l²)·u)·dt, clipped to ±MaxSpeed, then θ += θ̇·dt. Renders in human mode.

public override StepResult<NDArray> Step(NDArray action)

Parameters

action NDArray

A one-dimensional array whose first element is the torque, clipped to ±MaxTorque in the array's precision (float32 for the action space's samples). Read, never kept.

Returns

StepResult<NDArray>

The float32 observation, the reward -cost (float64, never positive), terminated=False, truncated=False and {}.

Remarks

The state is read before the action, as the source unpacks it first. Every x ** 2 is the C runtime's pow (powf for a float32 torque), as NumPy computes it, never x * x. Reference: gymnasium/envs/classic_control/pendulum.py.

Exceptions

AttributeError

Thrown before the first reset ('PendulumEnv' object has no attribute 'state').

TypeError

Thrown when State was assigned null (cannot unpack non-iterable NoneType object).

ValueError

Thrown when an assigned state does not hold exactly two values (Python's unpacking error).

IndexError

Thrown for a 0-d action (invalid index to scalar variable., as np.clip returns a scalar for it) or an empty one, with NumPy's messages.

NotSupportedException

Thrown for an action Gym.NET does not model: more than one dimension, or a float16 or complex dtype.

ZeroDivisionError

Thrown, as Python's ZeroDivisionError, when Length or Mass was set to zero (float division by zero).

DependencyNotInstalled

Thrown in human mode by the first render when no viewer factory is set (DR-20).