Table of Contents

Struct NDAxis

Namespace
NumSharp
Assembly
NumSharp.dll

NumPy's axis argument as one C# type: a single axis (axis=1) or a tuple of axes (axis=(0, 2), axis=(1,), axis=()). A function whose NumPy default is axis=None takes NDAxis? axis = null, so null is NumPy's None, and the four spellings below convert implicitly:

np.all(a, 1);                 // axis=1
np.all(a, (0, 2));            // axis=(0, 2)        - a C# tuple of two or three ints
np.all(a, new[] { 0, 2 });    // axis=(0, 2)        - an int[]: NumPy's tuple of any length, () included
np.all(a, null);              // axis=None          - the default
np.all(a, new NDAxis(0, 2));  // axis=(0, 2)        - the constructors build the same values explicitly

The value only HOLDS the axes, exactly as given: negative axes stay negative and nothing is range-checked until the function that receives it normalizes them against its operand (Normalize(int, string, bool)), so the error texts are the ones NumPy's function raises.

public readonly struct NDAxis : IEquatable<NDAxis>
Implements
Inherited Members

Remarks

A single axis and a one-element tuple are different values, as in Python (1 != (1,)): most functions answer both alike (NumPy's normalize_axis_tuple turns an int into a 1-tuple), but a few read the difference - an integer axis of a 0-d array may be 0 or -1 in a reduction (np.all(np.array(5), 0)) where the tuple (0,) is an AxisError, and np.squeeze checks a tuple's repeats as it reads it. Use IsTuple to tell them apart.

Footguns. default(NDAxis) and new NDAxis() are the EMPTY tuple () (no axis at all, like new NDAxis(new int[0])), not axis 0 - a reduction over () reduces nothing. A null int[] converts to a null NDAxis? (None), but to a non-nullable NDAxis it throws ArgumentNullException: the null literal converts to NDAxis through the int[] conversion, so flag ? null : someAxis is typed NDAxis and throws when flag is true - write flag ? (NDAxis?)null : someAxis. A List<int> has no conversion: pass list.ToArray().

The array a tuple was built from is copied, so changing that array afterwards never changes the value.

Constructors

NDAxis(int)

A single axis: NumPy's axis=axis. The same value as the implicit conversion from int.

public NDAxis(int axis)

Parameters

axis int

The axis as given; a negative axis counts from the end and is resolved by the function that receives the value.

NDAxis(params int[])

A tuple of axes: NumPy's axis=(…), the order kept (new NDAxis(2, 0) is (2, 0)). With no argument it is the empty tuple (); with exactly one int argument C# calls NDAxis(int) instead (a single axis) - pass new[] { 1 } for the one-element tuple (1,).

public NDAxis(params int[] axes)

Parameters

axes int[]

The axes as given (negative ones count from the end; repeats are reported by the function that receives the value). The array is copied.

Exceptions

ArgumentNullException

axes is null (a null array is None only through the conversion to NDAxis?).

NDAxis((int, int, int))

A tuple of three axes from a C# tuple: NumPy's axis=(a, b, c).

public NDAxis((int, int, int) axes)

Parameters

axes (int, int, int)

The three axes as given.

NDAxis((int, int))

A tuple of two axes from a C# tuple: NumPy's axis=(a, b).

public NDAxis((int, int) axes)

Parameters

axes (int AxisA, int AxisB)

The two axes as given.

Properties

Count

The number of axes: 1 for a single axis, the tuple's length otherwise (0 for ()).

public int Count { get; }

Property Value

int

IsTuple

True for a tuple of axes ((0, 2), (1,), (), and default(NDAxis)), false for a single axis. The functions whose NumPy answer differs between 1 and (1,) read it (see the type's remarks).

public bool IsTuple { get; }

Property Value

bool

this[int]

The axis at index, as given (not normalized).

public int this[int index] { get; }

Parameters

index int

0 for a single axis; a position in the tuple otherwise.

Property Value

int

The axis.

Exceptions

IndexOutOfRangeException

index is not in [0, Count).

Methods

Equals(NDAxis)

Whether two values hold the same axes in the same form: a single axis never equals a tuple, as 1 != (1,) in Python.

public bool Equals(NDAxis other)

Parameters

other NDAxis

The other value.

Returns

bool

True when both are single axes with the same value, or tuples with the same axes in the same order.

Equals(object)

Whether two values hold the same axes in the same form: a single axis never equals a tuple, as 1 != (1,) in Python.

public override bool Equals(object obj)

Parameters

obj object

The other object.

Returns

bool

True when both are single axes with the same value, or tuples with the same axes in the same order.

GetHashCode()

A hash consistent with Equals(NDAxis).

public override int GetHashCode()

Returns

int

The hash of the form and the axes.

Normalize(int, string, bool)

NumPy's numpy.lib.array_utils.normalize_axis_tuple(axis, ndim, argname, allow_duplicate): every axis wrapped into [0, ndim), in order, then the repeat check. A single axis is the one-element tuple, as NumPy turns an int into one.

public int[] Normalize(int ndim, string argname = null, bool allowDuplicate = false)

Parameters

ndim int

The rank the axes address.

argname string

The argument name NumPy prints before the AxisError text and inside the repeat text ("repeated axis in source argument"), or null for the plain texts.

allowDuplicate bool

When false (NumPy's default) a repeated axis raises.

Returns

int[]

A new array of the normalized axes, in the given order.

Remarks

Not every NumPy function normalizes this way: a ufunc reduction (np.all, np.ptp, the sum behind np.count_nonzero) reports a repeat as duplicate value in 'axis' and lets a 0-d operand take the INTEGER axis 0 / -1, and np.squeeze checks each axis' range and repeat together, in order. Those functions read the axes themselves.

Exceptions

AxisError

An axis is outside [-ndim, ndim) (the first one in order, reported as given), checked for every axis before any repeat.

ValueError

Two axes are the same after normalization and allowDuplicate is false (repeated axis).

ToArray()

The axes as a new array, as given (not normalized): one element for a single axis, the tuple's elements otherwise. The array is the caller's to change.

public int[] ToArray()

Returns

int[]

A new array of Count axes.

ToString()

The value as Python prints the argument: 1, (0, 2), (1,) or ().

public override string ToString()

Returns

string

The Python repr of the axis or the tuple.

Operators

operator ==(NDAxis, NDAxis)

Whether two values are equal (Equals(NDAxis)).

public static bool operator ==(NDAxis left, NDAxis right)

Parameters

left NDAxis

The first value.

right NDAxis

The second value.

Returns

bool

True when they are equal.

implicit operator NDAxis(int)

A single axis: NumPy's axis=axis (the same value as NDAxis(int)).

public static implicit operator NDAxis(int axis)

Parameters

axis int

The axis as given.

Returns

NDAxis

The single-axis value.

Remarks

C# lifts this conversion, so an int? converts to NDAxis? as well: a null int? is None.

implicit operator NDAxis(int[])

A tuple of axes from an int array, for a non-nullable NDAxis parameter (the array is copied).

public static implicit operator NDAxis(int[] axes)

Parameters

axes int[]

The axes as given; an empty array is the empty tuple ().

Returns

NDAxis

The tuple.

Exceptions

ArgumentNullException

axes is null: a non-nullable NDAxis has no None. Convert to NDAxis? instead, where a null array is None.

implicit operator NDAxis?(int[])

A tuple of axes from an int array, for an NDAxis? parameter: a null array is None (the meaning a null int[] axis had in the overloads this type replaced), any other array a tuple (copied).

public static implicit operator NDAxis?(int[] axes)

Parameters

axes int[]

The axes, or null for None.

Returns

NDAxis?

The tuple, or null.

implicit operator NDAxis((int, int, int))

A tuple of three axes from a C# tuple: (0, 1, 2) is NumPy's axis=(0, 1, 2).

public static implicit operator NDAxis((int, int, int) axes)

Parameters

axes (int, int, int)

The three axes as given.

Returns

NDAxis

The tuple.

implicit operator NDAxis((int, int))

A tuple of two axes from a C# tuple: (0, 2) is NumPy's axis=(0, 2).

public static implicit operator NDAxis((int, int) axes)

Parameters

axes (int AxisA, int AxisB)

The two axes as given.

Returns

NDAxis

The tuple.

operator !=(NDAxis, NDAxis)

Whether two values differ (Equals(NDAxis)).

public static bool operator !=(NDAxis left, NDAxis right)

Parameters

left NDAxis

The first value.

right NDAxis

The second value.

Returns

bool

True when they differ.