The ongoing search for constitutive relations that unify the multifaceted behaviour of granular media is hindered by the breadth of complex characteristics and phenomenology of these materials. For instance, they encompass a wide distribution of particle sizes, shapes, roughnesses and elasticities, which control their macroscopic dynamic properties. Additionally, the spatial distribution of the properties of the granular medium may change throughout the course of the flow, due to granular segregation – where particles segregate by size, density, shape, and cohesive properties – or particle breakage .

Furthermore, they also exhibit a strong dependence on the characteristic length scale (i.e., particle size) . This implies that the role of the microscopic length scale may not vanish at the macroscopic continuum scale, that is, the particle size is of the same order of magnitude as the scale of spatial variation of macroscopic fields .

Granular flows also show evidence of recording deformation history, implying that a previous deformation episode predisposes the initial conditions of the material . For instance, a high-shear episode to a granular packing with an initially isotropic contact network can induce dilation and preferentially align the force chains. This new fabric alters the initial state for any subsequent deformation, usually providing a higher shear strength relative to the initially isotropic packing.

The role of the interstitial fluid introduces an additional level of complexity in multiphase granular flows. What is more, the interplay between the solid and fluid phases changes between dilute and dense suspensions . The rheology is particularly challenging to capture in non-colloidal dense suspensions, as classical viscosity laws begin to break down due to the increase in energy dissipation through particle contacts .

These aspects of granular flows render their continuum representation particularly difficult. Nonetheless, since the surge of computers, modelling of discrete particle systems has been made possible through the Discrete Element Method (DEM). Despite its computational limitation to small scale systems, it is an invaluable tool for simulating complex granular flows without involving any continuum assumptions.

The DEM explicitly applies Newton’s second law of motion to the particle centres and the force displacement law at the contacts, to compute trajectories of individual granular particles from the forces exerted on particles, and vice versa, over time periods in which accelerations are assumed to be constant . Collisions are assumed viscoelastic, conceptualised as a spring-dashpot system – whose components respectively represent the repulsive force and the dissipated kinetic energy – although other contact models have also been implemented .

DEM was first developed by for a rock mechanics application and was later extended by for applications in granular media. Later it began to be applied to molecular dynamics , and soil mechanics . Coupling of DEM with Computational Fluid Dynamics (CFD) began in the early 1990s with , widening the range of applications of DEM to the study of multiphase granular flows.

In recent decades, DEM has become a powerful tool to study numerous natural processes in the field of geosciences: seismic wave propagation in unconsolidated sediments ; impact cratering on granular asteroids ; emplacement of igneous intrusions ; magma mush dynamics ; erosion processes ; bedload transport ; probing granular flow rheology from the basal force function , and thermal-geomechanical coupling effects in geothermal reservoirs , amongst others.

An essential service of DEM is that of providing the accurate particle dynamics from which we can obtain macroscopic quantities relevant for continuum-mechanical and/or statistical-mechanical formulations of those systems. The gap between discrete particle data and macroscopic fields may be bridged through discrete-to-continuum (Discrete2Continuum, D2C) transformations, which apply coarse-graining (CG) methods to DEM data to derive bulk quantities (e.g., stress tensor) projected onto continuum macroscopic fields. CG methods are grounded on the principle that macroscopic fields emerge as averages of microscopic quantities. It is worth noting this use of coarse-graining is distinct from coarse-grained DEM, a computational technique in which large populations of small particles are represented by fewer larger surrogate particles (e.g., ). Hereafter, the term “coarse-graining” will be used specifically to refer to the mathematical methods in D2C transformations.

Several CG formulations have been developed over the years. Early formulations were restricted to the quasi-static regime – whereby the inertial terms were neglected in the microscopic balance equations – or to the rapid flow regime – assuming only binary particle collisions . Some of these procedures are still used today to post-process DEM models that represent static systems (e.g., the host rock of a magma intrusion, ). Later, formulations began to include inertial terms , although with incomplete derivations, as corroborates.

