Table of Contents

Class DTypePromotion

Namespace
NumSharp
Assembly
NumSharp.dll

The NEP 42 / NEP 50 promotion engine over DType classes and descriptors — the ports of NumPy's common_dtype.c and convert_datatype.c: CommonDType(DTypeMeta, DTypeMeta) (PyArray_CommonDType), PromoteDTypeSequence(IReadOnlyList<DTypeMeta>) (PyArray_PromoteDTypeSequence with its reduce_dtypes_to_most_knowledgeable pass), PromoteTypes(DType, DType) (PyArray_PromoteTypes), CastDescrToDType(DType, DTypeMeta) (PyArray_CastDescrToDType), CastToDTypeAndPromoteDescriptors(IReadOnlyList<DType>, DTypeMeta) and ResultType(params object[]) (PyArray_ResultType, the NEP 50 entry point where C# literals are weak and arrays — 0-d included — are strong).

public static class DTypePromotion
Inheritance
DTypePromotion
Inherited Members

Remarks

Two NumPy numeric classes promote by NumPy's own table of type numbers (NumSharp.NumPyPromotionTable, consulted by DefaultBuiltinCommonDType(DTypeMeta, DTypeMeta)): its answer is a CLASS, and can be a lane-sharing C-type class even for two canonical classes (Windows' promote(int16, uint16) is the C int class 'i'). Its storage lane is always the one NumSharp's frozen table (NumSharp.np._nptypemap_arr_arr) names — the table every kernel and NumSharp's own Decimal and Char still promote by — so every two-operand promote_types / result_type answer the dtype_text fuzz tier gates is unchanged. Three things the old engine could not do come with the port: order-independent reduction of THREE OR MORE operands (the old fold dropped every other pair, so result_type(i1, i1, f8, i1) was int8), weak C# literals (result_type(int8_array, 300) is int8, result_type(int8_array, 1.5) is float64), and parametric classes (the datetime unit GCD).

Methods

CastDescrToDType(DType, DTypeMeta)

NumPy's PyArray_CastDescrToDType: the instance of givenDType that can represent descr — the descriptor itself when already of that class, the class default when the class is not parametric, else whatever the registered cast resolves (a datetime keeps its unit when cast between datetime64 and timedelta64; an integer cast to timedelta64 lands on the generic unit).

public static DType CastDescrToDType(DType descr, DTypeMeta givenDType)

Parameters

descr DType
givenDType DTypeMeta

Returns

DType

Exceptions

TypeError

cannot cast dtype %S to %S.

CastToDTypeAndPromoteDescriptors(IReadOnlyList<DType>, DTypeMeta)

NumPy's PyArray_CastToDTypeAndPromoteDescriptors: cast every descriptor to dtype and fold their common_instance (the string-length / datetime-unit resolution over N operands).

public static DType CastToDTypeAndPromoteDescriptors(IReadOnlyList<DType> descrs, DTypeMeta dtype)

Parameters

descrs IReadOnlyList<DType>
dtype DTypeMeta

Returns

DType

CommonDType(DTypeMeta, DTypeMeta)

NumPy's PyArray_CommonDType: dtype1.common_dtype(dtype2), then the mirrored question, then DTypePromotionError with NumPy's verbatim text.

public static DTypeMeta CommonDType(DTypeMeta dtype1, DTypeMeta dtype2)

Parameters

dtype1 DTypeMeta
dtype2 DTypeMeta

Returns

DTypeMeta

PromoteDTypeSequence(IReadOnlyList<DTypeMeta>)

NumPy's PyArray_PromoteDTypeSequence: the common class of any number of classes, computed so the answer does not depend on operand order (the "most knowledgeable" class — the highest category — promotes every other one; two mutually unknown classes raise).

public static DTypeMeta PromoteDTypeSequence(IReadOnlyList<DTypeMeta> dtypesIn)

Parameters

dtypesIn IReadOnlyList<DTypeMeta>

Returns

DTypeMeta

Exceptions

DTypePromotionError

NumPy's verbatim The DType %S could not be promoted by %S. ….

PromoteTypes(DType, DType)

NumPy's PyArray_PromoteTypes: the smallest descriptor both inputs cast to safely. The SAME native legacy descriptor object passed twice is returned as is (metadata and an explicit byte order preserved); otherwise the common CLASS decides — a non-parametric class yields its default descriptor (the singleton: metadata and an explicit host byte order are dropped), a parametric one casts both inputs to itself (CastDescrToDType(DType, DTypeMeta)) and takes their common_instance.

public static DType PromoteTypes(DType type1, DType type2)

Parameters

type1 DType

The first descriptor.

type2 DType

The second descriptor.

Returns

DType

The promoted descriptor.

Exceptions

ArgumentNullException

Either descriptor is null.

DTypePromotionError

The two classes have no common class.

TypeError

A parametric common class cannot represent an input, or the units have no common divisor.

ResultType(params object[])

NumPy's PyArray_ResultType under NEP 50: the descriptor of the result of combining arraysAndDtypes, where every NDArray (0-d included), DType, NPTypeCode, Type, dtype string, bool, char, Half and decimal is STRONG (contributes its dtype), while a C# integer, float/double or Complex literal is WEAK — it contributes only its NEP 50 class (_PyLongDType, _PyFloatDType, _PyComplexDType) and no width, so result_type(int8_array, 300) is int8. A DTypeMeta operand contributes the class alone, and a null operand is NumPy's None: the strong float64 descriptor (np.result_type(None, np.int8) is float64).

public static DType ResultType(params object[] arraysAndDtypes)

Parameters

arraysAndDtypes object[]

The operands, classified by ClassifyOperand(object, out DTypeMeta, out DType).

Returns

DType

The result descriptor.

Exceptions

ValueError

at least one array or dtype is required.

DTypePromotionError

No common dtype exists.

TypeError

An operand that is no dtype, or a dtype string NumPy cannot parse (see ClassifyOperand(object, out DTypeMeta, out DType)).

NotSupportedException

A dtype string or Type naming a dtype NumSharp has no class for.