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
| Concept |
Runtime meaning |
Required decision |
ndarray |
Homogeneous, fixed-size multidimensional elements plus shape/strides/dtype metadata. |
Define every axis and dtype. |
| scalar / 0-D array |
Python/NumPy scalar or shape == () array. |
Preserve the caller's return type deliberately. |
| view |
New array metadata sharing an underlying buffer. |
Mutation can affect another array. |
| copy |
Independently owned data buffer. |
Pay allocation cost when ownership isolation is needed. |
| ufunc |
Elementwise operation supporting broadcasting, dtype loops, out, and reductions. |
Check promotion and nonfinite behavior. |
Generator |
Explicit random stream. |
Inject it; never depend on ambient global RNG state. |
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
- Recover input/output shape, named axis meaning, dtype, units, mutability,
ownership, and nonfinite/missing policy from callers and tests.
- Normalize with
np.asarray when copying is unnecessary, or np.array(..., copy=True) when independent ownership is part of the API.
- State the intended broadcast using shape algebra; insert axes explicitly
with
None/np.newaxis, expand_dims, or reshape.
- Use ufuncs, reductions, indexing, matrix operations, or an operation family
matched to the semantic axis; avoid
np.vectorize as a performance fix.
- Control accumulation/result dtype when overflow or precision matters.
- Make copy/view and mutation behavior explicit at every slice, reshape,
transpose, fancy index,
astype, and boundary conversion.
- 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:
| Stage |
Required output |
| Formulate |
Mathematical quantity, units, domain, semantic axes, assumptions, and invariants. |
| Compute |
Algorithm, dtype, scale, shape, memory cost, and failure policy. |
| Verify |
Residual, invariant, refinement, independent formulation, or known reference. |
| Interpret |
Evidence-supported conclusion plus unresolved model, sampling, or numerical error. |
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
| Intent |
Prefer |
Guard |
| Convert array-like |
asarray / array |
Copy, dtype, ragged input, and subclass policy. |
| Elementwise transform |
ufunc/operator |
Broadcasting, promotion, where, out. |
| Aggregate |
sum, mean, min, etc. |
Axis, keepdims, empty input, accumulation dtype. |
| Matrix product |
@ / matmul |
Batch axes and 1-D special cases. |
| Elementwise product |
* |
Never substitute for matrix multiplication. |
| Rearrange without changing elements |
transpose/moveaxis/reshape |
View/copy possibility and axis mapping. |
| Select by slices |
basic indexing |
Usually a view. |
| Select by integer/boolean arrays |
advanced indexing |
A copy; boolean shape must match its indexed axes. |
| Join/split arrays |
concatenate/stack/block/split families |
Existing versus newly inserted axis. |
| Random sampling |
injected np.random.Generator |
Seed/stream/shape and distribution parameterization. |
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
1---2name: numpy-python3description: Use for writing, reviewing, debugging, testing, or optimizing Python NumPy ndarray code. Trigger on array construction, shape/axis reasoning, dtypes and casting, broadcasting, indexing, copies/views, ufuncs, reductions, vectorization, random Generator, linear algebra, FFT, masked/structured arrays, memory layout, or NumPy interoperability. Do not use for pandas/Polars table semantics, JAX/CuPy-only arrays, symbolic SymPy, or pure Python sequences without a NumPy boundary.4argument-hint: "[NumPy array task, shape contract, code, or error]"5metadata:6 source: https://skillmd.com/skills/schattenspiegel/numpy-python7---89# NumPy Python1011Produce NumPy code whose array shape, axis meaning, dtype, broadcasting,12ownership, mutation, missing/nonfinite policy, and numerical accuracy are13explicit and tested.1415## Know the array contract1617| Concept | Runtime meaning | Required decision |18|---|---|---|19| `ndarray` | Homogeneous, fixed-size multidimensional elements plus shape/strides/dtype metadata. | Define every axis and dtype. |20| scalar / 0-D array | Python/NumPy scalar or `shape == ()` array. | Preserve the caller's return type deliberately. |21| view | New array metadata sharing an underlying buffer. | Mutation can affect another array. |22| copy | Independently owned data buffer. | Pay allocation cost when ownership isolation is needed. |23| ufunc | Elementwise operation supporting broadcasting, dtype loops, `out`, and reductions. | Check promotion and nonfinite behavior. |24| `Generator` | Explicit random stream. | Inject it; never depend on ambient global RNG state. |2526Shape is not just dimensions: assign a semantic name to each axis. A vector27`(n,)`, a column `(n, 1)`, and a row `(1, n)` broadcast and multiply28differently. Dtype governs range, precision, missing representation, byte order,29and memory. Read [the ndarray, axis, dtype, and ownership model](references/object-model.md).3031## Ordered workflow32331. Recover input/output shape, named axis meaning, dtype, units, mutability,34 ownership, and nonfinite/missing policy from callers and tests.352. Normalize with `np.asarray` when copying is unnecessary, or `np.array(...,36 copy=True)` when independent ownership is part of the API.373. State the intended broadcast using shape algebra; insert axes explicitly38 with `None`/`np.newaxis`, `expand_dims`, or reshape.394. Use ufuncs, reductions, indexing, matrix operations, or an operation family40 matched to the semantic axis; avoid `np.vectorize` as a performance fix.415. Control accumulation/result dtype when overflow or precision matters.426. Make copy/view and mutation behavior explicit at every slice, reshape,43 transpose, fancy index, `astype`, and boundary conversion.447. Test empty axes, singleton axes, noncontiguous views, integer limits,45 mixed dtypes, `NaN`/infinity, aliasing, and invalid shapes.4647## Rigorous numerical contract4849Separate four stages and report which ones actually ran:5051| Stage | Required output |52|---|---|53| Formulate | Mathematical quantity, units, domain, semantic axes, assumptions, and invariants. |54| Compute | Algorithm, dtype, scale, shape, memory cost, and failure policy. |55| Verify | Residual, invariant, refinement, independent formulation, or known reference. |56| Interpret | Evidence-supported conclusion plus unresolved model, sampling, or numerical error. |5758Classify error sources before changing code: model error, input/measurement59error, discretization error, sampling error, conditioning, and floating-point60roundoff require different remedies. Do not call a result accurate merely61because execution completed or two printed values look close.6263Before computing, nondimensionalize or rescale when magnitudes differ enough to64harm conditioning. Prefer a stable algebraic formulation over higher precision;65use higher precision only when the error budget requires it and the selected66NumPy dtype/backend supplies it. Choose tolerances from units, scale,67conditioning, algorithm, and consequence—never from `allclose` defaults alone.6869Read [rigorous numerical practice](references/recipes-rigorous-numerics.md)70for the full checklist and reusable anchors for diagnosed linear solves, stable71normalization, and reproducible Monte Carlo estimates.7273## Choose by intent7475| Intent | Prefer | Guard |76|---|---|---|77| Convert array-like | `asarray` / `array` | Copy, dtype, ragged input, and subclass policy. |78| Elementwise transform | ufunc/operator | Broadcasting, promotion, `where`, `out`. |79| Aggregate | `sum`, `mean`, `min`, etc. | Axis, `keepdims`, empty input, accumulation dtype. |80| Matrix product | `@` / `matmul` | Batch axes and 1-D special cases. |81| Elementwise product | `*` | Never substitute for matrix multiplication. |82| Rearrange without changing elements | transpose/moveaxis/reshape | View/copy possibility and axis mapping. |83| Select by slices | basic indexing | Usually a view. |84| Select by integer/boolean arrays | advanced indexing | A copy; boolean shape must match its indexed axes. |85| Join/split arrays | concatenate/stack/block/split families | Existing versus newly inserted axis. |86| Random sampling | injected `np.random.Generator` | Seed/stream/shape and distribution parameterization. |8788Read [operations, broadcasting, and numerical rules](references/operations.md).8990## Canonical anchor9192```python93import numpy as np94import numpy.typing as npt959697def standardize_columns(values: npt.ArrayLike) -> np.ndarray:98 array = np.asarray(values, dtype=np.float64)99 if array.ndim != 2:100 raise ValueError(f"expected (rows, features), got {array.shape}")101 mean = array.mean(axis=0, keepdims=True)102 scale = array.std(axis=0, keepdims=True)103 if np.any(scale == 0) or not np.all(np.isfinite(scale)):104 raise ValueError("every feature must have finite, nonzero scale")105 return (array - mean) / scale106```107108`axis=0` aggregates rows to one statistic per feature; `keepdims=True` makes the109subsequent `(rows, features) - (1, features)` broadcast auditable. The function110returns a new floating array and rejects constant/nonfinite scale by policy.111112## High-risk rules113114- Broadcasting compares trailing dimensions; dimensions match when equal or115 one is `1`. Use `np.broadcast_shapes` in validation when shape compatibility116 is a public contract. Avoid a broadcast that creates a huge intermediate.117- Basic slicing normally returns a view; advanced integer/boolean indexing118 returns a copy. Chained indexing can therefore mutate—or fail to mutate—the119 original unexpectedly. Assign with one indexed operation when mutation is intended.120- `reshape` returns a view where possible and a copy otherwise. Never promise121 zero-copy without checking layout/strides or enforcing a contiguous contract.122- Dtype promotion can overflow integers, lose precision, or convert mixed data123 to object/string. Declare input, accumulation, and output dtypes for critical code.124- `NaN`, positive/negative infinity, masked values, and absence are different125 policies. Integer arrays cannot represent `NaN` without changing dtype.126- `np.empty` is uninitialized. Write every element before reading it.127- `np.vectorize` is a convenience loop, not native vectorized performance.128 Prefer ufunc/array algebra, generalized ufuncs, compiled kernels, or a clear129 outer loop that controls memory.130- Use `default_rng`/`Generator` injected into functions. Test invariants and131 fixed-stream reproducibility, not one global `np.random.seed` trace.132- For linear algebra, validate shapes, rank/conditioning, and residuals. Prefer133 solving systems to explicit inverse multiplication.134- Do not mutate `.shape` or `.dtype` attributes to reinterpret data. Use reshape,135 `astype`, or `view(dtype=...)` only when their different semantics are intended.136- A small residual is backward-error evidence, not automatically a small137 solution error when the problem is ill-conditioned. Report both conditioning138 and a scale-aware residual.139- For discretized algorithms, vary resolution and check convergence before140 trusting the finest result. If refinement stops helping, investigate141 roundoff, instability, or model error instead of extrapolating blindly.142- For stochastic work, inject `Generator`, record the stream construction and143 sample count, and report sampling uncertainty. A fixed seed makes a run144 reproducible; it does not make an estimator correct.145146## Performance and interoperability147148Before optimizing, measure allocations and representative shapes. Prefer array149operations but control temporaries with staged computation or `out=` only when150aliasing/casting is safe. Memory order, strides, and contiguity affect native151libraries; copying once at a boundary may beat repeated strided work.152153At pandas, Polars, Arrow, JAX, CuPy, Torch, or buffer boundaries, define device,154ownership, writable state, dtype, shape, zero-copy claim, and lifetime. “Array155like” does not guarantee a NumPy-owned CPU buffer.156157## Version grounding and completion158159The stable online docs currently identify NumPy 2.5, and the foundry evaluator160is pinned to NumPy 2.5.2. Check the target project's installed version with161`np.__version__`, then inspect the migration guide and signature before relying162on promotion, string dtype, copy keywords, random, or Array API behavior. Read163[verification](references/verification.md).164165Completion requires exact shape/axis/dtype/ownership contracts; broadcast and166mutation behavior proven on adversarial shapes/views; nonfinite and overflow167policy tested; numeric algorithms checked by residual/tolerance; and no hidden168object dtype, unintended copy, or global RNG dependency.169170## References171172- [ndarray, axis, dtype, and ownership model](references/object-model.md)173- [Operations, broadcasting, and numerical rules](references/operations.md)174- [Rigorous numerical practice](references/recipes-rigorous-numerics.md)175- [Verification and API grounding](references/verification.md)