numpy-best-practices

---
name: numpy-best-practices
description: Best practices for NumPy array programming, numerical computing, and performance optimization in Python
license: Apache-2.0
---

# NumPy Best Practices

Expert guidelines for NumPy development, focusing on array programming, numerical computing, and performance optimization.

## Code Style and Structure

- Write concise, technical Python code with accurate NumPy examples
- Prefer vectorized operations over explicit loops for performance
- Use descriptive variable names reflecting data content (e.g., `weights`, `gradients`, `input_array`)
- Follow PEP 8 style guidelines for Python code
- Use functional programming patterns when appropriate

## Array Creation and Manipulation

- Use appropriate array creation functions: `np.array()`, `np.zeros()`, `np.ones()`, `np.empty()`, `np.arange()`, `np.linspace()`
- Prefer `np.zeros()` or `np.empty()` for pre-allocation when array size is known
- Use `np.concatenate()`, `np.vstack()`, `np.hstack()` for combining arrays
- Leverage broadcasting for operations on arrays with different shapes

## Indexing and Slicing

- Use advanced indexing with boolean arrays for conditional selection
- Prefer views over copies when possible to save memory
- Use `np.where()` for conditional element selection
- Understand the difference between fancy indexing (creates copy) and basic slicing (creates view)

## Data Types

- Specify appropriate data types explicitly using `dtype` parameter
- Use `np.float32` for memory-efficient computations when full precision is not needed
- Be aware of integer overflow with fixed-size integer types
- Use `np.asarray()` for type conversion without unnecessary copies

## Performance Optimization

### Vectorization

- Always prefer vectorized operations over Python loops
- Use NumPy universal functions (ufuncs) for element-wise operations
- Leverage `np.einsum()` for complex tensor operations
- Use `np.dot()` or `@` operator for matrix multiplication

### Memory Management

- Use `np.ndarray.flags` to check memory layout (C-contiguous vs Fortran-contiguous)
- Prefer in-place operations with `out` parameter when possible
- Use memory-mapped arrays (`np.memmap`) for large datasets
- Be mindful of array copies vs views

### Computation Efficiency

- Use `np.sum()`, `np.mean()`, `np.std()` with `axis` parameter for aggregations
- Leverage `np.cumsum()`, `np.cumprod()` for cumulative operations
- Use `np.searchsorted()` for efficient sorted array operations

## Error Handling and Validation

- Validate input shapes and data types before computations
- Use assertions for dimension checking with informative messages
- Handle NaN and Inf values appropriately with `np.isnan()`, `np.isinf()`
- Use `np.errstate()` context manager for controlling floating-point error handling

## Random Number Generation

- Use `np.random.default_rng()` for modern random number generation
- Set seeds for reproducibility: `rng = np.random.default_rng(seed=42)`
- Prefer the new Generator API over legacy `np.random` functions
- Use appropriate distributions: `rng.normal()`, `rng.uniform()`, `rng.choice()`

## Linear Algebra

- Use `np.linalg` for linear algebra operations
- Leverage `np.linalg.solve()` instead of computing inverse for linear systems
- Use `np.linalg.eig()`, `np.linalg.svd()` for decompositions
- Check matrix condition with `np.linalg.cond()` before inversion

## Testing and Documentation

- Write unit tests using `pytest` with `np.testing` assertions
- Use `np.testing.assert_array_equal()` for exact comparisons
- Use `np.testing.assert_array_almost_equal()` for floating-point comparisons
- Include comprehensive docstrings following NumPy docstring format

## Key Conventions

- Import as `import numpy as np`
- Use `snake_case` for variables and functions
- Document array shapes in docstrings
- Profile code with `%timeit` to identify bottlenecks