However, the earlier averages were carried out within discrete or hard spatial boundaries – i.e., non-differentiable, hence inadequate for the derivation of macroscopic (differential) balance equations. It is not until , that a general averaging approach across granular flow regimes, suitable to obtain average balance equations for multiphase granular media, is introduced in the literature. The principles used by seem to be an adaptation of the almost coetaneous comprehensive derivation of continuum balance equations through spatio-temporal weighted averages in the field of molecular dynamics by .

Ever since , CG theory has been honed to simplify the derivations therein , to be valid near to hard boundaries , to address averaging scale dependency , to discuss appropriate spatial averaging resolution , to study the contribution of individual particle phases in polydisperse systems , and to account for contacts between particles of irregular shape .

Other CG methods exist in the literature, such as binning or the method of planes, however, they lack key advantages of the spatial weighted average. With the CG that performs a spatial weighted average: the macroscopic fields satisfy the average balance of continuum mechanics equations; the fields can be evaluated at every point in space; and particles are not assumed to be spherical or rigid .

Nowadays, there are numerous DEM code packages, both open-source – e.g., LAMMPS , LIGGGHTS , YADE , MercuryDPM , MFiX – and closed-source or commercial codes – e.g., Altair EDEM (Siemens) , PFC , and Iota-Suite (although no longer operational) . Regarding open-source software, some offer an inbuilt D2C transformation, that is the case of LAMMPS, with a standard volume averaging, and MercuryDPM, with a weighted average in their MercuryCG. Others, like MFiX do not provide that post-processing step, which leads users to build their own D2C code or adapt their DEM software outputs to the format other inbuilt D2C software require. Some of the closed-source software, such as Altair EDEM, also provide their own continuum analysis tools.

The purpose of this work was to build Pysammos, a Python package designed with the aim of providing a user-friendly D2C workflow to post-process data from the MFiX open-source DEM software, and provide a streamlined visualisation in widely used open-source visualisation software, ParaView (Fig. ). This code package provides flexibility in the output variable selection, mesh parametrisation, and data analysis of the obtained results. The efficient algorithmic complexity exhibited by Pysammos avoids the requirement of extensive computational resources, making it a program that can be run at the same time as other processes. Its modular design enhances DEM analysis across users with varying expertise, as it does not require access to inner-level source code. This is intended to encourage a broader use of DEM in geoscientific research, where many observed processes involving discrete elements are currently modelled as a continuum but could benefit from a discrete insight.

The name of the package is a reference to a work by Archimedes called The Sand (Greek: psammos) Reckoner, in which he endeavoured to determine the number of grains of sand that could fit in the universe . To do so, he created a new system of large number notation, given that the number system at that time could only express values up to a myriad (10 000). Similarly, Pysammos is concerned with the efficient handling and analysis of a large number of DEM particles. The name of the package thus reflects the shared focus on managing vast quantities of discrete elements, from grains of sand to simulated particles.

Below we present the coarse-graining mathematical theory implemented in Pysammos; a description of the code workflow, methodologies and features; and a presentation of its performance, benchmarking against other CG codes, and a showcase of examples relevant to the geoscientific community.

In this work, we refer to coarse-graining as a generalised weighted averaging approach to compute macroscopic continuum fields from microscopic discrete quantities (e.g., DEM observables: particle velocity and forces), such that they satisfy the average balance of equations for granular media. The contribution of each particle to the macroscopic field evaluated at any given point is weighted according to the relative position of the particle's centre of mass to the point. CG is applicable to a range of flow regimes – from the solid-like quasi-static mode, to the fluid-like rapid flow mode, for granular media of arbitrary particle size, shape and rigidity . The collisions are assumed not to be instantaneous.

