6. Python pre/post processing toolkit

The python scripts files can be found in the scripts folder.

6.1. Overview

The exaDEM/script folder provides a collection of Python scripts dedicated to pre-processing and post-processing tasks for exaDEM simulations. Its goal is to streamline the preparation of input data and the analysis of simulation outputs.

The project is organized into two main components:

a core Python library (scripts/lib) gathers all generic functionalities, including data structures (particles, interactions, geometries), input/output utilities, and various computational tools.
standalone scripts (located in scripts/pre_processing and scripts/post_processing) implement specific use cases such as configuration generation or result analysis. These scripts rely on the shared library..

Environment : The command (source /scripts/setenv.sh) automatically configures the PYTHONPATH so that the internal library can be used without requiring installation. Once the environment is sourced, users can run the scripts from any location while still accessing the project’s modules.

6.2. Pre-processing

The pre-processing tools are responsible for generating simulation-ready input files from geometric or mesh-based representations.

6.2.1. tess2rockable.py

6.2.1.1. Overview

This script converts a Neper .tess tessellation file into a complete Rockable-compatible input configuration. It performs:

parsing of polyhedral cells
geometric reconstruction of Voronoi-like structures
Minkowski erosion to account for particle radius
generation of Rockable shapefile (.shp)
generation of a full simulation configuration with “sticked particles”

The goal is to transform a geometric tessellation into a physically usable DEM input.

6.2.1.2. Workflow

Read Neper tessellation file (.tess)
Extract vertices, faces, edges, and polyhedra
Compute local face normals oriented toward cell centers
Perform Minkowski erosion of each cell:
- each face plane is shifted by a distance gap
- intersections of shifted planes define the eroded polyhedron
Compute:
- volume
- center of mass
- inertia tensor (Monte Carlo integration)
Write:
- Rockable shapefile (.shp)
- Rockable configuration file (_sticked.conf)

6.2.1.3. Inputs

input.tess (Neper tessellation file)
radius (float) - particle radius used for erosion and stick distance

6.2.1.4. Outputs

output.shp
- Rockable-compatible geometry file
- contains vertices, faces, edges, inertia tensor, volume
output_sticked.conf
- full simulation configuration
- includes:
  - particle initialization
  - interaction laws
  - gravity and timestep settings
  - stickVerticesInClusters parameter

6.2.1.5. Command line usage

python tess2rockable.py input.tess 0.1 output.shp

6.2.1.6. Physical assumptions

Cells are assumed to behave as rigid polyhedra
Erosion ensures no overlap between particles
Contact behavior is governed by Rockable’s StickedLinks law
Stick distance is set to 4 × gap (where gap = 2 × radius)

6.3. Post-processing

The post-processing tools are used to analyze DEM simulation outputs and extract physical quantities such as stress tensors, strains, and boundary forces.

6.3.1. compute_clusters_stresses_tensors.py

6.3.1.1. Overview

This script computes:

stress tensors per cluster of particles
global wall forces
global deformation (strain) of the particle assembly

It processes time series of:

*.xyz particle snapshots
corresponding interaction files

The goal is to extract continuum-scale mechanical quantities from discrete simulations.

6.3.1.2. Workflow

For each simulation timestep:

Load particle snapshot (.xyz)
Load corresponding interaction file
Build particle index and cluster grouping
Compute stress tensor:
- contact forces
- contact positions
- normalization by cluster volume (or particle density)
Compute wall forces:
- separation of contacts by spatial position
- aggregation of forces on top/bottom/left/right boundaries
Compute deformation:
- global bounding box of particles
- reference configuration stored at first timestep
- strain computed as relative variation

6.3.1.3. Inputs

particle files:

*.xyz (DEM snapshots)
format: position, velocity, cluster id, etc.
generated in ExaDEM datasets by :

analyses:
- timestep_file: "OutputRockableTestDir/ExaDEMAnalyses/dem_pos_vel_%09d.xyz"
- write_xyz:
   fields: [ id, velocity, fx, fy, fz, vrot, arot, cluster, mass ]

interaction files:
- InteractionOutputDir-*/InteractionOutputDir-*_0.txt
- generated in ExaDEM datasets by :
```
global:
  symetric: true
  analysis_interaction_dump_frequency: 500
```

6.3.1.4. Outputs

clusters_stresses_tensor.txt

Time series of stress tensors per cluster:
```
time cluster_id sxx syy szz sxy sxz syx syz szx szy
```

wall_forces.txt

Time series of global mechanical response:

time delta_x delta_y delta_z eps_x eps_y eps_z Fx Fy Fz

6.3.1.5. Command line usage

python compute_clusters_stresses_tensors.py --dir . --density 2500

Arguments:

--dir : directory containing simulation outputs
--density : particle material density (used for stress normalization)

6.3.1.6. Physical meaning

Stress tensor:
- computed from contact force moments
- normalized by cluster volume (or mass/density approximation)
Wall forces:
- represent macroscopic boundary reactions
- split between top/bottom regions
Strain:
- computed from initial bounding box
- gives global deformation of the granular assembly

6.3.1.7. Limitations

Assumes correct pairing between .xyz and interaction files