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
optionsPendulumEnvOptionsThe options.
Exceptions
- ArgumentNullException
Thrown when
optionsis 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
renderModeRenderModeThe 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.gdoubleGymnasium's
g: the gravitational acceleration, 10.0 by default (Gravity).viewerFactoryEnvViewerFactoryGym.NET's
viewer_factory(DR-20) for human mode; null usesGymnasium.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
renderModestringGymnasium's
render_mode: null,"human"or"rgb_array"; not validated, as in Gymnasium (makechecks it against the metadata).gdoubleGymnasium's
g: the gravitational acceleration, 10.0 by default (Gravity).viewerFactoryEnvViewerFactoryGym.NET's
viewer_factory(DR-20) for human mode; null usesGymnasium.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
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
Dt
Gymnasium's dt, 0.05 s per step.
public double Dt { get; set; }
Property Value
Gravity
Gymnasium's g: the gravitational acceleration, from the constructor.
[PyName("g")]
public double Gravity { get; set; }
Property Value
IsOpen
[PyName("isopen")]
public bool IsOpen { get; set; }
Property Value
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
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
Mass
Gymnasium's m, 1.0: the pendulum's mass.
[PyName("m")]
public double Mass { get; set; }
Property Value
MaxSpeed
Gymnasium's max_speed, 8: the clamp of the angular velocity, read every step.
public double MaxSpeed { get; set; }
Property Value
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
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
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
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
public Surface? Surf { get; }
Property Value
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
xdoubleThe angle.
Returns
- double
The normalized angle; NaN for a NaN or infinite one.
Remarks
Reference: gymnasium/envs/classic_control/pendulum.py.
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
Reference: gymnasium/envs/classic_control/pendulum.py.
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 itselsebranch).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 (nolast_u, after the rod was drawn), as in Gymnasium.- TypeError
- 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
seedBigInteger?The seed of a fresh
Generator(PCG64(SeedSequence(seed))), or null to keep the generator.optionsIReadOnlyDictionary<string, object>Gymnasium's reset options:
"x_init"and"y_init", anything Python'sfloat()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
actionNDArrayA 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=Falseand{}.
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., asnp.clipreturns 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).