Coarse-graining conceptualises an assembly of discrete solid particles as a system of discrete mass points located at the particle centres, as per the principles of statistical mechanics . Hence, the microscopic discrete mass density field (ρdiscrete) at a point in space (r) and time (t) is given by the convolution of the mass (mi) of particle i (located at ri) and the Dirac delta function (δ), as shown in Eq. () . Note that δ is zero everywhere except at the particle centres, where it is infinitely high, and has a total integral of one. 1ρdiscrete(r,t)=∑i=1Nmiδ(r-ri(t)) Similarly, the macroscopic continuum mass density field is obtained by convolving the particle mass with a coarse-graining function, Ψ, as described in Eq. () . 2ρ(r,t)=∑i=1NmiΨ(r-ri(t)) The net effect of Ψ is the smearing of the Dirac delta function of Eq. () across a volume of radius c and effective smoothing width w (see Sect. ). Hence, Ψ has dimensions of inverse volume, and the sum of the weights across that volume is 1 (Eq. ) . 3∫RDΨ(r)dr=1 Hence, by performing a spatial weighted average, the contribution of several particles is taken into account in the evaluation of a macroscopic continuum field at a given point in space. In order for the macroscopic fields to satisfy the continuum balance of equations, they must be smooth across space. This requires the coarse-graining function Ψ to be differentiable everywhere. Several weighting functions are commonly seen in the literature: the Lucy polynomial function , the Heaviside step function, and the cut-off Gaussian function (see Sect. ).

Continuum fields that correspond to a quantity representing the interaction between two particles are evaluated differently: by distributing the field along the branch vector connecting the two particles . The stress tensor is defined as the sum of the contact stress tensor (σc) and the kinetic stress tensor (σk), as shown in Eq. () . 4σ(r,t)=σc(r,t)+σk(r,t) The contact stress tensor is defined in Eq. (). 5σc(r,t)=∑i=1N∑j=i+1N∑k=1Cijfijk⊗aijk∫01Ψ(r-ri+saijk)ds, where N is the number of particles in the system, and Cij is the maximum number of contact points between two particles. The force between the particles i and j at the kth contact point is represented as fijk. The branch vector aijk is defined as the distance between the kth contact point and the centre of particle i. The dummy variable s parametrises the line segment from particle i to a contact point. The integral of the CG function Ψ over the projection of s on aijk, enables the contact force to be spatially distributed along the branch vector, ensuring a smooth representation of the contact stress (Fig. ). Note that Eq. () does not account for wall-particle interactions; this extension is discussed in detail in .

The coarse-grained velocity field may be distinguished from individual particle velocities, which generally exhibit higher velocities than the macroscopic field. The difference between these two velocities is referred to as the fluctuation velocity of the particle. To prevent it from vanishing to zero, it is represented by its magnitude .

The kinetic stress tensor, calculated with the fluctuation velocity (Eq. ), has been shown to depend on averaging width . 6σk(r,t)=∑i=1NmiVi′Vi′Ψ(r-ri(t)), The scale dependency arises from the fact that in Eq. () the fluctuation velocity, Vi′ (Eq. ), is defined with respect to the field velocity at r, V(r,t), and not at the position of the particle's centre of mass, ri, i.e. V(ri(t),t), in order to satisfy the continuum balance of equations at r . Nevertheless, Vi′ can be decomposed into two terms in order to isolate the scale dependency of σk, as shown below. 7Vi′=vi(t)-V(r,t)=vi(t)-V(ri(t),t)+V(ri(t),t)-V(r(t),t)=Vi*+V(ri(t),t)-V(r(t),t), where vi(t) is the velocity of the ith particle at time t, and Vi* is the fluctuation velocity field evaluated at the particle's centre of mass, ri(t). The latter terms of Vi′ capture the scale dependency due to velocity gradients. In the absence of these gradients, the scale dependency vanishes, and the fluctuation velocity simplifies to Vi′=Vi*. Alternatively, propose an a posteriori correction to obtain the scale-independent term of the kinetic tensor, thus bypassing the evaluation of the fluctuation velocity at ri by means of interpolation.

Nonetheless, the granular temperature is a measure that focuses solely on the local particle fluctuations, at ri. Hence, only the scale-independent part of σk is used to compute granular temperature (Eq.  in Appendix ).

