Table of Contents

Class PyMath

Namespace
Gym.Utils
Assembly
Gym.dll

Python's and NumPy's scalar arithmetic where it differs from C#'s (port plan §3.2 and §5.3, workstream F3): floor division and modulo that follow the divisor's sign, min/max whose NaN results depend on argument order, round with half-to-even and exact decimal rounding, and NumPy's clip and sign. Gym's env math calls these wherever Gymnasium's source uses the Python operator or function, so results match Gymnasium's bit for bit; the C# operator there would drift on negative operands, NaNs and ties.

public static class PyMath
Inheritance
PyMath
Inherited Members

Remarks

Python raises where C# would return a value: division or modulo by zero throws NumSharp's ZeroDivisionError with Python's message (DR-76), and an integer result Python could hold but long cannot (only long.MinValue // -1) throws .NET's OverflowException, like the checked arithmetic §3.2 asks for: that one is Gym.NET's limit, not a Python error.

The float operations reproduce CPython 3.12's floatobject.c operation for operation on top of the reference platform's C fmod (UCRT), including the sign of the NaN a non-finite dividend produces, so even the NaN bit patterns match. The live parity suite checks every member against the embedded interpreter.

Reference: Objects/floatobject.c and Python/bltinmodule.c (CPython 3.12), numpy/_core/src/umath/clip.cpp (NumPy 2.4.2).

Methods

Clip(double, double, double)

NumPy's np.clip(x, low, high) on float64 scalars: x raised to low, then lowered to high, where a tie keeps the value already held (clip(-0.0, 0.0, 1) is -0.0) and any NaN operand gives NaN. With low > high the result is high, as in NumPy.

public static double Clip(double x, double low, double high)

Parameters

x double

The value.

low double

The lower bound.

high double

The upper bound.

Returns

double

The clipped value.

Remarks

Matches NumPy 2.4.2 bit for bit, NaN payloads and signed zeros included, over every combination of {0, -0, 1, -1, 0.5, nan, inf, -inf}; the textbook min(max(x, low), high) does not (it turns clip(0.0, -0.0, 1) into -0.0). Reference: numpy/_core/src/umath/clip.cpp.

Clip(float, float, float)

NumPy's np.clip on float32 scalars: Clip(double, double, double) computed in float32, as NumPy keeps the dtype.

public static float Clip(float x, float low, float high)

Parameters

x float

The value.

low float

The lower bound.

high float

The upper bound.

Returns

float

The clipped value.

DivMod(double, double)

Python's divmod(a, b) for floats, CPython's float_divmod.

public static (double Quotient, double Remainder) DivMod(double a, double b)

Parameters

a double

The dividend.

b double

The divisor.

Returns

(double From, double To)

