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!

# FIX: Declare dtype upfront
arr = np.array([1, 2, 3], dtype=np.float64)

View vs Copy Confusion

# TRAP: Fancy indexing returns copy, slicing returns view
arr = np.array([1, 2, 3, 4, 5])

# This is a VIEW (changes affect original)
view = arr[1:4]

# This is a COPY (independent)
copy = arr[[1, 2, 3]]

Broadcasting Surprises

# TRAP: Unexpected broadcasting
a = np.array([1, 2, 3])
b = np.array([1, 2])
a + b  # ERROR - shapes don't broadcast

# TRAP: Accidental broadcasting
a = np.zeros((3, 4))
b = np.array([1, 2, 3])
a + b  # ERROR - (3,4) and (3,) don't align
a + b.reshape(-1, 1)  # Works - (3,4) and (3,1)

In-Place Operations

# TRAP: Some operations modify in-place, others don't
np.sort(arr)        # Returns sorted copy
arr.sort()          # Sorts in-place

# Safe pattern: be explicit
arr = np.sort(arr)  # Clear intent

Essential Patterns

Create Arrays

np.zeros((3, 4))           # All zeros
np.ones((3, 4))            # All ones
np.full((3, 4), 7)         # All sevens
np.eye(3)                  # Identity matrix
np.arange(0, 10, 2)        # [0, 2, 4, 6, 8]
np.linspace(0, 1, 5)       # [0, 0.25, 0.5, 0.75, 1]
np.random.rand(3, 4)       # Uniform [0,1)
np.random.randn(3, 4)      # Normal distribution

Reshape and Stack

arr.reshape(2, 6)          # New shape (must match size)
arr.flatten()              # 1D copy
arr.ravel()                # 1D view
np.concatenate([a, b])     # Join along existing axis
np.stack([a, b])           # Join along new axis
np.vstack([a, b])          # Stack vertically
np.hstack([a, b])          # Stack horizontally

Boolean Indexing

arr = np.array([1, 5, 3, 8, 2])
mask = arr > 3
arr[mask]                  # [5, 8]
arr[arr > 3] = 0           # Replace values > 3 with 0
np.where(arr > 3, 1, 0)    # 1 where >3, else 0

Linear Algebra

np.dot(a, b)               # Matrix multiplication
a @ b                      # Same (Python 3.5+)
np.linalg.inv(a)           # Inverse
np.linalg.det(a)           # Determinant
np.linalg.eig(a)           # Eigenvalues/vectors
np.linalg.solve(a, b)      # Solve Ax = b

Security & Privacy

Data that stays local:

• All computations run locally
• Code patterns saved in ~/numpy/

This skill does NOT:

• Send data externally
• Access files outside ~/numpy/
• Require network connectivity

Related Skills

Install with clawhub install <slug> if user confirms:

• data — data processing workflows
• math — mathematical computations
• statistics — statistical analysis

Feedback

• If useful: clawhub star numpy
• Stay updated: clawhub sync