Traditional statistical mechanics considers multiple realisations, or probabilistic copies of a system, over which the corresponding macroscopic quantities are averaged . This conceptual tool is equivalent to averaging over the total time range, an equivalence classically derived for ergodic systems in equilibrium , but which extends to systems at (non-equilibrium) steady state, where the relevant statistics are stationary in time . This is advantageous for systems that are complex to simulate over large time scales. In the case of granular media we are able to simulate complex granular systems for longer time scales with DEM. Hence, in the field of computational granular physics, ensemble averaging is not required , and in fact could be problematic due to the inherent lack of scale separation. Instead, the analytical expressions for continuum fields tend to include a time-averaging, as well as a space-averaging, which acts as a low-pass filter on the inherent fluctuations of granular flows, to obtain steady-state solutions . Nevertheless, the time averaging is not strictly required, and in fact, even moving window Heaviside temporal averages could obscure time-dependent trends in highly transient flows, as pointed out by . Hence, in this study only spatial averaging is considered for the analytical equations of coarse-graining.

The choice of averaging width w, i.e., the resolution of the continuum fields resulting from CG, has been shown to be non-trivial. proposes that the averaging should be computed over a representative volume, which is a region where no gradients occur, calling this the “continuum assumption”. In particular, the macroscopic kinetic tensor field has been shown to intrinsically depend on the square of the smoothing width . find two apparent CG length scales for which the coarse-grained macroscopic fields are almost independent of the averaging width: one at sub-particle scale, which is able to resolve flow layers close to the lower boundary of the modelled inclined flow, and one at particle scale, which yields smooth continuum fields.

To evaluate the partial contribution of various species, or phases, within a particulate mixture, we make use of mixture theory. It conceptualises the granular mixture to be simultaneously populated by all phases, with associated partial macroscopic fields . The macroscopic fields of the mixture are hence obtained by superposing (i.e., summing) the partial fields (Eq. ). 8F=∑νFν A phase can be defined as any particle property, or combination of such, that contributes to particle segregation, that is, density, size, shape, elasticity, roughness .

The architecture of Pysammos is designed to be modular, dividing cumbersome code into smaller manageable tasks, to enhance readability, and to allow reusability and easy maintenance. Code modularisation in Python takes on the form of packages, modules and functions, thus building a hierarchical structure of code (Fig. ). This is further aided by a hybrid implementation, combining object oriented programming (OOP) and functional programming (FP) approaches to optimise readability and maintainability. OOP provides a clear structural interface for encapsulating underlying computations, while FP is suitable for small reusable operations within or alongside OOP. The core code makes use of widely used scientific Python packages, such as NumPy , SciPy , VTK , XArray and Numba .

The paths to the DEM data files and the corresponding variable names are supplied by the user either through the configuration file (Appendix ), or directly to the user-facing CoarseGraining class.

The input DEM data required for Pysammos consist of particle data and contact data, which are stored in separate files. The particle data include particle position, particle ID, velocity, diameter (or radius), density, volume, mass, and optionally coordination number. The contact data include the particle IDs of the two particles involved in each recorded contact, the force acting on the first particle, and the contact point position. If contact point positions are unavailable (e.g., when using earlier MFiX releases), Pysammos can recalculate them for spherical particles.

MFiX records single-sided contacts, providing the force vector acting on the first particle, and the contact point position. Since the contact point position is explicitly available, reconstruction of the full bidirectional contact list is valid regardless of particle size distribution – the branch vectors (aij in Eq. ) are computed directly from particle centre positions and the contact point, rather than being inferred from particle geometry. The reconstruction procedure is described in Sect. and the Appendices referenced therein.

The data inspection consists of obtaining relevant information on the provided DEM data that will be used later on in the program to apply safety checks or perform calculations (Fig. a, panel 1). Likewise, it also provides the user with a particle-size overview. It starts with the .data_sampling() method, which loads and inspects the particle data at the first time step that the user has chosen to process, thus obtaining arrays of particle diameter, mass, density and the bounds of particle positions – i.e., the extent of the model to be post-processed at the first chosen time step. These particle data are analysed in .get_particle_size_statistics() to get the median, root-mean-squared and maximum size, and area- and volume-weighted average particle size or diameter.

The mesh is created with a resolution w (Eq. ) specified in .set_resolution(). It is calculated as w=mwd¯, where mw is a scaling and d¯ is a representative particle size. By default, mw is 0.75 . In polydisperse granular media the choice of d¯ is not trivial , hence, we provide different metrics for the user to choose from, such as the median diameter or d50, the root mean squared diameter (drms), volume-weighted average (d43) and area-weighted average or Sauter diameter (d32).

