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
Returns
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
descrsIReadOnlyList<DType>dtypeDTypeMeta
Returns
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
Returns
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
dtypesInIReadOnlyList<DTypeMeta>
Returns
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
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
arraysAndDtypesobject[]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.