Table of Contents

Class NDScalarType

Namespace
NumSharp
Assembly
NumSharp.dll

A NumPy scalar TYPE: one class of NumPy's numpy.generic hierarchy, or one of the Python built-in classes that hierarchy derives from, as a C# object. The ten abstract classes are np.generic, np.number, np.integer, np.signedinteger, np.unsignedinteger, np.inexact, np.floating, np.complexfloating, np.flexible and np.character; every registered dtype class has one concrete class under them (numpy.float64, numpy.int8, numpy.datetime64, ...), and so do the NumPy classes NumSharp has no dtype for (numpy.complex64, numpy.object_, numpy.void). They are what np.issubdtype(a.dtype, np.integer), isinstance(x, np.floating) and issubclass(t, np.number) test against.

public sealed class NDScalarType
Inheritance
NDScalarType
Inherited Members

Examples

np.issubdtype(a.dtype, np.integer)           // NumPy's most common type test
np.issubdtype(np.float32, np.floating)       // True
np.floating.__instancecheck__(a.sum())        // isinstance(a.sum(), np.floating)
np.number.__subclasscheck__(a.dtype.type)     // issubclass(a.dtype.type, np.number)
NDScalarType t = a.dtype;                     // a.dtype.type: the scalar class, <class 'numpy.float64'>
DType d = (DType)t;                           // np.dtype(t): the descriptor again
t.__mro__                                     // [float64, floating, inexact, number, generic, float, object]

Remarks

Why a type of its own. NumSharp spells a CONCRETE scalar class by its descriptor: np.float64 is a DType, because a C# double already is the scalar and every dtype= parameter takes a DType. An ABSTRACT class has no descriptor (np.dtype(np.integer) raises in NumPy 2.x), so it cannot be a DType; it is an NDScalarType. The concrete classes exist as NDScalarType objects too, so the hierarchy is complete: a descriptor converts IMPLICITLY to its scalar class (NumPy's dtype.type: NDScalarType t = np.float64;), and a scalar class converts EXPLICITLY back to its descriptor (NumPy's np.dtype(t)). The way back is explicit because it raises for an abstract class, with NumPy's own text (Converting `np.inexact` or `np.floating` to a dtype not allowed), so an abstract class passed where a dtype is expected is a compile error rather than a runtime one — every such call raises in NumPy too (np.zeros(3, np.integer), np.can_cast(x, np.floating)).

Identity. Each class is ONE object, compared by reference, as Python compares class objects: the abstract, dtype-less and built-in classes are static singletons, and the concrete class of a dtype class is built once and cached on its DTypeMeta, so (NDScalarType)np.dtype("f8") and (NDScalarType)np.float64 are the same object. There are no == operators: reference equality is Python's is and == for classes.

Python's built-in classes. NumPy's classes derive from Python's: numpy.generic from object, numpy.float64 also from float, numpy.complex128 from complex, numpy.bytes_ from bytes and numpy.str_ from str; np.ScalarType lists int, float, complex, bool, bytes, str and memoryview; and a StringDType descriptor's class IS Python's str. Those eight classes are modelled (PyObject, PyInt, PyBool, PyFloat, PyComplex, PyStr, PyBytes, PyMemoryView), with Python's own bases (bool derives from int), so every __mro__ is NumPy's whole tuple, computed by Python's C3 linearisation.

Instances. NumSharp has no scalar objects: a C# value of a dtype's element type (a boxed double, int, Half, Complex, decimal, char, bool or string) IS a scalar of that dtype, and so is a 0-d NDArray that stands for a scalar (every computed 0-d result, a[0] of a 1-D array, Scalar<T>(T)). A C# value is also the Python object it stands for in NumSharp's NEP 50 rules (a C# int is a Python int, a double a Python float). An explicit np.array(5) is a 0-d ndarray, not a scalar, exactly as in NumPy (isinstance(np.array(5), np.integer) is False). See __instancecheck__(object).

NumSharp's classes against NumPy's. NumSharp-only dtypes get NumSharp-only classes under the family their kind names (numsharp.decimal under floating, numsharp.char under unsignedinteger), the same placement np.isdtype has always used for them. The NumPy classes NumSharp has no dtype for (complex64, object_, void) exist as classes and refuse the conversion to a dtype with a NotSupportedException; a dtype class registered later under their NumPy type number adopts them.

Not modelled. The class call (np.float64(1.5), which makes a NumPy scalar), the unbound scalar methods NumPy's classes carry (np.integer.is_integer), NumPy's numpy.record (the class of a structured record, NumPy's one subclass of void), and Python's other classes: a built-in class's __subclasses__() lists only the modelled classes (Python's str.__subclasses__() also holds enum.StrEnum, and object.__subclasses__() some 360 classes).

