4.7. Input/Output

In this section, we will describe the various operators used for analysis and I/O in DEM simulations.

4.7.1. Configuration

4.7.1.1. IO Configuration

This operator is used to define the tree structure of output files. By default, exaDEM proposes a tree structure with names defined in the config_exaDEM file. You can override this operator yourself by redefining it in the io_tree operator.

  • Name: io_config

  • Description: This operator defines the tree structure of output files.

  • Parameters:

    • avg_stress_tensor_name : Write an output file containing stress tensors.

    • dir_name : Main output directory.

    • interaction_basename : Write an output file containing interactions.

    • log_name : Write an Output file containing log lines.

YAML example:

- io_config:
   dir_name: "ExaDEMOutputDir"
   log_name: "log.txt"
   avg_stress_tensor_name: "AvgStressTensor.txt"
   interaction_basename: "InteractionOutputDir-"

4.7.2. Checkpoint/Restart Operators

4.7.2.1. Reader Of xyz File

  • Name: read_xyz

  • Description: This operator reads a file written according to the xyz format.

  • Parameters:

    • bounds_mode : default mode corresponds to ReadBoundsSelectionMode.

    • enlarge_bounds : Define a layer around the volume size in the xyz file. Default size is 0.

    • file : File name, this parameter is required.

    • pbc_adjust_xform : Adjust the form.

YAML example:

- read_xyz:
  file: input_file_rigid_surface.xyz
  bounds_mode: FILE
  enlarge_bounds: 1.0 m

How to build your xyz input file of nb particles.

nb
box_size_x box_size_y box_size_z
type_0 pos_x_0 pos_y_0 pos_z_0
type_1 pos_x_1 pos_y_1 pos_z_1
type_2 pos_x_2 pos_y_2 pos_z_2
...
type_nb-1 pos_x_nb-1 pos_y_nb-1 pos_z_nb-1

This is an example of two particles the same type in a domain [[0,0,0],[10,10,10]].

2
10 10 10
0 2.5 5.0 5.0
0 7.5 5.0 5.0

4.7.2.2. Reader Of MPIIO File

  • Name: read_dump_particles

  • Description: This operator reads a dump file with all particle information required to restart the simulation. See operator: @write_dump_particles

  • Parameters:

    • filename : Dump file name to read.

    • bounds : If set, override the domain’s bounds, filtering out particles outside of overriden bounds (AABB = [[infx, infy, infz],[supx, supy, supz]]).

    • expandable : If set, override domain expandability stored in file

    • periodicity : If set, overrides the domain’s periodicity stored in a file with this value (ex: [false,true,false]).

    • scale_cell_size : If set, this option rescales cell size. Due to friction storage per cell, ou can only multiply this size by an integer (1,2,4, 8, …) or divide it by a power of 1/(2^n) (0.5,0.25 …).

    • shrink_to_fit : If set to true and bounds were specified, try to reduce the domain’s grid size to the minimum size enclosing fixed bounds.

YAML example:

- read_dump_particles:
    filename: last.dump

Note

This operator is used for spheres and not polyhedra because we need a special reader to read current interaction values containing the friction and moment. Show read_dump_particle_interaction.

4.7.2.3. Restart file script

In the scripts folder, you have the option of using a script restart_template.py that will enable you to quickly write the restart section of your simulation by directly retrieving the path to any saved files. This script directly includes whether the simulation mode is spherical or polyhedral. If the mode is polyhedral, the shape file will also be loaded automatically. The script will also check for a file containing driver data and include it. Finally, it will also include the last dump file (highest iteration).

Option:

  • directory: Output file path, the default path is ExaDEMOutputDir. Note that it should contains a subdirectory named: CheckpointFiles and this output file path is defined into the operator io_tree.

Example:

python3 ~/exaDEM/scripts/restart_template.py --directory SpheresMovableWallDir

Output:

Restart directory: SpheresMovableWallDir
Particle mode: Spheres
Last iteration identified: 29000
Here s a template for restarting your simulation at the last saved iteration:

includes:
  - config_spheres.msp
  - SpheresMovableWallDir/CheckpointFiles/driver_0000029000.msp

input_data:
  - read_dump_particle_interaction:
     filename: SpheresMovableWallDir/CheckpointFiles/exadem_0000029000.dump

4.7.2.4. Reader Of Rockable Files

  • Name: read_conf_rockable

  • Description: This operator reads a rockable output file. However, some lines are not processed by the reader, such as the contact law type or its parameters.

  • Paramters:

    • bounds This option defines the simulation domain. If not specified, the domain size is determined by the particle positions. Ex: [[0,0,0],[1,1,1]].

    • filename Dump file name to read.

    • enlarge_bounds Define a layer around the volume size. Default size is 0.

Yaml Example:

input_data:
  - read_conf_rockable:
     filename: input_file/518_poly.conf

