NumPy

Setup

On first use, read setup.md for integration guidelines. Creates ~/numpy/ to store preferences and snippets.

When to Use

User needs numerical computing in Python. Agent handles array operations, mathematical computations, linear algebra, and data manipulation with NumPy.

Architecture

Memory lives in ~/numpy/. See memory-template.md for structure.

~/numpy/
├── memory.md      # Preferences + common patterns used
└── snippets/      # User's saved code patterns

Quick Reference

Core Rules

1. Vectorize First

Never use Python loops for array operations. NumPy's vectorized operations are 10-100x faster.

# BAD - Python loop
result = []
for x in arr:
    result.append(x * 2)

# GOOD - Vectorized
result = arr * 2

2. Understand Broadcasting

Broadcasting allows operations on arrays of different shapes. Know the rules:

• Dimensions align from the right
• Size-1 dimensions stretch to match
• Missing dimensions treated as size-1

# Shape (3,1) + (4,) broadcasts to (3,4)
a = np.array([[1], [2], [3]])  # (3,1)
b = np.array([10, 20, 30, 40])  # (4,)
result = a + b  # (3,4)

3. Prefer Views Over Copies

Slicing returns views (same memory). Use .copy() only when needed.

# View - modifying b changes a
b = a[::2]

# Copy - independent
b = a[::2].copy()

4. Use Appropriate Dtypes

Choose the smallest dtype that fits your data. Saves memory and speeds up computation.

# For integers 0-255
arr = np.array(data, dtype=np.uint8)

# For floats that don't need double precision
arr = np.array(data, dtype=np.float32)

5. Axis Awareness

Most functions accept axis parameter. Know your axes:

• axis=0: operate along rows (down columns)
• axis=1: operate along columns (across rows)
• axis=None or omit: operate on flattened array

arr = np.array([[1, 2], [3, 4]])
np.sum(arr, axis=0)  # [4, 6] - sum each column
np.sum(arr, axis=1)  # [3, 7] - sum each row

6. Leverage Built-in Functions

NumPy has optimized functions for common operations. Don't reinvent them.

NumPy Traps

Shape Mismatches

# TRAP: Confusing (n,) with (n,1) or (1,n)
a = np.array([1, 2, 3])      # shape (3,)
b = np.array([[1, 2, 3]])    # shape (1,3)
c = np.array([[1], [2], [3]])  # shape (3,1)

# FIX: Use reshape or newaxis
a.reshape(-1, 1)  # (3,1)
a[np.newaxis, :]  # (1,3)

Silent Type Coercion

# TRAP: Integer array silently truncates floats
arr = np.array([1, 2, 3])  # int64
arr[0] = 1.9  # becomes 1, not 1.9!