The heart of the problem is a mismatch of scales. The Discrete Element Method, or DEM, has become the workhorse of computational granular physics since its development by Peter Cundall in 1971 and its landmark extension with Otto Strack in 1979. DEM applies Newton’s second law of motion to the centre of every particle and a force-displacement law at every contact, computing the trajectory of each grain through time. Collisions are typically modelled as viscoelastic spring-dashpot systems, capturing both the repulsive force and the dissipated kinetic energy. Coupled with Computational Fluid Dynamics in the early 1990s, DEM-CFD can now simulate landslides, debris flows, pyroclastic currents, riverbed transport and industrial powder handling with remarkable fidelity. But what the simulations deliver is a torrent of particle-scale data: individual velocities, individual forces, individual contacts. Science and engineering, however, speak the language of continuum fields such as pressure, stress, strain rate and density.

Bridging that gap requires a mathematical procedure known as coarse-graining, a discrete-to-continuum transformation in which macroscopic fields emerge as spatially weighted averages of microscopic quantities. Each particle contributes to the field at a given point according to a weighting function that spreads its influence over a small volume, effectively smearing the point-like mass of the particle into a smooth density. Crucially, the method makes no assumption that particles are spherical or rigid, and it works across flow regimes from solid-like quasi-static behaviour to fluid-like rapid flow. The theoretical foundations trace back to Babic’s 1997 averaging framework for granular media, itself inspired by spatio-temporal weighted averaging in molecular dynamics, and have been refined over decades to handle boundaries, scale dependence and polydisperse mixtures.

Despite this maturity, the software ecosystem has lagged. Some DEM packages, such as LAMMPS and MercuryDPM, include built-in coarse-graining capabilities. Others, notably the open-source MFiX-DEM developed by the United States National Energy Technology Laboratory, do not, forcing users to write custom post-processing code or contort their simulation outputs to fit other tools. That fragmentation, the Edinburgh team argues, hampers reproducibility and invites error propagation. Pysammos, whose name nods to Archimedes’ The Sand Reckoner and his attempt to count the grains of sand that could fill the universe, was built to fill this void: a user-friendly, computationally efficient Python package that reads MFiX-DEM output directly and produces continuum fields ready for analysis and visualisation.

Technically, the package implements the full weighted-average machinery. It computes the mass density, momentum density and velocity fields, and it evaluates the stress tensor as the sum of a contact part and a kinetic part. Contact forces are distributed along the branch vector connecting two touching particles through a line integral of the weighting function, which Pysammos evaluates numerically with a trapezoidal rule that the authors show is already converged with just ten sampling points. Users can choose among three smoothing kernels: the Lucy polynomial, a cut-off Gaussian and a Heaviside step function. The authors recommend the Lucy function, because the Heaviside kernel weights all particles in the averaging volume equally and thereby amplifies edge effects, while the truncated Gaussian technically violates the differentiability required for the continuum balance equations to hold exactly.

The choice of smoothing width, the resolution at which the continuum fields are computed, turns out to be anything but trivial. The kinetic stress tensor is intrinsically dependent on the square of the averaging width, because it captures velocity gradients between a particle’s position and the evaluation point. Previous work has identified two length scales at which coarse-grained fields become nearly independent of the averaging width: one below the particle scale, which can resolve thin flow layers near boundaries, and one at the particle scale, which yields smooth fields. Pysammos adopts a default smoothing width of 0.75 times a representative particle diameter, but the team stresses that users should verify the stability of their results for their particular flow regime.

One of the package’s most distinctive features is its automated phase detection. In polydisperse mixtures, particles segregate by size and density through competing mechanisms known as kinetic sieving and buoyancy. Pysammos clusters the particle data by diameter and density using the k-means algorithm, selecting the optimal number of phases via silhouette analysis, and then computes partial continuum fields for each phase separately. Mixture theory then superposes these partial fields to recover the bulk behaviour. The team demonstrated this on a simulated granular pile confined between walls, revealing the classic stress-arching phenomenon: instead of the hydrostatic pressure maximum a fluid would show beneath the pile’s peak, the basal pressure exhibits a local minimum because force chains redirect the weight sideways toward the flanks.

The showcase applications span the geosciences. A bedload transport simulation of polydisperse, non-spherical grains under travelling water waves revealed bands of elevated shear rate and inertial number at the wave fronts, invisible in the raw contact network. A high-speed impact on a million-particle granular bed, relevant to cratering on asteroids and seismology alike, showed a downward-propagating shock wave and a friction coefficient exceeding the static value around the impact zone. A pseudo-2D simulation of crystals suspended in magma flowing through a conduit quantified how the effective shear viscosity varies with wall friction. And an erodible-bed experiment reproduced the classic Bagnold velocity profile, with granular temperature increasing toward the base where grains rattle against a rough floor.

Benchmarking against established coarse-graining software, including MercuryCG, EDEM’s continuum analysis, Granulysed and Iota-Suite, showed that Pysammos reproduces the expected fields, with results from its Gaussian and Lucy kernels coinciding closely with MercuryCG’s weighted averaging scheme. Performance tests on the ARCHER2 supercomputer showed that the cost per particle decreases sub-linearly with system size, meaning overheads are amortised and caches are used efficiently. Efficient execution does not demand massive parallel resources: at sub-particle resolution a couple of cores suffice, while large dense packings at coarser resolution benefit from four to sixteen cores. That makes the tool practical on ordinary desktop machines as well as high-performance clusters, lowering the barrier for research groups without dedicated computing infrastructure.

The team positions Pysammos as a contribution to a broader effort to standardise and streamline DEM post-processing across an inherently interdisciplinary community spanning geosciences, engineering and physics. Future versions are planned to read data from other DEM packages such as LAMMPS and YADE, to offer more flexible meshing beyond the current structured cuboid grid, and to account for the effect of hard boundaries on the contact stress tensor. Work is also under way with the MFiX developers to enable rigorous coarse-graining of glued-sphere particles, which approximate irregular shapes such as angular volcanic ash. For a field in which the second-most-handled material by weight in global industry, behind only water, still defies a unified description, a well-documented, open-source bridge from grain to continuum may prove a quietly transformative piece of infrastructure.

Subject of Research: A discrete-to-continuum coarse-graining software tool for analysing the rheology of granular materials from DEM simulations

Article Title: Pysammos 1.0.0: a discrete-to-continuum transformation Python tool to analyse the rheology of granular materials

Article References: Pysammos 1.0.0: a discrete-to-continuum transformation Python tool to analyse the rheology of granular materials. (n.d.). https://doi.org/10.5194/gmd-19-9519-2026

Image Credits: AI Generated

DOI: 10.5194/gmd-19-9519-2026

Keywords: granular flows, Pysammos, Discrete Element Method, coarse-graining, rheology, DEM-CFD, MFiX, geohazards, sediment transport, open-source software, computational physics, continuum mechanics