What is read:

  • t

  • dt

  • density

  • periodicity

  • nDriven

  • shapeFile

  • precision

  • Particles

  • Interactions (read but NOT used)

What is not read:

  • Interactions (read but NOT used)

  • Interfaces

  • gravity

  • AddOrRemoveInteractions

  • UpdateNL

  • forceLaw

  • Contact law parameters

  • interVerlet

  • interConf

  • tmax

  • DVerlet

  • dVerlet

  • gravity

  • ParamsInInterfaces

  • dynamicUpdateNL

  • ContactPartnership

  • cellMinSizes

  • iconf

  • boxForLinkCellsOpt

4.7.2.5. Read Shape File

The purpose of this operator is to add shapes to a collection of shapes. This operator can be called as many times as desired. However, if you add the same shape multiple times, it will create duplicates. Additionally, the shapes will be ordered according to the order of reading, meaning that type 0 will be associated with the first shape from the first input file. Furthermore, this operator will automatically create a polydata for each shape, which will be used for displaying the polyhedra using ParaView.

Note

The output Paraview file does not incorporate the “spherical” characteristics of polyhedra, i.e. surfaces are created by connecting the centers of vertices, edges are straight lines (instead of cylinders), and vertices are points (instead of spheres).

  • read_shape_file :

    • filename: Input file name, no default name.

Warnings:

Warning

  • This operator takes on ASCII files.

  • This operator is not typo-proof and will ignore problematic values.

  • Do not define a shape “driven” such as a wall or a cylinder because the cell diameters and the cutoff radius for creating interaction lists are derived from the shapes of the polyhedra. These should be defined in specific operators if they have an analytical shape. If they have particular shapes with many facets, please use the STL mesh reader.

YAML example:

- read_shape_file:
   filename: shapes.shp

Example of a shape:

<
name Octahedron
radius 0.1
preCompDone y
nv 6
0.2310789034541148 -0.2310789034541148 0.0
0.2310789034541148 0.2310789034541148 0.0
0.0 0.0 0.32679491924311227
-0.2310789034541148 -0.2310789034541148 0.0
-0.2310789034541148 0.2310789034541148 0.0
0.0 0.0 -0.32679491924311227
ne 12
0 1
2 1
2 0
0 3
2 3
3 4
4 2
4 1
5 0
5 1
5 4
5 3
nf 8
3 0 1 2
3 2 3 4
3 1 2 4
3 0 2 3
3 0 5 1
3 0 5 3
3 3 5 4
3 4 5 1
obb.extent 0.33107890345411484 0.33107890345411484 0.4267949192431123
obb.e1 1.0 0.0 0.0
obb.e2 0.0 1.0 0.0
obb.e3 0.0 0.0 1.0
obb.center 0.0 0.0 0.0
position 0.0 0.0 0.0
orientation 1.0 0.0 0.0 0.0
volume 0.16666666666666666
I/m 0.04999999999999999 0.04999999999999999 0.04999999999999999
>

Example of Octahedron.vtk with paraview:

../../_images/octahedron.png

4.7.2.6. Writer Of MPIIO Files

  • Name: write_dump_particles

  • Description: This operator writes a dump file with all particle information required to restart the simulation. See operator: @read_dump_particles.

  • Parameters:

    • compression_level Zlib compression level.

    • filename Dump output file name.

  • Default behaviour: the default name is defined by : - timestep_file: “exaDEM_%09d.dump and piloted by simulation_dump_frequency: 1 in the operator global.

Note

This operator is defined in the default ExaDEM operator named dump_data_particles.

4.7.2.7. Writer Of Rockable Files

  • Name: write_conf_rockable

  • Description: This operator writes a minimal rockable output file to use the rockable tool see.

  • No parameter

YAML example:

iteration_dump_writer:
  - write_conf_rockable

Note

Only particles data are writen to use the rockable tool see.

4.7.2.8. Writer Of XYZ Files

  • Name: write_xyz_generic

  • Description: This operator writes a txt file (.xyz) with all specified fields.

  • Parameters: * fields: array of fieldsets. Example: [ id, velocity, radius ] * filename: name of the output file. * units: array of units. Example: { velocity: "m/s", radius: "m" }

Note

The first line of the output file contains the number of particles. The second line contains the “lattice” description, useful when using ovito.

YAML example: Replaces MPIIO output files with xyz files.

dump_data_xyz:
  - timestep_file: "dem_pos_vel_%09d.xyz"
  - write_xyz_generic:
     fields: [ id, velocity, radius ]
     units: { velocity: "m/s", radius: "m" }

iteration_dump_writer:
  - dump_data_xyz

global:
  simulation_dump_frequency: 500

To process these files, a sample script is provided in scripts/post_processing/profile_pos_vel.py. This is a minimal, easily modifiable post-processing file that calculates the averages of all position and velocity components.

Output file: [mean_r_v.pdf]

../../_images/mean_r_v.png