(a // b, a % b) as FloorDiv(double, double) and Mod(double, double) compute them.

Exceptions

ZeroDivisionError

Thrown when b is ±0: float divmod().

DivMod(long, long)

Python's divmod(a, b) for ints: (a // b, a % b) in one call.

public static (long Quotient, long Remainder) DivMod(long a, long b)

Parameters

a long

The dividend.

b long

The divisor.

Returns

(long Quotient, long Remainder)

The floored quotient and the divisor-signed remainder.

Exceptions

ZeroDivisionError

Thrown when b is 0: integer division or modulo by zero.

OverflowException

Thrown for divmod(long.MinValue, -1) (see FloorDiv(long, long)).

Float32(double)

np.float32(x): the float64 value rounded to the nearest float32, ties to even (IEEE), exactly C#'s (float)x. Spelled out so code that follows a Gymnasium source shows the cast that source makes, where the §3.2 rules allow no other narrowing.

public static float Float32(double x)

Parameters

x double

The float64 value.

Returns

float

The float32 value.

FloorDiv(double, double)

Python's a // b for floats, CPython's float_floor_div: the floored quotient computed from the exact remainder and snapped to the nearest integer, which is not always Math.Floor(a / b) (1 // 0.1 is 9.0, while 1 / 0.1 rounds to exactly 10).

public static double FloorDiv(double a, double b)

Parameters

a double

The dividend.

b double

The divisor.

Returns

double

The floored quotient; a zero result carries the sign of a / b.

Exceptions

ZeroDivisionError

Thrown when b is ±0: float floor division by zero.

FloorDiv(long, long)

Python's a // b for ints: the quotient rounded toward negative infinity (-7 // 2 == -4), where C#'s / truncates toward zero (-3).

public static long FloorDiv(long a, long b)

Parameters

a long

The dividend.

b long

The divisor.

Returns

long

The floored quotient.

Exceptions

ZeroDivisionError

Thrown when b is 0: integer division or modulo by zero.

OverflowException

Thrown for long.MinValue // -1, whose result 2^63 Python holds and long cannot.

Max<T>(IEnumerable<T>)

Python's max(iterable): the first item no later item compares greater than.

public static T Max<T>(IEnumerable<T> values) where T : IComparisonOperators<T, T, bool>

Parameters

values IEnumerable<T>

The items.

Returns

T

The maximum as Python picks it.

Type Parameters

T

A type with Python-like comparison operators.

Exceptions

ArgumentNullException

Thrown when values is null.

ValueError

Thrown for an empty sequence: max() iterable argument is empty.

Max<T>(T, T)

Python's max(a, b): b only when it compares greater than a, so the first argument wins ties and every comparison with NaN (max(nan, 1) is nan, max(1, nan) is 1; max(0.0, -0.0) is 0.0 and max(-0.0, 0.0) is -0.0).

public static T Max<T>(T a, T b) where T : IComparisonOperators<T, T, bool>

Parameters

a T

The first value.

b T

The second value.

Returns

T

The maximum as Python picks it.

Type Parameters

T

A type with Python-like comparison operators (every .NET number).

Min<T>(IEnumerable<T>)

Python's min(iterable): the first item no later item compares less than, scanning left to right with < as Min<T>(T, T) does.

public static T Min<T>(IEnumerable<T> values) where T : IComparisonOperators<T, T, bool>

Parameters

values IEnumerable<T>

The items.

Returns

T

The minimum as Python picks it.

Type Parameters

T

A type with Python-like comparison operators.

Exceptions

ArgumentNullException

Thrown when values is null.

ValueError

Thrown for an empty sequence: min() iterable argument is empty.

Min<T>(T, T)

Python's min(a, b): b only when it compares less than a, so the first argument wins ties and every comparison with NaN (min(nan, 1) is nan, min(1, nan) is 1). Min(double, double) returns NaN for both.

public static T Min<T>(T a, T b) where T : IComparisonOperators<T, T, bool>

Parameters

a T

The first value.

b T

The second value.

Returns

T

The minimum as Python picks it.

Type Parameters

T

A type with Python-like comparison operators (every .NET number).

Mod(double, double)

Python's a % b for floats, CPython's float_rem: C's fmod moved into the divisor's sign (-7.5 % 2 == 0.5, -5.0 % inf == inf); a zero result is a zero of the divisor's sign.

public static double Mod(double a, double b)

Parameters

a double

The dividend.

b double

The divisor.

Returns

double

The remainder.

Exceptions

ZeroDivisionError

Thrown when b is ±0: float modulo (Python 3.12's message).

Mod(long, long)

Python's a % b for ints: the remainder takes the divisor's sign (-7 % 2 == 1), where C#'s % takes the dividend's (-1).

public static long Mod(long a, long b)

Parameters

a long

The dividend.

b long

The divisor.

Returns

long

The remainder, in [0, b) for a positive divisor and (b, 0] for a negative one.

Exceptions

ZeroDivisionError

Thrown when b is 0: integer modulo by zero.

Round(double)

Python's round(x) with no digits: the nearest integer, ties to even (round(0.5) == 0, round(1.5) == 2), as an unbounded integer.

public static BigInteger Round(double x)

Parameters

x double

The value.

Returns

BigInteger

The rounded integer.

Remarks

CPython rounds half away from zero with C's round and fixes exact halves to even; .NET's exact Round(double, MidpointRounding) with ToEven is the same function.

Exceptions

ValueError

Thrown for NaN: cannot convert float NaN to integer.

OverflowError

Thrown, as Python's OverflowError, for an infinity: cannot convert float infinity to integer.

Round(double, int)

Python's round(x, ndigits): x rounded to ndigits decimal places (tens, hundreds, ... when negative) by its exact binary value, ties to even, then converted back to the nearest double. So round(2.675, 2) is 2.67: the double closest to 2.675 lies below it. Round(double, int, MidpointRounding) scales by a power of ten first and can differ.

public static double Round(double x, int ndigits)

Parameters

x double

The value.

ndigits int

The number of decimal places; negative rounds to the left of the point.

Returns

double

The rounded value; NaN and the infinities are returned as they are, and a zero keeps x's sign.

Remarks

CPython 3.12's float___round___impl and double_round round to a decimal string with _Py_dg_dtoa mode 3 and parse it back with _Py_dg_strtod; here the decimal rounding is exact BigInteger arithmetic and the parse is .NET's correctly rounded Parse(string, NumberStyles, IFormatProvider), which reach the same double. Reference: Objects/floatobject.c.

Exceptions

OverflowError

Thrown, as Python's OverflowError, when the rounded value exceeds the double range: rounded value too large to represent (round(1.7976931348623157e308, -308)).

Sign(double)

NumPy's np.sign on a float64 scalar: 1.0 for a positive value, -1.0 for a negative one, 0.0 (positive, also for -0.0) for a zero, and a NaN returned as it is. Sign(double) throws for NaN instead.

public static double Sign(double x)

Parameters

x double

The value.

Returns

double

The sign.

Sign(long)

NumPy's np.sign on an integer: -1, 0 or 1.

public static long Sign(long x)

Parameters

x long

The value.

Returns

long

The sign.

Sign(float)

NumPy's np.sign on a float32 scalar, in float32 (see Sign(double)).

public static float Sign(float x)

Parameters

x float

The value.

Returns

float

The sign.