Thread safety. Immutable after construction; the lazily built concrete classes are published with a compare-exchange, so concurrent first uses agree on one object.

Properties

IsAbstract

True for NumPy's ten abstract classes, which have no descriptor (converting one to a dtype raises NumPy's TypeError) and no instances; false for every concrete and built-in class.

public bool IsAbstract { get; }

Property Value

bool

IsBuiltin

True for Python's built-in classes (PyObject, PyFloat, ...), which are not NumPy dtypes: np.isdtype refuses them, and np.issubdtype reads one as NumPy's dtype(cls).type (float as numpy.float64).

public bool IsBuiltin { get; }

Property Value

bool

PyBool

Python's bool (a subclass of int): a C# bool is an instance; numpy.bool is not a subclass.

public static NDScalarType PyBool { get; }

Property Value

NDScalarType

PyBytes

Python's bytes: a C# byte[] is an instance (NumSharp's text APIs read it as bytes), and numpy.bytes_ a subclass.

public static NDScalarType PyBytes { get; }

Property Value

NDScalarType

PyComplex

Python's complex: a C# Complex is an instance, and numpy.complex128 a subclass.

public static NDScalarType PyComplex { get; }

Property Value

NDScalarType

PyFloat

Python's float: a C# double / float is an instance, and numpy.float64 a subclass.

public static NDScalarType PyFloat { get; }

Property Value

NDScalarType

PyInt

Python's int: a C# integer value is an instance (isinstance(5, int)); no NumPy integer class derives from it.

public static NDScalarType PyInt { get; }

Property Value

NDScalarType

PyMemoryView

Python's memoryview: an np.MemoryView (ndarray.data) is an instance.

public static NDScalarType PyMemoryView { get; }

Property Value

NDScalarType

PyObject

Python's object: numpy.generic's base, the end of every __mro__; every non-null value is an instance.

public static NDScalarType PyObject { get; }

Property Value

NDScalarType

PyStr

Python's str: a C# string is an instance, numpy.str_ a subclass, and a StringDType descriptor's class this class itself.

public static NDScalarType PyStr { get; }

Property Value

NDScalarType

__base__

Python's base: the first direct base (np.number for np.integer, numpy.floating for numpy.float64, Python's bytes for numpy.bytes_, object for numpy.generic). Null only for object.

public NDScalarType __base__ { get; }

Property Value

NDScalarType

__bases__

Python's bases: the direct bases in Python's order, read-only — one for most classes, two for NumPy's classes that also derive from a Python one (numpy.float64: [floating, float], numpy.str_: [str, character]), none for object.

public IReadOnlyList<NDScalarType> __bases__ { get; }

Property Value

IReadOnlyList<NDScalarType>

__module__

Python's module: "numpy", "numsharp" for NumSharp's own classes (decimal, char), or "builtins" for Python's classes (the class of a StringDType descriptor included).

public string __module__ { get; }

Property Value

string

__mro__

Python's mro: the method resolution order, read-only — this class, then its bases in Python's C3 order, ending in object ([float64, floating, inexact, number, generic, float, object] for numpy.float64).

public IReadOnlyList<NDScalarType> __mro__ { get; }

Property Value

IReadOnlyList<NDScalarType>

__name__

Python's name: "integer", "float64", "bool", "datetime64", "float".

public string __name__ { get; }

Property Value

string

__qualname__

Python's qualname: the same as __name__, since none of these classes is nested.

public string __qualname__ { get; }

Property Value

string

Methods

ToString()

NumPy's rendering of a class, repr(np.integer) and str(np.integer) alike: <class 'numpy.integer'>. Python leaves out the module of a built-in class (<class 'float'>), the class of a StringDType descriptor included (<class 'str'>).

public override string ToString()

Returns

string

The class repr.

__instancecheck__(object)

Python's isinstance(instance, cls): true when instance is an object of this class or of one of its subclasses (np.integer.instancecheck(a[0]) for an int32 array is true).

public bool __instancecheck__(object instance)

Parameters

instance object

