Table of Contents

Class ArrayMethod

Namespace
NumSharp
Assembly
NumSharp.dll

NEP 43's ArrayMethod — ONE object per (input DTypes → output DTypes) implementation of an operation: it resolves the loop descriptors for the given operand descriptors (resolve_descriptors(DType[], DType[], out long)) and hands out the strided inner loop that runs them (get_strided_loop(ArrayMethodContext, bool, long[], out NDArrayMethodFlags)). Casts are the first family (CastingImpl); ufunc loops for a new dtype register the same way (Stage C) instead of adding a case NPTypeCode.X: to the IL generators.

public abstract class ArrayMethod
Inheritance
ArrayMethod
Derived
Inherited Members

Remarks

The loop contract is NDInnerLoopFunc — NumSharp's existing analog of NumPy's PyUFuncGenericFunction / PyArrayMethod_StridedLoop — so NDIter drives a registered loop without a new driver. casting is the method's MINIMAL cast safety (NumPy's PyArrayMethodObject.casting): PyArray_CheckCastSafety short-circuits on it and only calls resolve_descriptors(DType[], DType[], out long) when the requested rule is stricter.

NumPy's names. The members are the fields of NumPy's PyArrayMethodObject (name, nin, nout, casting, flags, resolve_descriptors, get_strided_loop, array_method.h) and of the PyBoundArrayMethodObject that NumPy wraps around it to hold the operand classes (dtypes); NumSharp keeps both in one object, because a method here does not need to avoid NumPy's reference cycle between a method and its classes. The same names are the fields of the public PyArrayMethod_Spec a NumPy extension fills in to create a method. The test DTypeOracleTests.Members_ExistUnderNumPysNames holds the C# members to the names it reads from NumPy's headers.

Constructors

ArrayMethod(string, int, int, NPY_CASTING, NDArrayMethodFlags, IReadOnlyList<DTypeMeta>)

Builds a method — the fields NumPy's PyArrayMethod_FromSpec copies out of a PyArrayMethod_Spec.

protected ArrayMethod(string name, int nin, int nout, NPY_CASTING casting, NDArrayMethodFlags flags, IReadOnlyList<DTypeMeta> dtypes)

Parameters

name string

The method name ("numeric_cast", "datetime_casts", …).

nin int

The number of input operands.

nout int

The number of output operands.

casting NPY_CASTING

The minimal cast safety the method guarantees for any descriptors of its classes.

flags NDArrayMethodFlags

The method flags.

dtypes IReadOnlyList<DTypeMeta>

The classes of the operands, inputs first, then outputs: nin + nout entries.

Exceptions

ArgumentNullException

name or dtypes is null.

ArgumentOutOfRangeException

nin or nout is negative.

ArgumentException

dtypes does not hold one class per operand.

Fields

NoView

The view_offset value meaning "this cast is not a view" (NumPy's NPY_MIN_INTP).

public const long NoView = -9223372036854775808

Field Value

long

Properties

casting

NumPy's casting: the minimal cast safety this method guarantees for ANY descriptors of its DTypes (-1 in NumPy means "must resolve"; here NPY_UNSAFE_CASTING plays that role). A per-method constant; virtual so an implementation whose value is derived from a table that may not be built yet when the method is REGISTERED (the builtin numeric casts read np's frozen promotion table, and np's own type initializer can be what constructs DTypeRegistry) can compute it on first read instead.

public virtual NPY_CASTING casting { get; }

Property Value

NPY_CASTING

dtypes

The DType classes of the operands, inputs first then outputs — NumPy's PyBoundArrayMethodObject.dtypes.

public IReadOnlyList<DTypeMeta> dtypes { get; }

Property Value

IReadOnlyList<DTypeMeta>

flags

The method flags (unaligned support, floating-point-error behaviour, …) — NumPy's flags.

public NDArrayMethodFlags flags { get; }

Property Value

NDArrayMethodFlags

name

The method name ("numeric_cast", "datetime_casts", …) — NumPy's name.

public string name { get; }

Property Value

string

nin

The number of input operands — NumPy's nin.

public int nin { get; }

Property Value

int

nout

The number of output operands — NumPy's nout.

public int nout { get; }

Property Value

int

Methods

ToString()

Returns a string that represents the current object.

public override string ToString()

Returns

string

A string that represents the current object.

get_strided_loop(ArrayMethodContext, bool, long[], out NDArrayMethodFlags)

NumPy's get_strided_loop: the inner loop for the resolved context and the given fixed strides. The casts between the storage classes override it - the builtin numeric casts (the IL cast kernels), the fixed-width text casts (formatting, parsing, the text truth, the zero-pad copy and the S ↔ U casts) and the StringDType casts - and DTypeCasting hands their loops out (NumPy's PyArray_GetDTypeTransferFunction). The datetime casts have no storage yet (Stage C), so they keep this base implementation, which raises.

public virtual NDInnerLoopFunc get_strided_loop(ArrayMethodContext context, bool aligned, long[] strides, out NDArrayMethodFlags flags)

Parameters

context ArrayMethodContext

The method and the resolved operand descriptors.

aligned bool

True when every operand is aligned.

strides long[]

The fixed byte strides of the operands, or the strides of the first call.

flags NDArrayMethodFlags

Receives the flags of the returned loop (they may differ from the method's flags).

Returns

NDInnerLoopFunc

The inner loop: one call converts one strided run, dataptrs / strides holding the inputs first, then the outputs (a cast: [0] the source, [1] the destination). A NumSharp loop captures what it needs and ignores auxdata; it raises a conversion error as an exception, at the element NumPy's loop raises it.

Exceptions

NotSupportedException

The base implementation: the method has no loop (a datetime cast before Stage C).

resolve_descriptors(DType[], DType[], out long)

NumPy's resolve_descriptors: given the operand descriptors (an output entry may be null — "please pick"), fills loopDescrs with the descriptors the loop will actually run on and returns the cast safety of doing so.

public abstract NPY_CASTING resolve_descriptors(DType[] givenDescrs, DType[] loopDescrs, out long viewOffset)

Parameters

givenDescrs DType[]

The operand descriptors, inputs first; an output entry may be null.

loopDescrs DType[]

Receives the descriptors the loop runs on, one per operand.

viewOffset long

The byte offset at which the operation is a plain VIEW (0 for a no-op cast between identical descriptors), or NoView.

Returns

NPY_CASTING

The cast safety of running the loop on loopDescrs.

Exceptions

TypeError

The descriptors cannot be resolved (NumPy returns -1 with an error set).