Numpy Python

NumPy Python

Produce NumPy code whose array shape, axis meaning, dtype, broadcasting, ownership, mutation, missing/nonfinite policy, and numerical accuracy are explicit and tested.

Know the array contract

Shape is not just dimensions: assign a semantic name to each axis. A vector (n,), a column (n, 1), and a row (1, n) broadcast and multiply differently. Dtype governs range, precision, missing representation, byte order, and memory. Read the ndarray, axis, dtype, and ownership model.

Ordered workflow

1. Recover input/output shape, named axis meaning, dtype, units, mutability, ownership, and nonfinite/missing policy from callers and tests.
2. Normalize with np.asarray when copying is unnecessary, or np.array(..., copy=True) when independent ownership is part of the API.
3. State the intended broadcast using shape algebra; insert axes explicitly with None/np.newaxis, expand_dims, or reshape.
4. Use ufuncs, reductions, indexing, matrix operations, or an operation family matched to the semantic axis; avoid np.vectorize as a performance fix.
5. Control accumulation/result dtype when overflow or precision matters.
6. Make copy/view and mutation behavior explicit at every slice, reshape, transpose, fancy index, astype, and boundary conversion.
7. Test empty axes, singleton axes, noncontiguous views, integer limits, mixed dtypes, NaN/infinity, aliasing, and invalid shapes.

Rigorous numerical contract

Separate four stages and report which ones actually ran:

Classify error sources before changing code: model error, input/measurement error, discretization error, sampling error, conditioning, and floating-point roundoff require different remedies. Do not call a result accurate merely because execution completed or two printed values look close.

Before computing, nondimensionalize or rescale when magnitudes differ enough to harm conditioning. Prefer a stable algebraic formulation over higher precision; use higher precision only when the error budget requires it and the selected NumPy dtype/backend supplies it. Choose tolerances from units, scale, conditioning, algorithm, and consequence—never from allclose defaults alone.

Read rigorous numerical practice for the full checklist and reusable anchors for diagnosed linear solves, stable normalization, and reproducible Monte Carlo estimates.

Choose by intent

Read operations, broadcasting, and numerical rules.

Canonical anchor

import numpy as np
import numpy.typing as npt


def standardize_columns(values: npt.ArrayLike) -> np.ndarray:
    array = np.asarray(values, dtype=np.float64)
    if array.ndim != 2:
        raise ValueError(f"expected (rows, features), got {array.shape}")
    mean = array.mean(axis=0, keepdims=True)
    scale = array.std(axis=0, keepdims=True)
    if np.any(scale == 0) or not np.all(np.isfinite(scale)):
        raise ValueError("every feature must have finite, nonzero scale")
    return (array - mean) / scale

axis=0 aggregates rows to one statistic per feature; keepdims=True makes the subsequent (rows, features) - (1, features) broadcast auditable. The function returns a new floating array and rejects constant/nonfinite scale by policy.

High-risk rules

• Broadcasting compares trailing dimensions; dimensions match when equal or one is 1. Use np.broadcast_shapes in validation when shape compatibility is a public contract. Avoid a broadcast that creates a huge intermediate.
• Basic slicing normally returns a view; advanced integer/boolean indexing returns a copy. Chained indexing can therefore mutate—or fail to mutate—the original unexpectedly. Assign with one indexed operation when mutation is intended.
• reshape returns a view where possible and a copy otherwise. Never promise zero-copy without checking layout/strides or enforcing a contiguous contract.
• Dtype promotion can overflow integers, lose precision, or convert mixed data to object/string. Declare input, accumulation, and output dtypes for critical code.
• NaN, positive/negative infinity, masked values, and absence are different policies. Integer arrays cannot represent NaN without changing dtype.
• np.empty is uninitialized. Write every element before reading it.
• np.vectorize is a convenience loop, not native vectorized performance. Prefer ufunc/array algebra, generalized ufuncs, compiled kernels, or a clear outer loop that controls memory.
• Use default_rng/Generator injected into functions. Test invariants and fixed-stream reproducibility, not one global np.random.seed trace.
• For linear algebra, validate shapes, rank/conditioning, and residuals. Prefer solving systems to explicit inverse multiplication.
• Do not mutate .shape or .dtype attributes to reinterpret data. Use reshape, astype, or view(dtype=...) only when their different semantics are intended.
• A small residual is backward-error evidence, not automatically a small solution error when the problem is ill-conditioned. Report both conditioning and a scale-aware residual.
• For discretized algorithms, vary resolution and check convergence before trusting the finest result. If refinement stops helping, investigate roundoff, instability, or model error instead of extrapolating blindly.
• For stochastic work, inject Generator, record the stream construction and sample count, and report sampling uncertainty. A fixed seed makes a run reproducible; it does not make an estimator correct.

Performance and interoperability

Before optimizing, measure allocations and representative shapes. Prefer array operations but control temporaries with staged computation or out= only when aliasing/casting is safe. Memory order, strides, and contiguity affect native libraries; copying once at a boundary may beat repeated strided work.

At pandas, Polars, Arrow, JAX, CuPy, Torch, or buffer boundaries, define device, ownership, writable state, dtype, shape, zero-copy claim, and lifetime. “Array like” does not guarantee a NumPy-owned CPU buffer.

Version grounding and completion

The stable online docs currently identify NumPy 2.5, and the foundry evaluator is pinned to NumPy 2.5.2. Check the target project's installed version with np.__version__, then inspect the migration guide and signature before relying on promotion, string dtype, copy keywords, random, or Array API behavior. Read verification.

Completion requires exact shape/axis/dtype/ownership contracts; broadcast and mutation behavior proven on adversarial shapes/views; nonfinite and overflow policy tested; numeric algorithms checked by residual/tolerance; and no hidden object dtype, unintended copy, or global RNG dependency.

References

• ndarray, axis, dtype, and ownership model
• Operations, broadcasting, and numerical rules
• Rigorous numerical practice
• Verification and API grounding