The mesh domain can be user-defined or automatically determined from the model bounds. In the latter case, the mesh spans the extent of the model while leaving a safety margin to the boundaries proportional to the maximum grain size and averaging scale. In the case of 1D or 2D automatically generated meshes, the domain is reduced along one direction by taking a central transect perpendicular to that dimension.

The method .generate_grid() generates a structured grid with the specified spacing. Currently only a simple regular cuboid grid is available. Nevertheless, the code structure allows the additional implementation of new mesh types. Note that in this work, mesh refers to a general discretisation of space, while grid refers to the current structured Cartesian implementation.

The calculation of continuum fields across all time steps is encapsulated in .fields_in_time(). It makes use of hidden methods of the class, prefixed with an underscore, to organise internal logic and condense recurring functionality. For each time step processed, the data are loaded, the continuum fields are calculated, and output files are written (Fig. e–g). The field evaluation is broken down into particle and grid point association, weight computation, and the computation of the different fields (Fig. f).

Pysammos provides two types of output files: a vtkhdf file per DEM time step processed, for ParaView visualisation; and a single h5 file containing data from all the time steps, for data analysis and storage. Vtkhdf files are built on hdf5 but are adapted for vtk-type workflows, thus combining the parallel I/O support and the optimisation for meshed structures with the standardisation of data storage for visualisation purposes. On the other hand, h5 files offer high flexibility for structured data storage, are optimised for large datasets, and are compatible across programming languages.

Pysammos is intended to be used by a diverse community working with computational particulate methods, spread across geosciences, engineering and physics. Hence, reassuring users that it yields reliable results is key. For that reason, we compared results from Pysammos to other CG software: Iota-Suite , EDEM's continuum analysis , Granulysed (using Iota-Suite and VELaSSCo ), and MercuryCG . We used a benchmark DEM sample of a static monodisperse cubic lattice with vertical plate displacement and fixed side walls. The particles have diameter d=0.02 m and density ρ=2500 kg m⁻³. The sample is analysed at the centre, P=0,0,0.42725 m (Fig. g). The tests are carried out for different smoothing half-width lengths multiples of the characteristic particle size (i.e., w/d) and smoothing functions. These established tests are straightforward to carry out, as they are easily accessible through the user interface class. Future versions of the code should be benchmarked using the same data in order to guarantee output consistency. Figure  contains the continuum fields of the benchmarked simulation, computed with several different CG codes. All the fundamental continuum fields, including all the vector and tensor components are provided in the Supplement.

Volume fraction is overall constant across the entire w/d range (Fig. a). It shows a larger spread of values across codes in the lower range of smoothing widths when using the Heaviside functions in Pysammos and MercuryCG. The mixture density field shows a very similar set of characteristics to the volume fraction (see Fig. S1). The velocity (Fig. b) and momentum density (Fig. c) fields at the tested point increase as the smoothing width is increased for all codes. The Lucy function yields slightly lower values than the rest of the codes for w/d>4, whereas the Heaviside functions and EDEM’s Gaussian consistently estimate higher values. Pysammos’s results coincide with MercuryCG's corresponding results, as they use the same weighted spatial averaging scheme. The kinetic tensor field increases overall as the smoothing width is enlarged (Fig. f). Granulysed calculations yield constant values of the kinetic tensor across the entire w/d range. The results rendered by Pysammos, coincide again with those from MercuryCG.

