vectorcalculus 0.3.0
Small pure-Python vector calculus utilities
License: MIT
Requires Python: >=3.8

# vectorcalculus

Small pure-Python vector calculus utilities.

Usage example:

```py
from vectorcalculus import Vector, gradient, divergence, curl

v = Vector(1,2,3)
print(v.norm())

def f(p):
    x,y,z = p
    return x*y + z*z

print(gradient(f, (1.0,2.0,3.0)))
```

More examples
-------------

Pointwise (pure-Python) usage
```py
from vectorcalculus import Vector, gradient, divergence

v = Vector(2, -1, 0.5)
print("norm:", v.norm())

def scalar_field(p):
    x, y, z = p
    return x * y + z**2

g = gradient(scalar_field, (1.0, 2.0, -0.3))
print("gradient:", g)

def vec_field(p):
    x, y, z = p
    return (x**2, y**2, z**2)

print("divergence:", divergence(vec_field, (0.5, 0.2, -0.1)))
```

NumPy-vectorized usage (grids)
```py
import numpy as np
from vectorcalculus import mesh, gradient_on_grid, divergence_on_grid, curl_on_grid

# 2D grid
x = np.linspace(0, 1, 101)
y = np.linspace(-1, 1, 201)
X, Y = mesh(x, y)

def f(X, Y):
    return X * Y + 2 * Y**2

gx, gy = gradient_on_grid(f, x, y)

# 3D curl on grid
z = np.linspace(0, 0.5, 51)
def G(X, Y, Z):
    return (-Y, X, np.zeros_like(X))

curl = curl_on_grid(G, x, y, z)
print("curl shape:", curl.shape)  # spatial shape + last dim = 3
```

Running tests
--------------
Install dev deps and run:

```bash
python -m pip install -r requirements.txt    # if you add one
./.venv/Scripts/python.exe -m pytest -q
```

Additional examples
-------------------
See `examples/vectorcalculus_examples.ipynb` for more demonstrations:

- `Vector` utilities: `angle_with`, `proj_onto`, `cross`
- NumPy-accelerated operators: `gradient_np`, `divergence_np`, `curl_np`
- Grid helpers: `mesh`, `points_array`, `gradient_on_grid`, `curl_on_grid`

Integrals and theorem verifiers
-------------------------------
Numeric integrals and verifiers are provided:

```py
from vectorcalculus import line_integral, surface_integral, stokes_verifier, divergence_verifier_box
import math

# Work integral of F along a circle
def F(p):
    x, y, z = p
    return (-y, x, 0)

def boundary(t):
    return (math.cos(t), math.sin(t), 0.0)

circ = line_integral(F, boundary, 0.0, 2*math.pi, vector_field=True)
print('circulation:', circ)

# Verify Stokes on unit disk
res = stokes_verifier(F, boundary, 0.0, 2*math.pi,
                      lambda u, v: (u*math.cos(v), u*math.sin(v), 0.0),
                      0.0, 1.0, 0.0, 2*math.pi)
print(res)

# Divergence theorem on unit cube
def G(p):
    x, y, z = p
    return (x, y, z)

res2 = divergence_verifier_box(G, 0,1, 0,1, 0,1)
print(res2)
```

Symbolic helpers (SymPy)
------------------------
If `sympy` is installed you can compute symbolic gradient/divergence/curl:

```py
from sympy import symbols
from vectorcalculus import sympy_gradient, sympy_divergence

x, y, z = symbols('x y z')
f = x**2 + y*z
print(sympy_gradient(f, (x,y,z)))
```

Visualization (Matplotlib)
--------------------------
Helpers for quick visualization are available (requires `matplotlib`):

```py
from vectorcalculus import plot_vector_field_2d, plot_streamlines_2d

def F(p):
    x, y = p
    return (-y, x)

plot_vector_field_2d(F, (-2,2), (-2,2), nx=25, ny=25, save='quiver.png')
plot_streamlines_2d(F, (-2,2), (-2,2), density=1.0, nx=200, ny=200, save='stream.png')
```

Command-line demos
------------------
Example scripts in `examples/` support a `--show` flag to display plots
interactively via Matplotlib on a local desktop. By default the scripts
save PNGs into `examples/` so they can run headlessly (CI or servers).

Save images (non-interactive):

```bash
python examples/visualization_demo.py
python examples/complete_demo.py
```

Show interactively (local desktop):

```bash
python examples/visualization_demo.py --show
python examples/complete_demo.py --show
```