Table of Contents

Class PolyUtilsModule

Namespace
NumSharp
Assembly
NumSharp.dll

numpy.polynomial.polyutils — the helpers the six basis modules are built on, reachable as np.polynomial.polyutils: series normalization (as_series(object, bool), trimseq(NDArray), trimcoef(object, double)), the linear domain maps (getdomain(object), mapparms(object, object), mapdomain(NDArray, object, object)) and the coefficient formatter of the series classes (format_float(object, bool)).

[ModuleName("np.polynomial.polyutils")]
public class PolyUtilsModule
Inheritance
PolyUtilsModule
Inherited Members

Remarks

Every function reproduces NumPy 2.4.2 bit for bit, including which ARITHMETIC runs: NumPy never converts a domain, it indexes it, so a domain given as Python numbers is computed by CPython (exact ints; a zero-length domain raises DivideByZeroException, Python's ZeroDivisionError), and one given as an array by NumPy's scalar math (a zero-length domain yields inf/nan). In C#: an NDArray or a TYPED array (double[], float[], Complex[], …) is an ndarray; an object[] / IList is a Python list and a ValueTuple a Python tuple of Python numbers (a C# bool / integer / float / double / Complex is a Python number; Half, char and decimal are NumPy scalars of their dtype).

format_float(object, bool) prints with NumPy's Dragon4, ported (the code behind format_float_positional(object, int?, bool, bool, string, bool, int?, int?, int?) and format_float_scientific(object, int?, bool, string, bool, int?, int?, int?)).

https://numpy.org/doc/stable/reference/routines.polynomials.polyutils.html

Methods

as_series(object, bool)

Returns every item of alist as a 1-D coefficient array, all of one dtype — np.common_type of the items (every integer becomes float64; float16/float32/float64/complex128 are kept) — each a FRESH copy, with trailing zeros removed first when trim.

public NDArray[] as_series(object alist, bool trim = true)

Parameters

alist object

The coefficient sequences: an NDArray (a 1-D array yields one single-coefficient series per element, a 2-D array one series per row), or any C# collection of coefficient arrays / numbers.

trim bool

Remove trailing zeros from each series (NumPy's default: true).

Returns

NDArray[]

The series, in order (an empty collection yields an empty array).

Remarks

Exceptions

TypeError

alist is not iterable (null, a number, a 0-d array).

ValueError

A series is empty (Coefficient array is empty) or not 1-d (Coefficient array is not 1-d), or the series have no common type — bool or str series (Coefficient arrays have no common type; NumPy's object-array fallback does not exist here).

NotSupportedException

A null item or a Python int beyond uint64 (NumPy would build an object array).

format_float(object, bool)

Formats one coefficient the way the series classes print it (NumPy's numpy.polynomial.polyutils.format_float): under the current print options (printoptions(int?, int?, int?, int?, bool?, string, string, char?, string)), positional with the shortest digits cut at precision and one zero kept after the point ('0.1', '2.0', '123456.12345679'), scientific from 1e8 up or below 10**min(0, -(precision - 1) // 2) — 1e-4 at the default precision 8 ('1.0e-05').

public string format_float(object x, bool parens = false)

Parameters

x object

The value. A double is np.float64 / a Python float, a float np.float32 (float32's digits: 0.1f is '0.1' at every precision), a Half np.float16, a decimal NumSharp's floating decimal (printed as its float64). Anything that is not floating prints as Python's str() of the object it stands for: '3' (a C# integer, or a char: np.uint16), 'True', 'None', '(1+2j)', the text itself, '[1.5]' for a list, an array's str() — a 0-d array too, since NumPy's test reads type(x), which is ndarray there ('0.30000000000000004').

parens bool

Wrap a scientific result in parentheses ('(1.0e-05)'); a positional or special result is never wrapped.

Returns

string

The text: nanstr / infstr for NaN and either infinity (an infinity's sign is NOT printed, as in NumPy: -inf gives 'inf'); with floatmode='fixed' exactly precision digits ('0.10000000'); a leading '+' with sign='+' (sign=' ' changes nothing).

Remarks

NumPy's statements (FormatFloat(object, bool)): the thresholds are Python literals, so they compare in the value's own dtype (a float16 sees 1e8 as infinity); the digits are NumPy's Dragon4, ported. https://github.com/numpy/numpy/blob/v2.5.4/numpy/polynomial/polyutils.py

Exceptions

RuntimeError

Fixed mode with a precision whose zeros do not fit NumPy's 16384-character buffer (Float formatting result too large).

getdomain(object)

The smallest domain containing the points: [x.min(), x.max()] of the points converted to their common type (integers become float64); for complex points the corners [min re + min im·j, max re + max im·j] of the bounding rectangle.

public NDArray getdomain(object x)

Parameters

x object

The 1-D points.

Returns

NDArray

A new 2-element array (float16/float32/float64/complex128).

Remarks

Exceptions

ValueError

Empty or non-1-d points, or no common type (bool).

mapdomain(NDArray, object, object)

Maps the points x from the domain old to new: off + scl*x with (off, scl) = mapparms(old, new) — one fused pass over the array, with NumPy's result dtype (a Python-number domain keeps a float32/float16 x's precision; an array domain's dtype promotes with x's).

public NDArray mapdomain(NDArray x, object old, object @new)

Parameters

x NDArray

The points (any shape; a TYPED C# array converts to an ndarray of its dtype — a Python list, an object[] or a jagged / NDArray[] array, binds mapdomain(object[], object, object)).

old object

The source domain (see the class remarks).

new object

The target domain.

Returns

NDArray

The mapped points (a new array; 0-d for a 0-d x).

Remarks

Exceptions

ArgumentNullException

x is null.

IndexError

A domain shorter than 2.

TypeError

A domain that is not subscriptable.

ZeroDivisionError

A zero-length domain of Python numbers.

OverflowError

Python int overflow.

mapdomain(double, double[], double[])

mapdomain(NDArray, object, object) for a Python float point and float64 domains: plain IEEE arithmetic (off + scl*x in float64; NumPy's float64 scalar math — a zero-length domain gives inf/nan, never raises).

public double mapdomain(double x, double[] old, double[] @new)

Parameters

x double

The point.

old double[]

The source domain (≥ 2 elements).

new double[]

The target domain (≥ 2 elements).

Returns

double

The mapped point.

Remarks

Exceptions

ArgumentNullException

A domain is null.

IndexError

A domain shorter than 2.

mapdomain(double, object, object)

mapdomain(NDArray, object, object) for a Python float x (C# integer and float literals bind here too — a Python int meets a float scale as its correctly rounded float, so nothing changes): NumPy leaves a Python scalar unconverted, so the arithmetic is CPython's for a Python-number domain and NumPy's scalar math for an array domain.

public object mapdomain(double x, object old, object @new)

Parameters

x double

The point.

old object

The source domain.

new object

The target domain.

Returns

object

The mapped point as a boxed C# number (double for a Python float or float64 scalar, the dtype's C# type for another NumPy scalar), or an NDArray for a 2-D domain.

Remarks

Exceptions

IndexError

A domain shorter than 2.

TypeError

A domain that is not subscriptable.

ZeroDivisionError

A zero-length domain of Python numbers.

OverflowError

Python int overflow.

mapdomain(Complex, object, object)

mapdomain(NDArray, object, object) for a Python complex x (CPython's complex arithmetic against a Python-number domain).

public object mapdomain(Complex x, object old, object @new)

Parameters

x Complex

The point.

old object

The source domain.

new object

The target domain.

Returns

object

The mapped point as a boxed C# number, or an NDArray for a 2-D domain.

Remarks

Exceptions

IndexError

A domain shorter than 2.

TypeError

A domain that is not subscriptable.

ZeroDivisionError

A zero-length domain of Python numbers.

OverflowError

Python int overflow.

mapdomain(object, object, object)

mapdomain(NDArray, object, object) for any x: a Python number (C# bool excepted — NumPy converts a bool with np.asanyarray) or a NumPy scalar (Half, char, decimal) is mapped unconverted; anything else is converted to an array first — a typed C# array as an ndarray of its dtype, a Python tuple / list (a ValueTuple, object[], a jagged or NDArray[] array, any enumerable) by np.array's coercion, nested to any depth.

public object mapdomain(object x, object old, object @new)

Parameters

x object

The point(s).

old object

The source domain.

new object

The target domain.

Returns

object

An NDArray for array points, a boxed C# number for a scalar point.

Remarks

Exceptions

ArgumentNullException

x is null.

IndexError

A domain shorter than 2.

TypeError

A domain that is not subscriptable.

ZeroDivisionError

A zero-length domain of Python numbers.

OverflowError

Python int overflow.

ValueError

A ragged tuple / list of points (np.array's inhomogeneous-shape text).

NotSupportedException

A list NumPy makes an object array of (None, a Python int past uint64).

mapdomain(object[], object, object)

mapdomain(object, object, object) for a Python LIST of points — an object[], or by array covariance a jagged or NDArray[] array. Without it a C# array argument would bind the NDArray overload through the implicit array conversion, which only understands TYPED arrays; here the list goes through np.array's coercion (nested to any depth, the dtype discovered over every item, a ragged list raising NumPy's text) before the domains are read, as NumPy's np.asanyarray(x) does.

public NDArray mapdomain(object[] x, object old, object @new)

Parameters

x object[]

The points.

old object

The source domain.

new object

The target domain.

Returns

NDArray

The mapped points (a new array).

Remarks

Exceptions

ArgumentNullException

x is null.

ValueError

A ragged list (np.array's inhomogeneous-shape text).

NotSupportedException

A list holding null or a Python int past uint64 (NumPy's object arrays); a list of strs is NumPy's str array, whose scl*x raises NumPy's TypeError.

IndexError

A domain shorter than 2.

TypeError

A domain that is not subscriptable.

ZeroDivisionError

A zero-length domain of Python numbers.

OverflowError

Python int overflow.

mapdomain<T0, T1, T2, T3>(NDArray, (T0, T1), (T2, T3))

mapdomain(NDArray, object, object) with the domains written as C# 2-tuples (see mapparms<T0, T1, T2, T3>((T0, T1), (T2, T3))): one fused pass over x, whose offset/scale come from CPython's arithmetic on machine numbers when the domains are Python ints/floats/complexes.

public NDArray mapdomain<T0, T1, T2, T3>(NDArray x, (T0, T1) old, (T2, T3) @new)

Parameters

x NDArray

The points (any shape; a typed C# array converts to an ndarray — a Python list binds the object[] overload).

old (T0, T1)

The source domain.

new (T2, T3)

The target domain.

Returns

NDArray

The mapped points (a new array; 0-d for a 0-d x).

Type Parameters

T0

Type of old[0].

T1

Type of old[1].

T2

Type of new[0].

T3

Type of new[1].

Remarks

Exceptions

ArgumentNullException

x is null.

ZeroDivisionError

A zero-length domain of Python numbers.

TypeError

NumPy's bool subtraction (NumPy bool elements).

OverflowError

Python int overflow.

NotSupportedException

A null or string domain element.

mapdomain<T0, T1, T2, T3>(double, (T0, T1), (T2, T3))

mapdomain(double, object, object) with the domains written as C# 2-tuples: a domain of Python numbers maps the Python float x with CPython's float/complex arithmetic on machine numbers and no allocation beyond the boxed result.

public object mapdomain<T0, T1, T2, T3>(double x, (T0, T1) old, (T2, T3) @new)

Parameters

x double

The point (a Python float; C# integer literals bind here too, as in the object-domain overload).

old (T0, T1)

The source domain.

new (T2, T3)

The target domain.

Returns

object

The mapped point as a boxed C# number (double for a real Python domain, Complex for a complex one), or an NDArray for a domain of arrays.

Type Parameters

T0

Type of old[0].

T1

Type of old[1].

T2

Type of new[0].

T3

Type of new[1].

Remarks

Exceptions

ZeroDivisionError

A zero-length domain of Python numbers.

TypeError

NumPy's bool subtraction.

OverflowError

Python int overflow.

NotSupportedException

A null or string domain element.

mapdomain<T0, T1, T2, T3>(Complex, (T0, T1), (T2, T3))

mapdomain(Complex, object, object) with the domains written as C# 2-tuples: CPython's complex arithmetic (a float operand joins as (f, 0.0), CPython 3.12's rule), without allocation for a Python-number domain.

public object mapdomain<T0, T1, T2, T3>(Complex x, (T0, T1) old, (T2, T3) @new)

Parameters

x Complex

The point (a Python complex).

old (T0, T1)

The source domain.

new (T2, T3)

The target domain.

Returns

object

The mapped point as a boxed C# number (Complex for a Python domain), or an NDArray for a domain of arrays.

Type Parameters

T0

Type of old[0].

T1

Type of old[1].

T2

Type of new[0].

T3

Type of new[1].

Remarks

Exceptions

ZeroDivisionError

A zero-length domain of Python numbers.

TypeError

NumPy's bool subtraction.

OverflowError

Python int overflow.

NotSupportedException

A null or string domain element.

mapdomain<T0, T1, T2, T3>(object[], (T0, T1), (T2, T3))

mapdomain<T0, T1, T2, T3>(NDArray, (T0, T1), (T2, T3)) for a Python LIST of points (an object[], a jagged or NDArray[] array) — see mapdomain(object[], object, object) for why a list needs its own overload: np.array's coercion of the list first, then the tuple-domain map.

public NDArray mapdomain<T0, T1, T2, T3>(object[] x, (T0, T1) old, (T2, T3) @new)

Parameters

x object[]

The points.

old (T0, T1)

The source domain.

new (T2, T3)

The target domain.

Returns

NDArray

The mapped points (a new array).

Type Parameters

T0

Type of old[0].

T1

Type of old[1].

T2

Type of new[0].

T3

Type of new[1].

Remarks

Exceptions

ArgumentNullException

x is null.

ValueError

A ragged list (np.array's inhomogeneous-shape text).

NotSupportedException

A list holding a str or null, or a null / string domain element.

ZeroDivisionError

A zero-length domain of Python numbers.

TypeError

NumPy's bool subtraction (NumPy bool elements).

OverflowError

Python int overflow.

mapparms(double[], double[])

mapparms(object, object) for float64 domains — the arrays a double[] spells — as plain IEEE arithmetic (NumPy's float64 scalar math: a zero-length domain gives inf/nan, never raises).

public (double off, double scl) mapparms(double[] old, double[] @new)

Parameters

old double[]

The source domain (≥ 2 elements).

new double[]

The target domain (≥ 2 elements).

Returns

(double off, double scl)

(off, scl).

Remarks

Exceptions

ArgumentNullException

A domain is null.

IndexError

A domain shorter than 2 (index 1 is out of bounds for axis 0 with size N).

mapparms(Complex[], Complex[])

mapparms(object, object) for complex128 domains — the arrays a Complex[] spells — with NumPy's complex SCALAR math: the naive product (no FMA) and NumPy's Smith division (inf/nan, never a raise, on a zero-length domain).

public (Complex off, Complex scl) mapparms(Complex[] old, Complex[] @new)

Parameters

old Complex[]

The source domain (≥ 2 elements).

new Complex[]

The target domain (≥ 2 elements).

Returns

(Complex off, Complex scl)

(off, scl).

Remarks

Exceptions

ArgumentNullException

A domain is null.

IndexError

A domain shorter than 2.

mapparms(object, object)

The offset and scale of the linear map L(x) = off + scl*x sending old[0] → new[0] and old[1] → new[1], computed exactly as NumPy writes it: off = (old[1]*new[0] - old[0]*new[1]) / (old[1] - old[0]), scl = (new[1] - new[0]) / (old[1] - old[0]).

public (object off, object scl) mapparms(object old, object @new)

Parameters

old object

The source domain (indexed at 0 and 1, never converted — see the class remarks for what a C# argument means).

new object

The target domain.

Returns

(object off, object scl)

(off, scl): each a boxed C# number — double / Complex for a Python result, the dtype's C# type (double, float, Half, Complex, …) for a NumPy scalar — or an NDArray when a domain is 2-D (its items are then arrays).

Remarks

Exceptions

IndexError

A domain shorter than 2 (NumPy's / CPython's text), a 0-d array.

TypeError

A domain that is not subscriptable (a number, null), or NumPy's bool subtraction.

ZeroDivisionError

A zero-length domain of Python numbers (ZeroDivisionError).

OverflowError

A Python int too large (integer division result too large for a float, or out of a NumPy integer dtype's range).

mapparms<T0, T1, T2, T3>((T0, T1), (T2, T3))

mapparms(object, object) for domains written as C# 2-tuples — Python tuples, NumPy's own docstring spelling (mapparms((-1, 1), (0, 2))) — read without boxing. When every element is a Python int, float or complex (a C# integer, bool, float, double or Complex) CPython's arithmetic runs on machine numbers (exact ints; an int intermediate beyond long switches to exact big integers, so the answer never changes); any other element (Half, an NDArray, a BigInteger, …) takes the general path with the same meaning it has in the object overload.

public (object off, object scl) mapparms<T0, T1, T2, T3>((T0, T1) old, (T2, T3) @new)

Parameters

old (T0, T1)

The source domain.

new (T2, T3)

The target domain.

Returns

(object off, object scl)

(off, scl) — a boxed double or Complex each for Python-number domains (true division never yields a Python int), otherwise as mapparms(object, object) returns them.

Type Parameters

T0

Type of old[0].

T1

Type of old[1].

T2

Type of new[0].

T3

Type of new[1].

Remarks

Exceptions

ZeroDivisionError

A zero-length domain of Python numbers (division by zero for ints, float division by zero once a float is involved — CPython 3.12's texts).

TypeError

NumPy's bool subtraction (NumPy bool elements).

OverflowError

A Python int too large (see mapparms(object, object)).

TypeError

A string element (a Python str): Python's subtraction error naming both items' types, in NumPy's order (old's subtraction before new's).

NotSupportedException

A null element.

trimcoef(object, double)

Removes the trailing coefficients whose magnitude is at most tol (np.abs(c) > tol decides what stays) and returns the rest as a fresh copy of the coefficient dtype; when nothing exceeds the tolerance the result is c[:1]*0 (a zero that keeps -0.0 and NaN the way NumPy's multiply does). A complex series is judged by its float64 magnitude.

public NDArray trimcoef(object c, double tol = 0)

Parameters

c object

The series (1-D).

tol double

The non-negative tolerance, NumPy's Python number (0, the default, trims only the trailing exact zeros): it adopts the coefficients' precision, so a float16 series compares against the float16-rounded tolerance; a NaN tolerance trims everything.

Returns

NDArray

The trimmed copy.

Remarks

https://numpy.org/doc/stable/reference/generated/numpy.polynomial.polyutils.trimcoef.html

API-parity batch 11 (the owner's decision 2, typed parameters only): one signature with NumPy's default; the (object c) and (object c, object tol) forms went, so a NumPy scalar or a 0-d array tolerance (strong: compared in the promoted dtype) is no longer a C# spelling - pass the number.

Exceptions

ValueError

tol must be non-negative; an empty or non-1-d series; no common type (bool).

trimseq(NDArray)

Removes trailing zeros from seq, keeping at least one element: seq ITSELF when it is empty or ends in a nonzero (NaN counts as nonzero, -0.0 as zero), otherwise the VIEW seq[:i+1] ending at the last nonzero — writes through it reach seq.

public NDArray trimseq(NDArray seq)

Parameters

seq NDArray

The sequence (rank ≥ 1; the rows of a 2-D+ array must hold exactly one element).

Returns

NDArray

The same instance, or a view of it.

Remarks

Exceptions

ArgumentNullException

seq is null.

TypeError

A 0-d array (len() of unsized object).

ValueError

Rows of several elements or of none (NumPy's truth-value errors).

trimseq(object)

trimseq(NDArray) for any other argument — NumPy returns the KIND it was given: a Python tuple (a ValueTuple / Tuple) itself or a new ValueTuple of the kept items; any other Python sequence (a IEnumerable) itself or an object[] of the kept items; a str itself; an NDArray, a typed C# array or a Memory<T> (ndarrays) itself or a view, as trimseq(NDArray) does.

public object trimseq(object seq)

Parameters

seq object

The sequence.

Returns

object

The same instance, or the trimmed sequence of the same kind.

Remarks

Exceptions

TypeError

A value without a length: null or a number (object of type 'int' has no len()), a 0-d array (len() of unsized object).

ValueError

A tested array item or row holds several elements or none.

trimseq(object[])

trimseq(NDArray) for a Python LIST — an object[], or by array covariance a jagged or NDArray[] array: seq ITSELF when it is empty or its last item is nonzero, otherwise a NEW array of the items up to the last nonzero one (at least one), NumPy's list slice seq[:i+1] (of the same element type). An item is zero exactly when Python's item != 0 is false: a number by value (NaN is nonzero, -0.0 zero, a complex zero only when both parts are), an array item by its truth value, and anything else — a str, a nested list, null — never equals 0.

public object[] trimseq(object[] seq)

Parameters

seq object[]

The list.

Returns

object[]

The same instance, or the trimmed copy.

Remarks

Exceptions

TypeError

seq is null (object of type 'NoneType' has no len()).

ValueError

A tested array item holds several elements or none (NumPy's truth-value errors).