The contact tensor field (Fig. d) shows a broadly constant mean value across the analysed w/d range (see Fig. S6e for enlarged view), with a greater scatter at the low end. Pysammos and MercuryCG show a degree of discrepancy at lower w/d. This could be attributed to the difference in the particle-search criterion between the two codes: in Pysammos, a contact is included in the averaging volume based on the distance from the grid point to the centre of particle i, whereas MercuryCG's determines inclusion based on the minimum distance from the grid point to the branch vector itself . This more general criterion allows MercuryCG to include contacts whose branch vector is positioned near the grid point even when the particle centre itself lies outside the cut-off radius, an effect expected to be more pronounced at low w/d, where the search radius is comparable to the branch-vector length. We note that this discrepancy is unlikely to stem from the numerical evaluation of the branch-vector line integral in Pysammos (Sect. ), as the trapezoidal integration is already converged at N=10 sampling points (Fig. S7 of the Supplement) and is not expected to be a significant source of error even at low w/d. Further, the Heaviside function in Pysammos shows larger disagreement with that of MercuryCG across the whole w/d range and especially in the diagonal components of σc, compared to the off-diagonal ones (see Fig. S5). This could be due to the Heaviside's uniform weighting of all the particles within the search volume, which exacerbates edge effects of the search shift discussed above. Conversely, the Gaussian and Lucy functions heavily damp the contribution from particles further from the evaluation point, making them less susceptible to this issue. Despite these discrepancies, the ratio of the vertical to the shear component in the xy-plane of the contact stress tensor converges towards a constant value close to 0 after w/d∼3, whereas it shows a larger scatter on the order of ±4×10-2 for w/d<3 (Fig. e).

The computational performance of Pysammos's CG workflow was evaluated by means of the computational cost per particle as the post-processed model increased in size. The computational cost per particle corresponds to the ratio between runtime and number of accounted particles, and it is a measure of how well the code scales resources needed as complexity increases. The model size is quantified by the number of grid points and/or particles in the analysed space. The performance was tested at different spatial averaging resolutions (w/d), and using different number of core processors. Thus, we provide a map of optimal performance across different analysis scenarios, revealing that the ideal configuration depends on the nature of the data being processed and the resolution at which it is being processed.

The DEM sample was that of a static random packing cube of side length ∼95d43, with a high coordination number of ∼5–6 (Fig.  prior to the impact). All available outputs, involving both particle and contact related fields, were exported in order to have a complete representation of the computational requirements when running the program at full capacity. The quoted runtime values are an average of three different computed time steps. The computation for this exercise was carried out on the ARCHER2 HPC cluster.

The cost per particle decreases sub-linearly with number of particles across all averaging resolutions and number of cores, meaning the code cost scales favourably with problem size (Fig. ). This entails that overheads are being amortised and caches are being used efficiently. Inherently, for a given tested model size (i.e., Nparticles), the higher the CG resolution is (i.e., lower w/d), the larger the number of grid points, but the fewer particles per grid point. Consequently, we observe that across all number of cores, the cost per particle at Pysammos's default w/d=0.75 begins to plateau at ∼10-4 for 106 particles (Fig. a), but for larger w/d it continues to decrease (Fig. b–d). Thus, we can say that the number of particles per grid point controls the point at which the performance plateaus. At higher resolutions, the iteration at each grid point carries out operations across a smaller range of particles, which is harder to amortise for large models (∼106 particles), regardless of the total number of grid points.

The use of parallel computing reduces the cost per particle for model sizes of Nparticles>105 at resolutions of w/d>2 (Fig. ). The efficiency gained from additional cores increases with w/d, up to w/d=6, beyond which it begins to plateau relative to w/d=4 (Fig. c, d). For larger systems (Nparticles>105) the speed-up by parallelisation saturates at a low number of cores under sub-particle resolution, but at 16 cores for w>d. For smaller systems (Nparticles<105), parallelisation provides no noticeable speed-up at resolutions w>d, and saturates at a low number of cores (∼2) at resolutions w<d. Although Numba reduces Python-level overhead, the gains from additional parallelism at w<d are of limited improvement (Fig. a), most likely because the algorithms where Numba parallelisation is employed are memory-bound, and this cost is not sufficiently amortised when the number of particles per grid point is small.

Therefore, when coarse-graining at a high resolution below the particle scale, it is recommended to use a low number of cores to attain optimal computational efficiency. Nevertheless, this means that efficient execution of Pysammos does not require extensive parallel resources, thereby making this post-processing software well suited for shared computational systems. On the other hand, when coarse-graining at a lower resolution, namely above particle scale, in a large dense packing it is recommended to use between 4 and 16 cores. In general, further improved parallel performance can be attained by, alternatively or additionally, distributing independent time slices across different shared-memory processes.

