| --- |
| library_name: kernels |
| license: apache-2.0 |
| --- |
| |
| # surf |
|
|
| GPU kernels for breaking ocean waves, loadable through `kernels`: a |
| nonlinear shallow-water solver for the surf zone and a weakly-compressible |
| SPH solver for the overturn. The reference standards are the lake-at-rest |
| equilibrium, held to a part in a million, and an independent torch |
| implementation of the shallow-water right-hand side. |
|
|
| A swell passes through two regimes on its way to shore, and no single |
| formulation covers both. A height field can shoal a wave, steepen it, and |
| break it into whitewater, but `eta(x, y)` is a function, so it can never |
| overturn: a barrel is a multivalued surface with air inside it. Particles |
| can. This kernel ships the phase-resolved surf-zone hydrodynamics and the |
| Lagrangian solver together, so a wave can be carried from the shelf to the |
| tube, at a fifth of a millisecond per shallow-water step and 13.5 million |
| SPH particles. |
|
|
| <video src="https://huggingface.co/kernels/phanerozoic/surf/resolve/main/media/hero.mp4" autoplay loop muted playsinline controls width="100%"> |
| <img src="https://huggingface.co/kernels/phanerozoic/surf/resolve/main/media/hero.gif" alt="A swell propagating across a shoaling bed, refracting over a reef and decaying toward the beach"> |
| </video> |
|
|
| *A 9-second swell driven across a 256 x 448 bed that shoals from 9 m to the |
| beach over a submerged reef: crests steepen and refract, the reef throws a |
| diffraction pattern downwave, and energy decays through the surf zone. On |
| the same bed a still sea holds to 3.5e-6 m/s and 4.8e-7 m, which is what |
| well-balancing means; the step costs 0.15 ms.* |
|
|
| ## Usage |
|
|
| ```python |
| import torch |
| from kernels import get_kernel |
| |
| surf = get_kernel("phanerozoic/surf", version=1, trust_remote_code=True) |
| |
| # surf zone: shoal and break a swell over bathymetry (b = bed elevation) |
| for _ in range(nsteps): |
| h, hu, hv = surf.nsw_step(h, hu, hv, b, dx, dy, dt, cf=0.004) |
| eta = h + b # free surface; h = 0 is dry sand |
| |
| # overturning: WCSPH forces (pos/vel [N,3], ptype 0=fluid 1=wall) |
| perm, cs, ce = surf.build_cells(pos, origin, csz, grid) |
| pos, vel, rho, ptype = pos[perm], vel[perm], rho[perm], ptype[perm] |
| drho, acc, xsph = surf.sph_forces(pos, vel, rho, ptype, cs, ce, |
| grid, origin, csz, h=hsm, mass=mass, c0=c0) |
| ``` |
|
|
| `version` selects the release branch; `trust_remote_code` is required by |
| `kernels` for publishers without the trusted-publisher mark. |
|
|
| ## API |
|
|
| | Symbol | Purpose | |
| |---|---| |
| | `nsw_step(h, hu, hv, b, dx, dy, dt, cf)` | one nonlinear shallow-water step over bathymetry `b`; returns updated `(h, hu, hv)` | |
| | `nsw_rhs(...)` | the shallow-water right-hand side alone | |
| | `build_cells(pos, origin, csz, grid)` | uniform spatial-hash build; returns `(perm, cell_start, cell_end)` | |
| | `sph_forces(pos, vel, rho, ptype, cs, ce, grid, origin, csz, h, mass, c0)` | WCSPH forces; returns `(drho, acc, xsph)` | |
|
|
| ## Method |
|
|
| `nsw_rhs` / `nsw_step` solve the Saint-Venant equations with well-balanced |
| hydrostatic reconstruction, MUSCL (minmod) reconstruction, HLL fluxes, and |
| wet/dry runup, which shoals a swell over real bathymetry and breaks it as |
| bores. `sph_forces` / `build_cells` run 3D weakly-compressible SPH over a |
| uniform spatial hash: continuity with delta-SPH density diffusion, a Tait |
| equation of state, artificial viscosity, and XSPH. Well-balancing is the |
| property that matters most: a scheme without it spins up currents from the |
| bed slope alone, and a still sea over a reef never settles. |
|
|
| ## Correctness |
|
|
| | check | result | |
| |---|---| |
| | lake-at-rest over an uneven bed | max \|u\| = 3.5e-6 m/s, max \|eta\| = 4.8e-7 m | |
| | radial dam break | finite, bounded; 4-fold asymmetry 3.4e-5 | |
| | `nsw_rhs` vs an independent torch reference | 8.8e-5 relative (float32 op ordering) | |
| | SPH isolated particle | accelerates at exactly `-g`, no spurious lateral force | |
|
|
| The lake-at-rest figure is measured against the published build, so it |
| reproduces from a bare `get_kernel`. |
|
|
| ## Measured |
|
|
| | case | result | |
| |---|---| |
| | `nsw_step`, 256 x 448 | 0.15 ms/call (RTX 3070 Ti) | |
| | `nsw_rhs`, 384 x 768 | 0.06 ms/call (RTX 6000 Ada), 0.13 (3070 Ti) | |
| | SPH scale | 13.5M particles at ~95 ms/step (RTX 6000 Ada) | |
|
|
| ## Requirements and limits |
|
|
| - float32, CUDA, compute capability 8.0+, Linux x86_64 (the kernel builder |
| emits no Windows variants). |
| - Shallow-water fields are `[Ny, Nx]`; x is cross-shore (zero-gradient), y |
| is longshore (periodic). `b` is bed elevation, `eta = h + b`, `h` is |
| depth. |
| - NSW is depth-averaged and non-dispersive: right for the surf zone, wrong |
| for deep-water swell propagation over long distances. |
| - SPH is weakly compressible; `c0` should be ~10x the fastest expected flow. |
| Resolving a plunging jet needs roughly `H/dp >= 25`; coarser and a wave |
| spills instead of tubing. |
| - `nsw_step` is explicit: `dt <= 0.3 * dx / max(|u| + sqrt(g*h))`. |
| |
| ## References |
| |
| Audusse et al., well-balanced hydrostatic reconstruction (2004); Harten, |
| Lax, van Leer (HLL) fluxes; Monaghan, weakly-compressible SPH; Antuono et |
| al., delta-SPH density diffusion. |
| |
| ## License |
| |
| Apache-2.0. |
| |
