[Array API Standard] Cross-Platform Array Library Compatibility

Overview

The Python Array API Standard is a consortium-driven specification defining a common API for array computing libraries, enabling code portability across NumPy, PyTorch, JAX, CuPy, Dask, and other array libraries.

Version: 2024.12 | Full Specification

---

Why It Matters

1. Interoperability: Code written against Array API works across any conforming library
2. Future-proofing: As adoption grows, NumSharp conformance ensures ecosystem compatibility
3. Clear specification: Unambiguous behavioral requirements
4. Cross-platform: Same API for CPU, GPU, and distributed arrays

---

Required Data Types (14)

Category	Types
Boolean	bool
Signed Integer	int8, int16, int32, int64
Unsigned Integer	uint8, uint16, uint32, uint64
Floating-Point	float32, float64
Complex	complex64, complex128

NumSharp Gap: Currently 12 types - missing complex64 and complex128.

---

Required Constants (5)

Constant	Description
e	Euler's constant (2.71828...)
inf	Positive infinity
nan	Not a Number
newaxis	Alias for dimension expansion
pi	Mathematical pi (3.14159...)

---

Array Object Requirements

Attributes (7 required)

Attribute	Description
dtype	Data type of elements
device	Hardware device (CPU/GPU)
ndim	Number of dimensions
shape	Dimensions tuple
size	Total element count
T	Transpose
mT	Matrix transpose (stacked matrices)

Operators (all required)

• Arithmetic: +, -, *, /, //, %, **, unary -, +
• Comparison: <, <=, >, >=, ==, !=
• Bitwise: ~, &, |, ^, <<, >>
• Matrix: @ (matmul)
• All reflected and in-place variants

---

Function Categories Summary

Category	Count	Examples
Creation	16	arange, asarray, empty, eye, linspace, ones, zeros
Element-wise	67	add, sin, exp, log, isnan, maximum, clip
Data Types	6	astype, can_cast, finfo, iinfo, isdtype, result_type
Linear Algebra	4	matmul, matrix_transpose, tensordot, vecdot
Manipulation	14	broadcast_to, concat, reshape, squeeze, stack
Statistical	9	sum, mean, std, var, max, min, prod
Searching	6	argmax, argmin, nonzero, where, searchsorted
Sorting	2	sort, argsort
Set	4	unique_all, unique_counts, unique_inverse, unique_values
Indexing	2	take, take_along_axis
Utility	3	all, any, diff
Total	133

Optional Extensions

• linalg (23): cholesky, det, eigh, inv, qr, svd, solve, etc.
• fft (14): fft, ifft, rfft, fftfreq, etc.

---

Key Behavioral Requirements

Type Promotion

• Within category: promotes to larger bit-width
• Signed + Unsigned: unsigned promotes to signed
• No cross-category: int + float requires explicit cast

std/var Difference

# Array API: correction parameter (default 0.0 = population)
std(x, correction=1.0)  # sample std

# NumPy: ddof parameter
np.std(x, ddof=1)  # sample std

Unique Functions Split

# Array API: 4 separate functions
unique_values(x)      # just values
unique_counts(x)      # values and counts
unique_inverse(x)     # values and inverse indices
unique_all(x)         # everything

# NumPy: single function with flags
np.unique(x, return_counts=True, return_inverse=True)

---

Suggested Implementation for NumSharp

Phase 1: Core Compliance

• Add complex number support (complex64, complex128)
• Add device parameter (CPU-only but API-compatible)
• Implement isdtype() function
• Add .mT property

Phase 2: Function Alignment

• Rename/alias: cumulative_sum/cumulative_prod
• Add missing: copysign, hypot, logaddexp, nextafter, signbit
• Implement: unique_all, unique_counts, unique_inverse, unique_values
• Add: diff, tile, unstack, flip, repeat, take, take_along_axis

Phase 3: Behavioral Conformance

• Type promotion per spec
• std/var with correction parameter
• Ensure broadcasting follows spec exactly

Phase 4: Extensions

• Complete linalg extension
• Add fft extension

Device Model

public class Device {
    public static Device CPU { get; } = new Device("cpu");
}

public Device device => Device.CPU;

public NDArray to_device(Device device) {
    if (device != Device.CPU)
        throw new NotSupportedException("Only CPU supported");
    return this;
}

---

Compliance Summary

Category	Required	NumSharp
Creation	16	~14
Element-wise	67	~50
Data Types	6	~3
Linear Algebra	4	4
Manipulation	14	~10
Statistical	9	~7
Searching	6	~4
Sorting	2	2
Set	4	1
Indexing	2	0
Utility	3	2
Total Core	133	~80

---

References

• Array API Specification
• Type Promotion Rules

Related Issues

• #547 [NEP50 NEP52 NEP56] - NEP 56 covers Array API adoption in NumPy