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
alistobjectThe 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.
trimboolRemove 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
alistis 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
xobjectThe value. A double is
np.float64/ a Python float, a floatnp.float32(float32's digits:0.1fis'0.1'at every precision), a Halfnp.float16, a decimal NumSharp's floating decimal (printed as its float64). Anything that is not floating prints as Python'sstr()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'sstr()— a 0-d array too, since NumPy's test readstype(x), which isndarraythere ('0.30000000000000004').parensboolWrap a scientific result in parentheses (
'(1.0e-05)'); a positional or special result is never wrapped.
Returns
- string
The text:
nanstr/infstrfor NaN and either infinity (an infinity's sign is NOT printed, as in NumPy:-infgives'inf'); withfloatmode='fixed'exactlyprecisiondigits ('0.10000000'); a leading '+' withsign='+'(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
xobjectThe 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
xNDArrayThe 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)).oldobjectThe source domain (see the class remarks).
newobjectThe target domain.
Returns
- NDArray
The mapped points (a new array; 0-d for a 0-d x).
Remarks
Exceptions
- ArgumentNullException
xis 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
xdoubleThe point.
olddouble[]The source domain (≥ 2 elements).
newdouble[]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
Returns
- object
The mapped point as a boxed C# number (
doublefor 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
Returns
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
Returns
Remarks
Exceptions
- ArgumentNullException
xis 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
Returns
- NDArray
The mapped points (a new array).
Remarks
Exceptions
- ArgumentNullException
xis 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*xraises 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
xNDArrayThe 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
T0Type of
old[0].T1Type of
old[1].T2Type of
new[0].T3Type of
new[1].
Remarks
Exceptions
- ArgumentNullException
xis 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
xdoubleThe 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 (
doublefor a real Python domain, Complex for a complex one), or an NDArray for a domain of arrays.
Type Parameters
T0Type of
old[0].T1Type of
old[1].T2Type of
new[0].T3Type 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
xComplexThe 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
T0Type of
old[0].T1Type of
old[1].T2Type of
new[0].T3Type 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
xobject[]The points.
old(T0, T1)The source domain.
new(T2, T3)The target domain.
Returns
- NDArray
The mapped points (a new array).
Type Parameters
T0Type of
old[0].T1Type of
old[1].T2Type of
new[0].T3Type of
new[1].
Remarks
Exceptions
- ArgumentNullException
xis 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
Returns
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
Returns
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
oldobjectThe source domain (indexed at 0 and 1, never converted — see the class remarks for what a C# argument means).
newobjectThe 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 boxeddoubleor Complex each for Python-number domains (true division never yields a Python int), otherwise as mapparms(object, object) returns them.
Type Parameters
T0Type of
old[0].T1Type of
old[1].T2Type of
new[0].T3Type of
new[1].
Remarks
Exceptions
- ZeroDivisionError
A zero-length domain of Python numbers (
division by zerofor ints,float division by zeroonce 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
cobjectThe series (1-D).
toldoubleThe 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
seqNDArrayThe 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
seqis 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
seqobjectThe 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
seqobject[]The list.
Returns
- object[]
The same instance, or the trimmed copy.
Remarks
Exceptions
- TypeError
seqis null (object of type 'NoneType' has no len()).- ValueError
A tested array item holds several elements or none (NumPy's truth-value errors).