Here we provide a usage example of the user-facing CoarseGraining class. Listing shows how to initialise the class with the entries of the configuration file. See Appendix for an example of a configuration file.

Listing  presents the algorithm steps of the CG workflow applied through the methods of the CoarseGraining class, previously described in Sect. . Alternatively, the method CG.run() performs all the steps sequentially with default parameters.

Below we present a set of example MFiX DEM simulations of processes relevant to the geoscientific community, alongside coarse-graining results to showcase the functionalities offered by Pysammos – some of the various continuum fields that can be computed, relevant further data analysis, and result visualisation modalities.

The DEM community is inherently interdisciplinary due to the ubiquity of granular processes in nature, engineering and industry. This naturally prompted the development of a range of DEM software, both open and closed source. In academic research open-source software is favoured from an ethical point of view. However, some open-source DEM software packages do not offer CG post-processing functionalities (e.g., MFiX), leading to the production of individual codes that do not tend to be widely shared, hindering reproducibility and increasing the likelihood of error propagation. Other DEM software might employ other averaging methodologies (e.g., LAMMPS, YADE). Stand-alone CG software might find their flexibility is limited by data format diversity (e.g., MercuryCG), forcing the user to convert data files. Recent efforts in the DEM community focus on standardising workflows and interoperability-related aspects to facilitate reproducibility and direct comparison of results across DEM software and users.

Pysammos aims to contribute to this endeavour. Firstly, it provides a CG tool for MFiX, thus avoiding file conversion and duplication of privately produced CG codes, and ensuring consistency in outputs across MFiX users. Secondly, it is user-friendly and Python-based, to promote usage in several areas of academic research. Further, it is conceived as an open-source tool, inviting others to develop it further to be adapted to other DEM software. This is facilitated by its modular structure and the provided benchmarked examples to ensure consistency. Finally, it provides a streamlined visualisation in widely used open-source visualisation software ParaView.

Although the current MFiX release does not export individual bounding GSP data, component-sphere particle data can be coarse-grained at the GSP scale in the interim to yield reasonable results. The following example demonstrates Pysammos's ability to handle DEM simulations involving complex particle shapes represented by GSP, with the expectation that fully rigorous GSP-level CG will become possible once the relevant MFiX export functionality is complete. This is particularly relevant for applications such as volcanic ash, whose angular morphology produces rougher particle surfaces that directly influence the bulk flow behaviour of such mixtures .

To this end, we use the MFiX feature that approximates a glued-sphere particle to a target shape supplied in stereolithographic (STL) format to simulate a fluidised granular bed of volcanic ash particles (Fig. ). The GSP geometry is fitted to that of an ash particle, obtained from the X-ray micro-tomography by , and scaled up to reduce computational cost (Fig. b–c). The granular bed is fluidised through a basal inlet at 2 m s⁻¹, generating large bubbles that rise through the bed, as visible in the volume fraction field (Fig. d). The transition between dense and collisional flow regimes is reflected in a gradient in the vertical granular temperature (Fig. e).

The ethos behind Pysammos is heavily weighted by the idea of open-source code, well documented and structured to facilitate maintenance and future developments. The first version offers a range of advantageous features suitable for different types of users, nevertheless, there are aspects that can be further developed. Below we outline several implementations that would enhance the functionalities of this code package.

In order to work towards standardising and streamlining DEM post-processing software, future versions of this code package should incorporate data reading modules that are compatible with data from other DEM software, such as LAMMPS (available in the next release) or YADE, to fit the array structure that is used in the core functions. The current architecture is already designed to host new data readers. Regarding meshing, at present Pysammos offers a structured cuboid grid, a choice that is not optimal for all spatial model configurations. Greater flexibility in the meshing scheme would enable better alignment with complex geometries and minimise unnecessary sampling. Finally, the coarse-grained fields implemented in Pysammos are not taking into account the effect of hard boundaries as described in , as it modifies the contact stress tensor. Therefore, future versions of this code should implement the calculation of the contact stress tensor for those particles in direct contact with the walls of a DEM model.