Metadata-Version: 2.4
Name: warpSPHBoundaries
Version: 0.1.0
Summary: Exact SPH boundary integrals via divergence-theorem edge reductions (2D), scene layer and delta+-SPH / DFSPH solvers on analytic boundaries
License: MIT
Project-URL: Repository, https://github.com/wi-re/warpSPHBoundaries
Project-URL: Issues, https://github.com/wi-re/warpSPHBoundaries/issues
Keywords: sph,smoothed-particle-hydrodynamics,boundary-conditions,warp,pytorch,analytic-boundaries
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: mpmath
Requires-Dist: torch
Requires-Dist: warp-lang
Requires-Dist: warpSPHCore>=0.6.0
Provides-Extra: solvers
Requires-Dist: warpSPH>=0.6.0; extra == "solvers"
Requires-Dist: warpSPHCore>=0.6.0; extra == "solvers"
Provides-Extra: scripts
Requires-Dist: matplotlib; extra == "scripts"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# curvatureBoundaries

Curvature-aware closed forms for the semi-analytic SPH boundary integral of
Winchenbach, Akhunov & Kolb (2020),

```
lambda(x) = Int_{D_B(x)} W(|x-x'|, h) dx',     W(r,h) = C_n/h^n W_hat(r/h)
```

extended beyond the paper's 3-D planar cubic-spline result to:

* **2-D planar** boundaries for all four kernels — new arccos/ln closed forms
  (`maple/01_planar.mpl`, §3 of `docs/derivation.md`);
* **3-D planar** Wendland kernels w2/w4/w6 — single polynomials of degree 2n
  via the monomial basis `F(n,p,x)`;
* **curved boundaries**: solid sphere for the Wendland kernels — both
  branches (`2R+d >= 1` and `2R+d < 1`) are rational `N(R,d)/(R+d)`, with
  exact planar limit `R -> infinity`.

Kernels and conventions follow warpSPHCore
(`src/warpSPHCore/kernels/`, `scripts/kernels/kernel_specs.yaml`):
`q = r/h` with `h` the support radius.

## Layout

```
maple/00_setup.mpl          kernel table, normalization, F(n,p,x) basis checks
maple/01_planar.mpl         2-D + 3-D planar, all kernels
maple/03_sphere.mpl         solid sphere (Wendland w2/w4/w6)
maple/run_all.sh            regenerate src/warpSPHBoundaries/data/symbolic/ (needs Maple 2026)
src/warpSPHBoundaries/curvbound/              PLAN track: kernel table, closed-form evaluators, oracles (curvature-aware planar / sphere integrals)
src/warpSPHBoundaries/edge/         HANDOFF track: exact 2D edge-reduction integrals (mpmath -> numpy -> torch -> Warp), FEM weights, tiers 3 / 4
src/warpSPHBoundaries/scene/        bodies and representations, boundary operations, wall operators of the delta+-SPH solver, the boundary provider (`AnalyticBoundary`, `scene/provider.py`)
src/warpSPHBoundaries/data/tables/  pre-tabulated tier-3 kernel tables (package data)
src/warpSPHBoundaries/sim/          DFSPH2D and DeltaSPH2D solvers, cases, validation runners
scripts/                    command-line runners (regression harness, profiler, validation, videos), scripts/studies, scripts/bench
tests/                      pytest suite: tests/{edge,scene,sim,curvbound} (940 tests)
notebooks/demo.ipynb        executed demo: geometry, curves, validation
notebooks/examples/         nine example flows (Taylor-Green ... flow past a cylinder) on the delta+ and the DFSPH solver, against reference solutions
docs/derivation.md          full mathematical write-up
PLAN.md                     project status & roadmap
src/warpSPHBoundaries/data/symbolic/  Maple exports (committed, shipped with the package; consumed by warpSPHBoundaries.curvbound)
results/figures/            notebook figures (generated, git-ignored)
```

## Package layering

`edge` <- `scene` <- `sim`: the edge machinery and the scene layer (`pip install .`, needs `warpSPHCore` only) are the boundary library `warpSPHBoundaries` (renamed from `edgebound` on 2026-10-06); `sim` (the reference
solvers) additionally needs `warpSPH`.  A scheme consumes the analytic bodies through `warpSPHBoundaries.scene.AnalyticBoundary` (the `BoundaryProvider` protocol: integrals at the fluid particles, signed distance,
body kinematics); see docs/audit-warpsph-boundary-hooks.md.  The layering is enforced by `tests/test_package_layering.py`.

## Quick start

```bash
# 1. (re)generate the symbolic results — needs Maple 2026
maple/run_all.sh                       # MAPLE=/path/to/maple to override

# 2. install (editable) and run the validation suite; the solvers need warpSPH / warpSPHCore in the same env
pip install -e . --no-deps          # or: pip install -e .[test]
python -m pytest tests/ -q -n 4     # ~3 min with pytest-xdist; GPU tests use cuda:0

# 3. run the demo notebook (jupyter + matplotlib)
python -m jupyter nbconvert --to notebook --execute --inplace \
    notebooks/demo.ipynb --ExecutePreprocessor.kernel_name=python3
```

Python API sketch:

```python
from fractions import Fraction
from curvbound import planar2d, planar3d, sphere

planar3d("w4", Fraction(1, 3))          # exact rational (polynomial in d)
planar2d("w4", "0.3")                   # mpf (arccos/ln closed form)
sphere("w4", Fraction(4, 10), Fraction(1, 5))   # solid ball R=0.4, d=0.2
```

## Validation

Every closed form is validated three ways (details in `docs/derivation.md`
§5): exact symbolic identities in Maple, 50-digit Maple quadrature, and
independent 40-digit mpmath oracles in `src/warpSPHBoundaries/curvbound/oracle.py`
(including a true 2-D Cartesian quadrature and the h-scaling identity).
Worst observed error: ~1e-39.

## Status

3-D planar (cubic + Wendland) and 3-D spherical (Wendland) were completed in
the original plan; the 2-D derivations, the promotion of the toy harnesses
to this repository layout, and the demo notebook are done (see `PLAN.md`
§18–§18c). Next: cylinder boundary, 2-D circle boundary, inside-solid
(`d < 0`) cases, gradient terms.
