pypr/pysph

1. What this repository is

PySPH is a computational framework for Smoothed Particle Hydrodynamics, built around a Python front end with performance-critical kernels implemented in Cython and OpenCL. The architecture is designed so users describe problems in high-level Python, while the framework generates and runs optimized numerical code.

2. Primary execution path

A typical simulation flows from an Application into a Solver, which coordinates time stepping, output, and controller logic. The solver drives one or more Scheme/Equation sets, coupled with an Integrator, over particle data stored in ParticleArray objects.

3. Core numerical layer

The pysph.sph package is the main SPH formulation layer. It contains the abstraction for equations, integrators, and step objects, plus concrete implementations for many SPH variants: weakly compressible SPH, incompressible SPH, gas dynamics, solid mechanics, surface tension, rigid bodies, and shallow-water equations. This is where the mathematical model is expressed independently of any one example.

4. Particle and neighborhood infrastructure

The pysph.base package provides the low-level computational backbone: particle arrays, kernel functions, point/tree utilities, and multiple nearest-neighbor particle search (NNPS) implementations. Several NNPS backends are present, including linked-list, cell-indexing, octree, spatial-hash, Z-order, and GPU-oriented variants. These structures are essential because most SPH operations depend on neighborhood queries.

5. Generated and accelerated code

A major architectural boundary is the code-generation layer. Many performance-sensitive parts have Cython or Mako-template variants, and the package includes helpers for generating Cython/OpenCL code for acceleration evaluation and integration. The readme and file layout show that PySPH compiles user-defined Python-level equations into faster runtime code, and stores generated source under ~/.pysph/source.

6. Parallel and GPU execution

Parallelism is split across several mechanisms. OpenMP is used for shared-memory CPU parallelism, the OpenCL path supports GPU execution, and the pysph.parallel package handles distributed execution concerns such as load balancing, remote exchange, and reductions. The readme also calls out Zoltan/PyZoltan support for parallel partitioning.

7. Boundary-condition subsystem

Boundary handling is its own subsystem under pysph.sph.bc, with multiple styles implemented as separate modules: do-nothing, mirror, characteristic, hybrid, and modified do-nothing. This boundary layer plugs into the SPH equation/evaluator pipeline rather than being hardcoded into examples.

8. Domain-specific formulation packages

Several subpackages specialize the generic SPH core for particular physics domains: gas_dynamics, wc, isph, swe, solid_mech, surface_tension, and rigid_body. These provide reusable equation sets, closures, and formulation-specific helpers that examples build on top of.

9. Examples as integration templates

The pysph.examples package demonstrates how the framework is assembled end-to-end. Examples define geometry, particle initialization, equations, boundary conditions, and solver settings, then run through the same Application/Solver pipeline used by real simulations. The examples also serve as a functional reference for the architecture.

10. I/O, output, and post-processing

Solver output is handled in pysph.solver.output and related modules, with VTK/XDMF utilities available for downstream visualization and data exchange. The pysph.tools package includes converters, interpolators, viewers, and mesh/geometry helpers, which means post-processing is treated as part of the overall workflow rather than an external concern.

11. CLI and user entry points

The pysph.tools.cli and pysph.examples.run components expose command-line workflows such as running examples and viewing output. This makes the framework usable as both a library and a simulation application, with CLI commands acting as the top-level orchestration interface.

12. Testing, docs, and release structure

The repository is organized with extensive unit/integration tests under each major package, Sphinx documentation under docs/, and CI workflows for standard and MPI-enabled builds. Packaging files (pyproject.toml, setup.py, MANIFEST.in) and Docker/starcluster assets indicate that reproducible builds and deployment across environments are part of the project’s operational architecture.