Metadata-Version: 2.4
Name: iterpdesolver
Version: 0.1.0
Summary: Iterative PDE solvers for 2D elliptic equations with finite differences
Project-URL: Homepage, https://github.com/michaelwallner/PoissonSolver
Project-URL: Repository, https://github.com/michaelwallner/PoissonSolver
Author: Michael Wallner
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: matplotlib>=3.6
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Provides-Extra: app
Requires-Dist: streamlit; extra == 'app'
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# iterpdesolver

Iterative PDE solvers for 2D elliptic equations with finite differences.

A Python library implementing 11 solver algorithms for second-order elliptic PDEs on uniform rectangular grids, including classical iterative methods, Krylov solvers, and multigrid methods.

Originally based on a [Bachelor thesis](docs/thesis.pdf) on iterative methods for the discrete Poisson equation (University of Regensburg), now extended to support multiple equation types.

## Installation

```bash
pip install iterpdesolver
```

Or install from source:

```bash
git clone https://github.com/michaelwallner/iterpdesolver.git
cd iterpdesolver
pip install -e ".[dev]"
```

## Quick Start

```python
import iterpdesolver as pde

result = pde.solve(
    equation=pde.Poisson(source=lambda x, y: -4.0),
    grid=pde.UniformGrid(nx=63, ny=63),
    boundary=pde.DirichletBC(lambda x, y: x**2 + y**2),
    solver="cg",
    tol=1e-6,
)

print(f"Converged in {result.iterations} iterations ({result.time_seconds:.3f}s)")
print(f"Residual: {result.residual_norm:.2e}")
```

## Supported Equations

| Equation | Class | PDE |
|---|---|---|
| Poisson | `pde.Poisson(source)` | $-\nabla^2 u = f$ |
| Helmholtz | `pde.Helmholtz(source, k)` | $-\nabla^2 u + k^2 u = f$ |
| Convection-Diffusion | `pde.ConvectionDiffusion(source, diffusion, velocity)` | $-D\nabla^2 u + \mathbf{v} \cdot \nabla u = f$ |
| Heat (implicit Euler) | `pde.Heat(source, alpha, dt, u_prev)` | $u^{n+1}/\Delta t - \alpha \nabla^2 u^{n+1} = u^n/\Delta t + f$ |

## Available Solvers

| Solver | Key | Type |
|---|---|---|
| Direct (LU) | `"direct"` | Direct |
| Jacobi | `"jacobi"` | Iterative |
| Jacobi Relaxation | `"jacobi_relaxation"` | Iterative |
| Gauss-Seidel | `"gauss_seidel"` | Iterative |
| SOR | `"sor"` | Iterative |
| Conjugate Gradient | `"cg"` | Krylov |
| PCG (ILU) | `"pcg_ilu"` | Krylov |
| PCG (MILU) | `"pcg_milu"` | Krylov |
| Two-Grid | `"two_grid"` | Multigrid |
| V-Cycle | `"v_cycle"` | Multigrid |
| W-Cycle | `"w_cycle"` | Multigrid |

## SolveResult

Every solver returns a `SolveResult` with:

- `solution` — 1D numpy array of interior point values
- `iterations` — number of iterations (0 for direct solver)
- `time_seconds` — wall-clock solve time
- `residual_norm` — final residual norm
- `converged` — whether tolerance was met
- `residual_history` — list of residual norms per iteration
- `plot(grid=...)` — quick matplotlib surface plot

## Examples

```bash
python examples/basic_poisson.py
python examples/solver_comparison.py
python examples/helmholtz_example.py
```

### Streamlit App

```bash
pip install iterpdesolver[app]
streamlit run examples/streamlit_app/app.py
```

## Testing

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

## License

MIT