The value to test; null is not an instance of anything (Python's None is, but of no class NumSharp models).

Returns

bool

For PyObject: true for every non-null value (every Python object is an object).

For an NDArray: true only when it is a 0-d array that stands for a scalar — a computed 0-d result, a[0] of a 1-D array or Scalar<T>(T) — and its dtype's class is under this one (a 0-d float64 array is a numpy.float64, so also a Python float; a 0-d float32 is not). An array with dimensions and an explicit np.array(x) 0-d array are ndarrays, not scalars.

For a boxed C# value: true when its type is the element type of a dtype whose class is under this one (a double is a numpy.float64, a decimal a numsharp.decimal), OR when the Python object it stands for is (a C# integer is a Python int, a bool a bool, a float / double a float, a Complex a complex, a string a str, a byte[] a bytes, an np.MemoryView a memoryview). False for a descriptor or a class (a class is not an instance of itself), and for a value of a type neither mapping knows.

Remarks

NumSharp has no scalar objects, so a C# value stands for both of the objects Python keeps apart: a double is the numpy.float64 an array's element is and the Python float a literal is. So np.float64.__instancecheck__(1.5) and PyFloat.__instancecheck__(1.5) are both true, where NumPy's 1.0 is a float but not a numpy.float64, and PyInt.__instancecheck__(5) is true although a NumPy int32 scalar is not an int. A ported isinstance(x, (int, np.integer)) therefore answers for the values NumSharp hands out, which is what such a test is written for. The same rule makes a C# string a numpy.str_ scalar (the U dtype stores string), where NumPy's "abc" is a str but not an np.str_.

The element type must match EXACTLY: a boxed enum is not an integer even though its underlying type is, because no dtype stores enums and an enum is not a Python int.

__subclasscheck__(NDScalarType)

Python's issubclass(subclass, cls): true when subclass is this class or derives from it. A DType converts implicitly to its scalar class, so a descriptor is accepted where NumPy passes a class (np.number.subclasscheck(np.float32) is true).

public bool __subclasscheck__(NDScalarType subclass)

Parameters

subclass NDScalarType

The class to test.

Returns

bool

True when this class is in subclass's __mro__.

Exceptions

TypeError

subclass is null (Python's issubclass() arg 1 must be a class).

__subclasscheck__(Type)

Python's issubclass(subclass, cls) for a C# type — NumSharp's type is the C# element type, so a port of issubclass(a.dtype.type, np.integer) lands here: np.integer.subclasscheck(typeof(int)) is true. As for instances, a C# type stands for both the NumPy class of the dtype that stores it and the Python class its values are (typeof(int) is numpy.int32 and int).

public bool __subclasscheck__(Type subclass)

Parameters

subclass Type

The C# type to test.

Returns

bool

True when either class subclass stands for derives from this one, and true for PyObject whatever the type (every class derives from object); false otherwise.

Exceptions

TypeError

subclass is null (Python's issubclass() arg 1 must be a class).

__subclasses__()

Python's type.subclasses(): the DIRECT subclasses, as a new list, in creation order — NumPy's registration order for NumPy's classes, abstract subclasses first (np.signedinteger.subclasses() is [int8, int16, int32, int64, timedelta64] on a host whose C int is NumSharp's int32 class). A built-in class lists the modelled classes only (Python's own list also holds classes outside NumPy).

public List<NDScalarType> __subclasses__()

Returns

List<NDScalarType>

A new list of the direct subclasses.

Remarks

The list is computed once per registry state and copied out on each call: a dtype registered after this class was first asked still shows up as its subclass (as a Python class created later does), because every registration publishes a new registry array and the cached list remembers the array it was built from.

mro()

Python's type.mro(): the method resolution order as a NEW, mutable list (Python returns a fresh list each call).

public List<NDScalarType> mro()

Returns

List<NDScalarType>

A new list holding __mro__'s classes.

Operators

explicit operator DType(NDScalarType)

The descriptor of a scalar class — NumPy's np.dtype(cls): a concrete class gives its dtype class's builtin descriptor, the same object np.dtype("f8") returns; a Python built-in class gives NumPy's descriptor for it (np.dtype(float) is float64, np.dtype(int) the pointer-sized integer, np.dtype(str) the unsized <U).

public static explicit operator DType(NDScalarType sctype)

Parameters

sctype NDScalarType

The scalar class, or null.

Returns

DType

The descriptor, or null for a null class.

Exceptions

TypeError

sctype is abstract: NumPy's texts, e.g. Converting 'np.integer' or 'np.signedinteger' to a dtype is not allowed (the conversion is explicit for exactly this reason).

NotSupportedException

sctype is a NumPy class NumSharp has no dtype for (complex64, object_, void, and the built-in object / memoryview, whose NumPy dtypes are those).

implicit operator NDScalarType(DType)

The scalar class of a descriptor — NumPy's dtype.type (np.dtype('f8').type is np.float64). Every descriptor has one, so the conversion never fails; descriptors of one dtype class ('<f8', '>f8'; 'M8[s]', 'M8[ns]') share it, and a StringDType descriptor's is Python's str.

public static implicit operator NDScalarType(DType dtype)

Parameters

dtype DType

The descriptor, or null.

Returns

NDScalarType

Its scalar class, or null for a null descriptor (C#'s null maps through, as every DType conversion does).