Guides
Executable notebooks explain mpiarray from array creation through complete simulations. Read the rendered pages with their generated figures, or download a notebook to run and change it yourself. Longer setup and plotting cells can be expanded with Show code.
- Distributed arrays — creation, storage, gathering and files.
- Layouts — decomposition, ownership and redistribution.
- Domain decomposition — how the array is split: process grid, cuts, neighbours and halos, with figures and an interactive explorer.
- Halo exchange — boundaries, stencils and deposition.
- Operations and reductions — arithmetic, indexing and collective operations.
- GPU arrays — CuPy and CUDA-aware MPI, with CPU-compatible examples.
- PETSc — DMDAs, vector transfers and numbering.
- Sparse stencil operators — fixed-pattern operators and PETSc matrices.
- xarray — labels, coordinates and generated plots.
- Using physical units — compatible arithmetic, assignments and reductions.
- Heat equation — a complete stencil simulation.
- Particles — migration and deposition.
- Building, reducing and saving arrays — rank-local data and I/O.
For notebook authoring and code-folding tags, see Building the docs.
Distributed arrays
A DistributedArray is a global array of which each rank stores only the block it owns, plus an optional frame of halo cells. You create one with a function named like its NumPy counterpart:

Layouts
Every DistributedArray has a layout: an immutable description of how its global shape is split over the ranks of a communicator. The creation functions build it from their split, halo, periodic, comm…

Domain decomposition
How mpiarray splits an array over the ranks of an MPI job, step by step: the process grid, the cut points along each axis, the numbering of the ranks and their neighbours, and the halo cells around…
Halo exchange
Halo cells hold copies of, or contributions to, cells that belong to a neighbouring rank. A halo can be at most as wide as the smallest block along its axis (it is filled from the neighbouring block…
Operations and reductions
A distributed array behaves like a NumPy array for elementwise arithmetic and reductions. Elementwise operations run on each rank's block without communication; reductions combine the blocks with one…
GPU arrays
mpiarray creates its arrays through cunumpy, which is NumPy or CuPy depending on the selected backend. The same script runs on the CPU and on the GPU; only the backend changes.
PETSc
mpiarray.petsc connects layouts and arrays to petsc4py, so that KSP, SNES and TS can work on mpiarray data without a second, hand-made decomposition. It needs petsc4py, which is not a dependency of…
Sparse stencil operators
mpiarray.StencilOperator represents a linear operator given by a small, fixed set of neighbour offsets -- the pattern a finite-difference stencil has -- without ever storing a sparse matrix: apply…

xarray
a.toxarray(dims, ...) gathers an array (like gather/tonumpy) and labels the result as an xarray.DataArray, for plotting or further analysis with xarray-based tools. It needs xarray, which is not a…
Physical units
Attach physical units to distributed arrays, combine compatible quantities, and reduce them to unit-bearing scalars. This guide follows energy and volume samples through an energy-density…

Heat equation
The 2D heat equation \partialt u = \alpha \nabla^2 u, solved with a five-point stencil on a grid split over the MPI ranks. Each step updates the halo cells from the neighbours, with a zero-flux…

Particles
Particle-in-cell codes keep particles with the rank that owns the grid cell they are in, and deposit their charge on the grid. This guide moves particles in a periodic 2D box, sends each one to its…

Working with data
Simulation data usually starts on the ranks that computed it. This guide builds distributed arrays from those pieces with fromlocal, reduces them along axes, reads parts of them, and writes them to…
Nothing matches.