# pypr/pysph architecture

> Architecture diagram of the GitHub repository pypr/pysph, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pypr/pysph
- Repository: https://github.com/pypr/pysph

## Overview

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.

Main entry points: [`pysph/solver/solver.py`](https://github.com/pypr/pysph/blob/main/pysph/solver/solver.py) (Solver), [`pysph/sph/__init__.py`](https://github.com/pypr/pysph/blob/main/pysph/sph/__init__.py) (SPH Core), [`pysph/sph/scheme.py`](https://github.com/pypr/pysph/blob/main/pysph/sph/scheme.py) (Scheme), [`pysph/base/particle_array.pyx`](https://github.com/pypr/pysph/blob/main/pysph/base/particle_array.pyx) (Particle Array)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app["Application<br/>orchestrator<br/>[application.py]"]
  node_solver["Solver<br/>time-stepping engine<br/>[solver.py]"]
  node_controller["Controller<br/>run control<br/>[controller.py]"]
  node_output["Output<br/>results I/O<br/>[output.py]"]
end

subgraph group_numerics["Numerics"]
  node_sph_core["SPH Core<br/>formulation layer<br/>[__init__.py]"]
  node_equations["Equations<br/>math model<br/>[equation.py]"]
  node_integrator["Integrator<br/>[integrator.py]"]
  node_scheme["Scheme<br/>problem setup<br/>[scheme.py]"]
  node_accel["Codegen<br/>generated kernels"]
  node_bc["Boundaries<br/>BC subsystem<br/>[__init__.py]"]
  node_wc["Weakly Compressible<br/>domain package<br/>[__init__.py]"]
  node_isph["Incompressible<br/>domain package<br/>[__init__.py]"]
  node_specialized["Specialized SPH<br/>domain package<br/>[__init__.py]"]
end

subgraph group_infra["Infrastructure"]
  node_particle[("Particle Array<br/>particle data<br/>[particle_array.pyx]")]
  node_nnps["NNPS<br/>neighbor search<br/>[nnps.py]"]
  node_tree["Tree<br/>spatial index<br/>[tree.py]"]
  node_kernels["Kernels<br/>kernel math<br/>[kernels.py]"]
  node_parallel["Parallel<br/>distributed execution"]
end

subgraph group_usage["Usage"]
  node_tools["Tools<br/>utilities<br/>[cli.py]"]
  node_examples["Examples<br/>reference apps<br/>[run.py]"]
  node_docs["Docs<br/>documentation<br/>[index.rst]"]
  node_ops["Build & CI<br/>project ops<br/>[pyproject.toml]"]
end

node_app -->|"starts"| node_solver
node_solver -->|"uses"| node_controller
node_solver -->|"advances"| node_integrator
node_solver -->|"evaluates"| node_equations
node_solver -->|"writes"| node_output
node_solver -->|"parallelizes"| node_parallel
node_sph_core -->|"defines"| node_equations
node_sph_core -->|"defines"| node_integrator
node_sph_core -->|"defines"| node_scheme
node_sph_core -->|"compiles"| node_accel
node_equations -->|"extends"| node_bc
node_scheme -->|"specializes"| node_wc
node_scheme -->|"specializes"| node_isph
node_scheme -->|"specializes"| node_specialized
node_particle -->|"queried by"| node_nnps
node_nnps -->|"backed by"| node_tree
node_particle -->|"combined with"| node_kernels
node_accel -->|"operates on"| node_particle
node_parallel -->|"partitions"| node_nnps
node_tools -->|"post-processes"| node_output
node_examples -->|"invokes"| node_app
node_examples -->|"demonstrates"| node_scheme
node_docs -->|"documents"| node_sph_core
node_ops -->|"supports"| node_examples
node_ops -->|"supports"| node_docs

click node_app "https://github.com/pypr/pysph/blob/main/pysph/solver/application.py"
click node_solver "https://github.com/pypr/pysph/blob/main/pysph/solver/solver.py"
click node_controller "https://github.com/pypr/pysph/blob/main/pysph/solver/controller.py"
click node_output "https://github.com/pypr/pysph/blob/main/pysph/solver/output.py"
click node_sph_core "https://github.com/pypr/pysph/blob/main/pysph/sph/__init__.py"
click node_equations "https://github.com/pypr/pysph/blob/main/pysph/sph/equation.py"
click node_integrator "https://github.com/pypr/pysph/blob/main/pysph/sph/integrator.py"
click node_scheme "https://github.com/pypr/pysph/blob/main/pysph/sph/scheme.py"
click node_accel "https://github.com/pypr/pysph/blob/main/pysph/sph/acceleration_eval.py"
click node_bc "https://github.com/pypr/pysph/blob/main/pysph/sph/bc/__init__.py"
click node_wc "https://github.com/pypr/pysph/blob/main/pysph/sph/wc/__init__.py"
click node_isph "https://github.com/pypr/pysph/blob/main/pysph/sph/isph/__init__.py"
click node_specialized "https://github.com/pypr/pysph/blob/main/pysph/sph/gas_dynamics/__init__.py"
click node_particle "https://github.com/pypr/pysph/blob/main/pysph/base/particle_array.pyx"
click node_nnps "https://github.com/pypr/pysph/blob/main/pysph/base/nnps.py"
click node_tree "https://github.com/pypr/pysph/blob/main/pysph/base/tree/tree.py"
click node_kernels "https://github.com/pypr/pysph/blob/main/pysph/base/kernels.py"
click node_parallel "https://github.com/pypr/pysph/blob/main/pysph/parallel/parallel_manager.pyx"
click node_tools "https://github.com/pypr/pysph/blob/main/pysph/tools/cli.py"
click node_examples "https://github.com/pypr/pysph/blob/main/pysph/examples/run.py"
click node_docs "https://github.com/pypr/pysph/blob/main/docs/source/index.rst"
click node_ops "https://github.com/pypr/pysph/blob/main/pyproject.toml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_solver,node_controller,node_output toneBlue
class node_sph_core,node_equations,node_integrator,node_scheme,node_accel,node_bc,node_wc,node_isph,node_specialized toneAmber
class node_particle,node_nnps,node_tree,node_kernels,node_parallel toneMint
class node_tools,node_examples,node_docs,node_ops toneRose
```

## Components

### Runtime

Top-level orchestration and execution flow

- [Application](https://github.com/pypr/pysph/blob/main/pysph/solver/application.py): orchestrator · Entry point that configures and launches simulations · `pysph/solver/application.py`
- [Solver](https://github.com/pypr/pysph/blob/main/pysph/solver/solver.py): time-stepping engine · Coordinates stepping, controllers, and output · `pysph/solver/solver.py`
- [Controller](https://github.com/pypr/pysph/blob/main/pysph/solver/controller.py): run control · High-level simulation control and lifecycle management · `pysph/solver/controller.py`
- [Output](https://github.com/pypr/pysph/blob/main/pysph/solver/output.py): results I/O · Stores solver output and supports VTK/XDMF export · `pysph/solver/output.py`

### Numerics

SPH formulations and accelerated evaluation

- [SPH Core](https://github.com/pypr/pysph/blob/main/pysph/sph/__init__.py): formulation layer · Shared abstractions for equations, integrators, schemes, and compilation · `pysph/sph/__init__.py`
- [Equations](https://github.com/pypr/pysph/blob/main/pysph/sph/equation.py): math model · Base equation definitions and boundary equations · `pysph/sph/equation.py`
- [Integrator](https://github.com/pypr/pysph/blob/main/pysph/sph/integrator.py): time integrator · Integration framework and step objects · `pysph/sph/integrator.py`
- [Scheme](https://github.com/pypr/pysph/blob/main/pysph/sph/scheme.py): problem setup · Reusable formulation and solver-setup interface · `pysph/sph/scheme.py`
- [Codegen](https://github.com/pypr/pysph/blob/main/pysph/sph/acceleration_eval.py): generated kernels · Cython/OpenCL acceleration helpers and equation evaluation generation · `pysph/sph/acceleration_eval.py`
- [Boundaries](https://github.com/pypr/pysph/blob/main/pysph/sph/bc/__init__.py): BC subsystem · Inlet, outlet, interpolation, and boundary-condition variants · `pysph/sph/bc/__init__.py`
- [Weakly Compressible](https://github.com/pypr/pysph/blob/main/pysph/sph/wc/__init__.py): domain package · WCSPH formulations and corrections · `pysph/sph/wc/__init__.py`
- [Incompressible](https://github.com/pypr/pysph/blob/main/pysph/sph/isph/__init__.py): domain package · ISPH and IISPH formulations · `pysph/sph/isph/__init__.py`
- [Specialized SPH](https://github.com/pypr/pysph/blob/main/pysph/sph/gas_dynamics/__init__.py): domain package · Gas dynamics, solid mechanics, surface tension, rigid body, and shallow-water formulations · `pysph/sph/gas_dynamics/__init__.py`

### Infrastructure

Particle data, neighborhood search, parallelism, and I/O

- [Particle Array](https://github.com/pypr/pysph/blob/main/pysph/base/particle_array.pyx): particle data · Core particle-state container used by SPH computations · `pysph/base/particle_array.pyx`
- [NNPS](https://github.com/pypr/pysph/blob/main/pysph/base/nnps.py): neighbor search · Nearest-neighbor particle search abstractions and backends · `pysph/base/nnps.py`
- [Tree](https://github.com/pypr/pysph/blob/main/pysph/base/tree/tree.py): spatial index · Point/tree utilities supporting neighborhood queries · `pysph/base/tree/tree.py`
- [Kernels](https://github.com/pypr/pysph/blob/main/pysph/base/kernels.py): kernel math · SPH kernel functions and supporting linear algebra · `pysph/base/kernels.py`
- [Parallel](https://github.com/pypr/pysph/blob/main/pysph/parallel/parallel_manager.pyx): distributed execution · Parallel manager, load balancing, exchange, and reductions · `pysph/parallel/parallel_manager.pyx`

### Usage

Examples, tools, docs, and operational assets

- [Tools](https://github.com/pypr/pysph/blob/main/pysph/tools/cli.py): utilities · CLI, conversion, interpolation, viewers, packing, and geometry tools · `pysph/tools/cli.py`
- [Examples](https://github.com/pypr/pysph/blob/main/pysph/examples/run.py): reference apps · End-to-end simulation templates across the supported physics domains · `pysph/examples/run.py`
- [Docs](https://github.com/pypr/pysph/blob/main/docs/source/index.rst): documentation · Sphinx docs, tutorials, and design notes · `docs/source/index.rst`
- [Build & CI](https://github.com/pypr/pysph/blob/main/pyproject.toml): project ops · Packaging, Docker, and GitHub Actions for reproducible builds and testing · `pyproject.toml`

## Connections

- Application → Solver: starts · Applications construct and launch solver runs
- Solver → Controller: uses · Solver delegates lifecycle and runtime control
- Solver → Integrator: advances · Time stepping is performed through integrators
- Solver → Equations: evaluates · Solver execution applies equation sets over particles
- Solver → Output: writes · Solver emits state and results through output modules
- Solver → Parallel: parallelizes · Solver may run with distributed or OpenMP-backed execution
- SPH Core → Equations: defines · Core package exposes equation abstractions
- SPH Core → Integrator: defines · Core package exposes integrator and step abstractions
- SPH Core → Scheme: defines · Core package provides the scheme interface
- SPH Core → Codegen: compiles · Core package includes generated acceleration paths
- Equations → Boundaries: extends · Boundary equations plug into the same evaluation pipeline
- Scheme → Weakly Compressible: specializes · Schemes assemble domain-specific formulations
- Scheme → Incompressible: specializes · Schemes assemble incompressible formulations
- Scheme → Specialized SPH: specializes · Schemes assemble gas, solid, rigid-body, and SWE formulations
- Particle Array → NNPS: queried by · Neighborhood search operates over particle arrays
- NNPS → Tree: backed by · Several NNPS variants use tree and spatial indexing structures
- Particle Array → Kernels: combined with · Particle interactions depend on kernel evaluation
- Codegen → Particle Array: operates on · Generated kernels evaluate particle data efficiently
- Parallel → NNPS: partitions · Parallel execution needs neighbor-aware domain decomposition
- Tools → Output: post-processes · Tools convert and visualize solver output
- Examples → Application: invokes · Examples are assembled and run through the application entry point
- Examples → Scheme: demonstrates · Examples show how physics formulations are composed
- Docs → SPH Core: documents · Docs cover architecture and solver interfaces
- Build & CI → Examples: supports · Packaging and CI make examples and builds reproducible
- Build & CI → Docs: supports · Documentation build and hosting are part of project operations