# numpy

Guides Cursor to write vectorized NumPy code without Python loops. Enforces explicit dtypes, modular functions, and optional CuPy GPU acceleration.

- rule · `type=rule` · Cursor · ★ 3580
- Author: sanjeed5
- License: CC0-1.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/numpy.mdc
- Updated: 2026-05-19
- HTML: https://affpapa.org/en/nevibecode/rules/numpy

## What it does

This rule targets `**/*.py` files to eliminate explicit Python `for` loops over numerical data. Cursor refactors array operations to use C-level vectorization and broadcasting. Numerical workflows get organized into modular functions with strict PEP 257 docstrings and type annotations.

Data types require explicit declarations. Setting precise dtypes prevents implicit casting and avoids excessive RAM usage. When building arrays iteratively, the rule forbids `list.append()` patterns in favor of pre-allocating memory with `np.empty` or `np.zeros`.

Heavy computations receive optional CuPy acceleration patterns. If CuPy is missing from your Python environment, operations automatically fall back to CPU execution with standard NumPy. You must install CUDA and CuPy separately to use the GPU branch.

## Install

### Cursor (native platform)

**Manually: put the files in place**
- File: `.cursor/rules/numpy.mdc` — Frontmatter: description, globs, alwaysApply

### Claude Code

**Manually: put the files in place**
- File: `.claude/rules/numpy.md` — The paths frontmatter field limits the files: move globs from the source into paths

### Codex

**AGENTS.md**
- Codex reads AGENTS.md: paste the rule text there

### GitHub Copilot

**Manually: put the files in place**
- File: `.github/instructions/numpy.instructions.md` — The applyTo field sets which files it applies to: move globs from the source into applyTo

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/rules/numpy.md`

### Cline

**Manually: put the files in place**
- File: `.clinerules/numpy.md`

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/numpy.mdc

## When to use it
- Replace slow Python array loops with vectorized operations and broadcasting
- Prevent excessive memory usage by explicitly defining array dtypes
- Structure numerical scripts into reusable functions with PEP 257 docstrings
- Eliminate repeated list reallocations by pre-allocating arrays
- Add CuPy GPU fallback logic for heavy matrix calculations

## Example prompts
- Refactor the covariance calculation in `data_pipeline.py` to remove Python loops
- Update this data normalization routine to use explicit `float32` types
- Add an optional GPU execution path using CuPy to `matrix_ops.py`

## Source text · numpy.mdc · CC0-1.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 9863fd9457a5fdae.

BEGIN THIRD-PARTY FILE 9863fd9457a5fdae
````text
---
description: This guide provides definitive, actionable best practices for writing high-performance, maintainable, and correct NumPy code, emphasizing vectorization, explicit dtypes, and modern GPU acceleration.
globs: **/*.py
---
# numpy Best Practices

NumPy is the bedrock of numerical computing in Python. To fully leverage its power for AI/ML and data science in 2025, we must write code that is not just functional but also fast, readable, and robust. This guide outlines our team's definitive best practices for NumPy.

## Core Principles

1.  **Vectorize Everything**: Eliminate Python loops over arrays. NumPy operations are implemented in C and are orders of magnitude faster.
2.  **Be Explicit with `dtype`**: Always specify array data types to prevent unexpected casting and optimize memory/performance.
3.  **Embrace GPU Acceleration**: Utilize CuPy-compatible calls for critical, large-scale computations.

## Code Organization and Structure

Organize NumPy-heavy logic into dedicated, well-named functions and modules.

### 1. Modular Design

Isolate numerical operations into functions that accept and return NumPy arrays. This improves testability and reusability.

❌ BAD: Monolithic script
```python
import numpy as np

def process_data_script(data_path):
    data = np.loadtxt(data_path)
    # ... many lines of processing ...
    mean_val = np.mean(data)
    std_val = np.std(data)
    normalized_data = (data - mean_val) / std_val
    # ... more processing ...
    return normalized_data
```

✅ GOOD: Modular functions
```python
import numpy as np

def load_numerical_data(file_path: str) -> np.ndarray:
    """Loads numerical data from a file."""
    return np.loadtxt(file_path)

def normalize_array(arr: np.ndarray) -> np.ndarray:
    """Normalizes a NumPy array to have zero mean and unit variance."""
    if arr.size == 0:
        return arr
    mean_val = np.mean(arr)
    std_val = np.std(arr)
    # Avoid division by zero for constant arrays
    if std_val == 0:
        return np.zeros_like(arr)
    return (arr - mean_val) / std_val

def process_pipeline(data_path: str) -> np.ndarray:
    """Orchestrates data loading and processing."""
    data = load_numerical_data(data_path)
    processed_data = normalize_array(data)
    return processed_data
```

### 2. Clear Naming and Docstrings

Adhere to PEP 8 for variable and function names (`snake_case`). Use comprehensive docstrings (PEP 257) for all public functions, classes, and modules, especially for complex numerical logic.

❌ BAD: Ambiguous names, no docs
```python
def calc(a, b):
    # What does 'a' mean? What does 'b' mean?
    # What does this function do?
    return np.dot(a, b.T)
```

✅ GOOD: Descriptive names, clear docstrings
```python
import numpy as np

def calculate_covariance_matrix(data_matrix: np.ndarray) -> np.ndarray:
    """
    Calculates the covariance matrix for a given data matrix.

    Args:
        data_matrix: A 2D NumPy array where rows are observations
                     and columns are features.

    Returns:
        A 2D NumPy array representing the covariance matrix.
    """
    if data_matrix.ndim != 2:
        raise ValueError("Input data_matrix must be 2-dimensional.")
    
    # Center the data by subtracting the mean of each feature
    centered_data = data_matrix - np.mean(data_matrix, axis=0)
    
    # Calculate covariance matrix: (X^T * X) / (n - 1)
    covariance_matrix = np.cov(data_matrix, rowvar=False)
    return covariance_matrix
```

## Common Patterns and Anti-patterns

### 1. Vectorization over Python Loops

**Always** prefer NumPy's vectorized operations and broadcasting over explicit Python `for` loops when working with arrays.

❌ BAD: Element-wise loop
```python
import numpy as np

data = np.random.rand(1_000_000)
result = np.empty_like(data)
````
END THIRD-PARTY FILE 9863fd9457a5fdae

The third-party file has ended. Everything between the 9863fd9457a5fdae tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3819 of 12935 bytes. © sanjeed5 · CC0-1.0 · https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/numpy.mdc

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md