Visualizing force chains out of ESyS-Particle simulations: fcconv

I report here my initial experience in visualizing force chains out of numerical simulations of sheared granular layers using ESyS-Particle.
In ESyS-Particle 2.0, there is a post-processing tool called fcconv that can help you with doing that. Its logic is similar to dump2vtk's one.

Let's start with the basics.

Where can you find fcconv ?
The program itself is in ESyS-Particle's binary directory. Its source code is in

<ESyS-Particle source tree>/Tools/ForceChains .

What's its command line ?

fcconv -i < input filename > -o < ouput filename >

-vvf -vtk ,

where <

input filename

> is the input filename,

<

output filename

> is the output filename, the option -vvf is used if you want an output file in a format readable with Itasca's PFC2D(3D) DEM software while -vtk it's used if you want an output file in VTK-XML format.
You can use either -vvf or -vtk or both.

The output file is an unstructured grid constituted by points and cells.
The points are centers of particles belonging to couples of interacting particles, where the interaction is of a specific type (see below). The cells are type=3 VTK cells, i.e., lines, connecting these couples of particles. Associated to the cells there is a DataArray attribute, as it is called in VTK language, specifically, a scalar. This scalar variable corresponds, in the simulation, to the norm of the interaction force acting on one of the two particles, for each couple of interacting particles.
If you wanted the output files in VTK-XML format, such that you could read them in with Paraview, it would be useful to define the file name suffix as .vtu, to remind Paraview that it is a VTK unstructured grid dataset file in XML format. Otherwise you have to specify to Paraview which type of dataset you are importing.

The input file is the output of a specific FieldSaver used inside your ESyS-Particle simulation script. This output refers to a specific time step of the simulation.
That means that, contrary to dump2vtk which manages multiple snapshots in time, you have to use fcconv inside a for loop to convert multiple snapshots in time into the corresponding VTK unstructured grid datasets.

Each input file is an ASCII file and contains the following information (for a specific time step) :

• each line corresponds to a couple of particles interacting with each other according to a specific interaction type, whose name is specified as a member of the FieldSaver object; this interaction shall be either RotFriction or NRotFriction, so a pure frictional, repulsive, contact force;
  

• each line contains 14 fields, each one separated by a blank space from the following one.

The fields (observables) are the following:

1. particle #1's X coordinate
2. particle #1's Y coordinate
3. particle #1's Z coordinate
4. particle #1's radius
5. particle #2's X coordinate
6. particle #2's Y coordinate
7. particle #2's Z coordinate
8. particle #2's radius
9. contact point between particle #1 and particle #2, X coordinate
10. contact point between particle #1 and particle #2, Y coordinate
11. contact point between particle #1 and particle #2, Z coordinate
12. contact force's X component
13. contact force's Y component
14. contact force's Z component

The FieldSaver that produces such files is the following one:

InteractionVectorFieldSaverPrms(
interactionName = "friction",
fieldName = "force",
fileName = "/pool2/grm118/ShearFaultGouge2DEx3_33/ContactForce",
fileFormat = "RAW2",
beginTimeStep = 0,
endTimeStep = nt,
timeStepIncr = 500
)

In this example, friction is the name of an interaction group of type RotFriction.
The fieldName indicates that we want to record the full interaction force for each couple of particles subject to this type of interaction. You can choose also fieldName = normal_force and only the projection of the interaction force along the direction passing through the two particles' centers will be recorded.
fileFormat has to be = RAW2 if you are using ESyS-Particle 2.0. I tried to use

fileFormat = RAW_SERIES, like for other FieldSavers, but it did not work. Maybe it's something related to ESyS-Particle's previous versions.
timeStepIncr indicates the time step in between two successive files. It's the sampling time step.
fileName is the FieldSaver's output filename prefix. The program actually add to that prefix a .n.dat suffix, where n is a increasing counter numbering the files (n = 0,1,2,...).
This means that each output filename does not track the simulation time step it refers to.

The VTK-XML unstructured grid dataset files (one for each recording time step) allows you to visualize the contact force network as a network of solid "beams", each one with the same thickness, but with different color scaled according to the scalar attribute, the norm of the contact force.
This contact force network visualization is not the best one: in the literature, you can find several simulation works showing force chains represented as cylindrical beams of different colors AND thicknesses, both scaled according to the value of the norm of the contact force.
However, it's still a useful pictorial representation of contact forces.

For more information, see threads #91547 and #92702 at ESyS-Particle launchpad Web site.

-------------------------------------------------------------------------------------------------
Disclaimer

This post is based on the author's personal experience in using the ESyS-Particle Discrete Element Method code.
This post should not be considered as an official document about the code itself.
This post does not come with any warranty about the correctness of its content.
If you find any error in the content, please write to the author.
-------------------------------------------------------------------------------------------------