How it works

Struphy kernels

Struphy keeps the simulation and model logic in readable Python, while moving the tight loops over spline coefficients, grid cells and particles into small computational kernels. These functions are written once in Python and can run as Python during development or as compiled Fortran or C in a production simulation.

What is a kernel?

A kernel is a focused numerical routine that applies the same operation to many values: evaluate a basis function, multiply a stencil matrix by a vector, move a marker, or add marker weights to a grid. Kernels do not assemble a simulation or choose a time-stepping scheme. Propagators and models call them as the inner operations of a substep.

This separation keeps the high-level API expressive without putting Python's per-element loop overhead in the hot path. It also gives each operation a small, testable interface and makes the data movement and parallel loops explicit.

Kernel families

B-splines

struphy.bsplines.*_kernels

Evaluate basis functions, derivatives and tensor-product shape functions on one-, two- and three-dimensional grids.

FEEC

struphy.feec.*_kernels

Project fields into compatible finite-element spaces, apply mass operators and assemble local contributions.

Geometry

struphy.geometry.*_kernels

Evaluate mappings between logical and physical coordinates, transform fields and compute geometry factors.

Linear algebra

struphy.linear_algebra.*_kernels

Apply distributed stencil matrices and their transposes to the coefficient vectors used by field solvers.

Particles

struphy.pic.*_kernels

Push markers, evaluate fields at marker positions, deposit moments and currents, filter data and sort markers.

Particle-in-cell operations are split into pushing, sampling, accumulation, filtering and sorting modules. The numerical methods page explains how these operations couple finite-element fields to marker distributions.

From Python to a simulation

Write

A kernel is a small, typed Python function using the NumPy subset supported by Pyccel.

Discover

The compiler finds modules whose filenames contain “kernels” and records their dependencies.

Compile

Pyccel translates the functions to Fortran or C and builds shared libraries for the selected compiler.

Call

Struphy calls the compiled function through the same Python-facing module used by the simulation.

Compilation is incremental: Struphy stores the discovered kernel list and rebuilds the generated code when a source or dependency changes. The language, compiler family and OpenMP option are selected at compile time. If a kernel has not been compiled, its Python implementation remains available, which is useful for debugging and for tests.

struphy compile                  # compile kernels with Fortran
struphy compile --language c    # compile kernels with C
struphy compile --openmp        # enable OpenMP in the kernels
struphy compile --status        # show the compilation status
struphy compile --dependencies  # print kernels and dependencies

Parallel execution

Kernels are the layer where local work is parallelized. OpenMP can split loops over particles, cells or other independent entries on one node. MPI distributes the field grid and markers between ranks; the surrounding Struphy code handles marker migration, ghost-region exchange and reductions between kernel calls.

Compiled kernels do not change the mathematical method. The same spline basis, discrete operators and particle-to-grid rules are used in the Python and compiled paths, so compilation is a performance choice rather than a separate numerical scheme.

See Code and parallelization for the package layers, MPI decomposition, clones, profiling and the current GPU roadmap.