Class PyMath
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
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
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
Returns
- (double From, double To)
(a // b, a % b)as FloorDiv(double, double) and Mod(double, double) compute them.
Exceptions
- ZeroDivisionError
Thrown when
bis ±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
Returns
Exceptions
- ZeroDivisionError
Thrown when
bis 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
xdoubleThe 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
Returns
- double
The floored quotient; a zero result carries the sign of
a / b.
Exceptions
- ZeroDivisionError
Thrown when
bis ±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
Returns
- long
The floored quotient.
Exceptions
- ZeroDivisionError
Thrown when
bis 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
valuesIEnumerable<T>The items.
Returns
- T
The maximum as Python picks it.
Type Parameters
TA type with Python-like comparison operators.
Exceptions
- ArgumentNullException
Thrown when
valuesis 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
aTThe first value.
bTThe second value.
Returns
- T
The maximum as Python picks it.
Type Parameters
TA 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
valuesIEnumerable<T>The items.
Returns
- T
The minimum as Python picks it.
Type Parameters
TA type with Python-like comparison operators.
Exceptions
- ArgumentNullException
Thrown when
valuesis 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
aTThe first value.
bTThe second value.
Returns
- T
The minimum as Python picks it.
Type Parameters
TA 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
Returns
- double
The remainder.
Exceptions
- ZeroDivisionError
Thrown when
bis ±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
Returns
- long
The remainder, in
[0, b)for a positive divisor and(b, 0]for a negative one.
Exceptions
- ZeroDivisionError
Thrown when
bis 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
xdoubleThe 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
xdoubleThe value.
ndigitsintThe 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
xdoubleThe 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
xlongThe 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
xfloatThe value.
Returns
- float
The sign.