|
| 1 | +# kernelpack-python |
| 2 | + |
| 3 | +[](https://github.com/VarShankar/kernelpack-python/actions/workflows/python.yml) |
| 4 | +[](https://github.com/VarShankar/kernelpack-python/releases/latest) |
| 5 | +[](LICENSE) |
| 6 | +[](#requirements) |
| 7 | + |
| 8 | +**Meshfree geometry, RBF-FD, partition-of-unity methods, and PDE solvers for |
| 9 | +Python.** |
| 10 | + |
| 11 | +`kernelpack-python` provides Python implementations of meshfree geometry, |
| 12 | +scattered-node discretizations, and PDE solvers on embedded fixed domains. It |
| 13 | +combines reusable geometry and node-generation tools with standard and |
| 14 | +overlapped PHS+poly RBF-FD, weighted least squares, localized |
| 15 | +partition-of-unity approximations, and sparse elliptic and diffusion solvers. |
| 16 | + |
| 17 | +The package is the Python member of the KernelPack family. The companion |
| 18 | +[`kernelpack-matlab`](https://github.com/VarShankar/kernelpack-matlab) |
| 19 | +repository includes the moving-surface implementation accompanying the |
| 20 | +preprint [*A high-order, meshless, Lagrangian--Eulerian RBF-FD method for |
| 21 | +advection--diffusion--reaction on moving manifolds*](https://arxiv.org/abs/2608.19384) |
| 22 | +by Matthew Lowery, Grady B. Wright, and Varun Shankar. This Python release is |
| 23 | +focused on the fixed-domain numerical core and does not claim that |
| 24 | +moving-surface solver. |
| 25 | + |
| 26 | + |
| 27 | + |
| 28 | +The figure shows an end-to-end Poisson solve on a geometry-defined scattered |
| 29 | +node set: the geometric model supplies the boundary and normals, the node |
| 30 | +generator fills the domain, and PHS+poly RBF-FD supplies the differential and |
| 31 | +boundary operators. |
| 32 | + |
| 33 | +[Install](#installation) | [First solve](#first-solve) | |
| 34 | +[Examples](#examples) | [Tests](#verification) | |
| 35 | +[Papers](#research-foundations) | [Citation](#citation) |
| 36 | + |
| 37 | +## Who this is for |
| 38 | + |
| 39 | +This package is intended for numerical PDE researchers and Python users who |
| 40 | +want to: |
| 41 | + |
| 42 | +- prototype PHS+poly RBF-FD or weighted-least-squares discretizations; |
| 43 | +- generate scattered nodes and differential operators on embedded domains; |
| 44 | +- compare standard and overlapped local assembly; |
| 45 | +- solve elliptic and diffusion problems without constructing a volume mesh; |
| 46 | +- build localized PU or divergence-free RBF approximations; or |
| 47 | +- extend a tested, inspectable numerical research codebase. |
| 48 | + |
| 49 | +It is research software, not a general-purpose finite-element package. |
| 50 | + |
| 51 | +## At a glance |
| 52 | + |
| 53 | +| Component | What the public release provides | |
| 54 | +| --- | --- | |
| 55 | +| Geometry models | Smooth and piecewise-smooth embedded boundaries and surfaces, PHS geometric fits, RBF level sets, normals, projection, and geometry-aware bounding data | |
| 56 | +| Node generation | Seeded fixed- and variable-radius Poisson sampling in boxes, clipping by embedded geometry, boundary and ghost nodes, boundary-zone outer refinement, and dual node sets | |
| 57 | +| Local approximation | Centered and scaled Legendre polynomial bases, standard and overlapped PHS+poly RBF-FD, weighted-least-squares stencils, and local divergence-free PHS interpolation | |
| 58 | +| Fixed-domain solvers | Poisson, variable-coefficient and nonlinear variable-coefficient Poisson, BDF1--BDF3 diffusion, localized PU diffusion, and homogeneous or heterogeneous multispecies diffusion | |
| 59 | +| Numerical infrastructure | SciPy KD trees and sparse matrices, cached local polynomial templates, and targeted Numba kernels for repeated geometry, polynomial, and stencil calculations | |
| 60 | + |
| 61 | +The main namespaces are `kernelpack.geometry`, `kernelpack.nodes`, |
| 62 | +`kernelpack.domain`, `kernelpack.poly`, `kernelpack.rbffd`, |
| 63 | +`kernelpack.divfree`, and `kernelpack.solvers`. |
| 64 | + |
| 65 | +## Requirements |
| 66 | + |
| 67 | +- Python 3.11 or newer |
| 68 | +- NumPy 2.0 or newer |
| 69 | +- SciPy 1.14 or newer |
| 70 | +- Numba 0.61 or newer |
| 71 | +- Matplotlib 3.9 or newer for examples and figures |
| 72 | + |
| 73 | +## Installation |
| 74 | + |
| 75 | +### Clone the repository |
| 76 | + |
| 77 | +```bash |
| 78 | +git clone https://github.com/VarShankar/kernelpack-python.git |
| 79 | +cd kernelpack-python |
| 80 | +python -m venv .venv |
| 81 | +``` |
| 82 | + |
| 83 | +Activate the environment on macOS or Linux: |
| 84 | + |
| 85 | +```bash |
| 86 | +source .venv/bin/activate |
| 87 | +``` |
| 88 | + |
| 89 | +Activate it on Windows: |
| 90 | + |
| 91 | +```powershell |
| 92 | +.venv\Scripts\Activate.ps1 |
| 93 | +``` |
| 94 | + |
| 95 | +Install the package and example dependencies: |
| 96 | + |
| 97 | +```bash |
| 98 | +python -m pip install -e ".[examples]" |
| 99 | +``` |
| 100 | + |
| 101 | +For development, install the test and build tools as well: |
| 102 | + |
| 103 | +```bash |
| 104 | +python -m pip install -e ".[dev]" |
| 105 | +``` |
| 106 | + |
| 107 | +## First solve |
| 108 | + |
| 109 | +This example constructs a disk from boundary samples, generates interior and |
| 110 | +ghost nodes, solves $-\Delta u = 4$ with $u=0$ on the boundary, and plots the |
| 111 | +numerical solution. |
| 112 | + |
| 113 | +```python |
| 114 | +import matplotlib.pyplot as plt |
| 115 | +import matplotlib.tri as mtri |
| 116 | +import numpy as np |
| 117 | + |
| 118 | +from kernelpack.geometry import EmbeddedSurface |
| 119 | +from kernelpack.nodes import DomainNodeGenerator |
| 120 | +from kernelpack.solvers import PoissonSolver |
| 121 | + |
| 122 | +t = np.linspace(0.0, 2.0 * np.pi, 200, endpoint=False) |
| 123 | +surface = EmbeddedSurface() |
| 124 | +surface.set_data_sites(np.column_stack([np.cos(t), np.sin(t)])) |
| 125 | +surface.build_closed_geometric_model_ps(2, 0.08, t.size) |
| 126 | +surface.build_level_set_from_geometric_model() |
| 127 | + |
| 128 | +generator = DomainNodeGenerator() |
| 129 | +domain = generator.build_domain_descriptor_from_geometry( |
| 130 | + surface, 0.08, seed=17, strip_count=5 |
| 131 | +) |
| 132 | + |
| 133 | +solver = PoissonSolver( |
| 134 | + lap_assembler="fd", |
| 135 | + bc_assembler="fd", |
| 136 | + lap_stencil="rbf", |
| 137 | + bc_stencil="rbf", |
| 138 | +) |
| 139 | +solver.init(domain, 4) |
| 140 | + |
| 141 | +forcing = lambda x: 4.0 * np.ones(x.shape[0]) |
| 142 | +neumann = lambda xb: np.zeros(xb.shape[0]) |
| 143 | +dirichlet = lambda xb: np.ones(xb.shape[0]) |
| 144 | +boundary_data = lambda neu, diri, normals, xb: np.zeros(xb.shape[0]) |
| 145 | +result = solver.solve(forcing, neumann, dirichlet, boundary_data) |
| 146 | + |
| 147 | +x = domain.get_int_bdry_nodes() |
| 148 | +tri = mtri.Triangulation(x[:, 0], x[:, 1]) |
| 149 | +plt.tripcolor(tri, result["u"], shading="gouraud") |
| 150 | +plt.gca().set_aspect("equal") |
| 151 | +plt.colorbar(label="u") |
| 152 | +plt.title("Poisson solution") |
| 153 | +plt.show() |
| 154 | +``` |
| 155 | + |
| 156 | + |
| 157 | + |
| 158 | +## Solver workflows |
| 159 | + |
| 160 | +All solvers use a `DomainDescriptor`, so geometry, node generation, and local |
| 161 | +operator construction remain separate from the PDE definition. A target |
| 162 | +spatial order `xi` determines the polynomial reproduction degree and the lower |
| 163 | +odd-degree PHS used by the local stencil builders. |
| 164 | + |
| 165 | +The elliptic solver family supports Dirichlet, Neumann, and mixed boundary |
| 166 | +rows. Pure-Neumann systems use an explicit null-space augmentation. The |
| 167 | +variable-coefficient solver assembles the divergence-form operator, while the |
| 168 | +nonlinear variant applies Newton iterations with sparse linear solves. |
| 169 | + |
| 170 | +`DiffusionSolver` advances fixed-domain problems with BDF1, BDF2, or BDF3 and |
| 171 | +reuses time-independent operators and preconditioners where possible. The PU |
| 172 | +variants localize approximation and support single- or multispecies diffusion, |
| 173 | +including distinct diffusivities by species. |
| 174 | + |
| 175 | + |
| 176 | + |
| 177 | +## Examples |
| 178 | + |
| 179 | +Complete convergence drivers live in [`examples`](examples): |
| 180 | + |
| 181 | +| Goal | Example | |
| 182 | +| --- | --- | |
| 183 | +| Verify a two-dimensional pure-Neumann Poisson solve | [`poisson_convergence_2d_neumann.py`](examples/poisson_convergence_2d_neumann.py) | |
| 184 | +| Verify a three-dimensional pure-Neumann Poisson solve | [`poisson_convergence_3d_neumann.py`](examples/poisson_convergence_3d_neumann.py) | |
| 185 | + |
| 186 | +Run a study from the repository root, for example: |
| 187 | + |
| 188 | +```bash |
| 189 | +python examples/poisson_convergence_2d_neumann.py --orders 2 4 6 |
| 190 | +``` |
| 191 | + |
| 192 | +Generated tables, JSON data, and figures are written under `artifacts/`, which |
| 193 | +is intentionally excluded from version control. The committed README figures |
| 194 | +can be regenerated with: |
| 195 | + |
| 196 | +```bash |
| 197 | +python scripts/render_readme_examples.py |
| 198 | +``` |
| 199 | + |
| 200 | +## Verification |
| 201 | + |
| 202 | +Install the development dependencies and run the complete public suite: |
| 203 | + |
| 204 | +```bash |
| 205 | +python -m pip install -e ".[dev]" |
| 206 | +python -m pytest -q |
| 207 | +``` |
| 208 | + |
| 209 | +The same suite runs on Python 3.11 and 3.12 in GitHub Actions for every push |
| 210 | +and pull request. |
| 211 | + |
| 212 | +## Research foundations |
| 213 | + |
| 214 | +`kernelpack-python` brings together methods developed across several papers. |
| 215 | +Please cite the publications corresponding to the parts of the library used in |
| 216 | +your work. |
| 217 | + |
| 218 | +| Code or method | Publication | |
| 219 | +| --- | --- | |
| 220 | +| Overlapped RBF-FD assembly (`kernelpack.rbffd.FDODiffOp`) | V. Shankar, [*The overlapped radial basis function-finite difference (RBF-FD) method: A generalization of RBF-FD*](https://doi.org/10.1016/j.jcp.2017.04.037), Journal of Computational Physics 342 (2017), 211--228 | |
| 221 | +| PHS geometric models and Poisson node generation (`kernelpack.geometry`, `kernelpack.nodes`) | V. Shankar, R. M. Kirby, and A. L. Fogelson, [*Robust node generation for mesh-free discretizations on irregular domains and surfaces*](https://doi.org/10.1137/17M114090X), SIAM Journal on Scientific Computing 40 (2018), A2584--A2608 | |
| 222 | +| Lower odd-degree PHS selection used by the solver stencil defaults | V. Shankar and A. L. Fogelson, [*Hyperviscosity-based stabilization for radial basis function-finite difference (RBF-FD) discretizations of advection-diffusion equations*](https://doi.org/10.1016/j.jcp.2018.06.036), Journal of Computational Physics 372 (2018), 616--639 | |
| 223 | + |
| 224 | +For moving-surface ADR, surface hyperviscosity, and the associated research |
| 225 | +drivers, see the public |
| 226 | +[`kernelpack-matlab`](https://github.com/VarShankar/kernelpack-matlab) |
| 227 | +release and its research-foundations table. |
| 228 | + |
| 229 | +## Citation |
| 230 | + |
| 231 | +Software citation metadata are provided in [`CITATION.cff`](CITATION.cff). |
| 232 | +Please also cite the method papers corresponding to the components used in |
| 233 | +your work. |
| 234 | + |
| 235 | +## Contributing |
| 236 | + |
| 237 | +Bug reports, focused pull requests, and reproducible numerical examples are |
| 238 | +welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the development workflow |
| 239 | +and [`SECURITY.md`](SECURITY.md) for responsible vulnerability reporting. |
| 240 | + |
| 241 | +## License |
| 242 | + |
| 243 | +`kernelpack-python` is released under the [BSD 3-Clause License](LICENSE), |
| 244 | +which permits academic and commercial use, modification, and redistribution |
| 245 | +subject to its terms. |
0 commit comments