What output file formats are available for GenGeo?

GenGeo can output constructed particle geometries in either of three different formats: raw, geo and vtu. The format of the output file is specified by the second argument to the MNTable3D.write(..) subroutine:

0 = raw format
1 = geo format
2 = vtu format

e.g.
mntable.write("mygeometry.raw", 0) # outputs the geometry in "raw" format to file named "mygeometry.raw"
mntable.write("mygeometry.raw", 1) # outputs the geometry in "geo" format to file named "mygeometry.geo"
mntable.write("mygeometry.raw", 2) # outputs the geometry in "vtu" format to file named "mygeometry.vtu"

The "raw" format is for debugging purposes and is not generally recommended to be used for general applications.

The "vtu" format is the VTK Unstructured Grid format specified by Kitware. Files output in "vtu" format can be easily opened and visualized using paraview (https://www.paraview.org/). It is a good idea to routinely output GenGeo particle geometries in "vtu" format so that the quality of the geometry can be assessed prior to import into ESyS-Particle or other DEM simulations.

For more information about the "vtu" format please refer to:
https://vtk.org/wp-content/uploads/2015/04/file-formats.pdf

The final output file format is "geo". This is the output format recognised by ESyS-Particle's LsmMpi.readGeometry(..) subroutine. It is a human-readable ASCII file with up to two sections. The first section contains a list of all particles in the geometry: their positions, radii, id numbers and particle tags. The second section contains a list of connections between neighbouring particles. This list consists of three columns per connection. The first two columns are the id numbers of the two connected particles and the third column is the bond tag of that connection. Multiple connections may have the same bond tag and there may be multiple groups of connections with differing bond tags.

Both particle tags and bond tags can be used in ESyS-Particle to specify different material properties and interaction types, depending on the application being simulated.

Below is a simple example GenGeo "geo" file for a geometry consisting of three particles forming a triangle with connections along the edges of the triangle.

# triangle_example.geo:
LSMGeometry 1.2
BoundingBox -1 -2 -3 7 8 9
PeriodicBoundaries 0 0 0
Dimension 3D
BeginParticles
Simple
3
0 0 0 0.2 47 999
1 0 0 0.3 58 999
0.5 1 0 0.4 98 999
EndParticles
BeginConnect
3
47 58 987
47 98 987
58 98 987
EndConnect
# end of triangle_example.geo file

The "geo" file commences with a header comprising 4 lines:
1) The first line specifies the geometry file format. Currently only version "1.2" is supported by ESyS-Particle.

2) The second line defines the bounding box of the spatial domain. In this example the minimum point is at (-1,-2,-3) and the maximum point is at (7,8,9).

3) The third line indicates which of the three coordinate axes has a periodic (or circular boundary). In this example, none of the axes are periodic. Replacing the "0" with "1" will indicate that an axis is periodic.

4) The forth line indicates whether the geometry is 2D or 3D. The geometry is 3D in the example above.

Subsequent to the header, the particles section of the "geo" file commences with the keyword "BeginParticles". The line immediately following this contains the total number (Np) of particles in the geometry; Np = 3 particles in this example. The next Np lines provide information about each of the particles. The format for each line is:
position_X position_Y position_Z radius particle_id particle_tag

In the example above, the three particles are located at (0,0,0) , (1,0,0) and (0.5, 1, 0). Their respective radii are 0.2, 0.3 and 0.4.

Each particle has a unique particle_id. Generally these particle_ids are semi-random however it is possible to renumber the particles contiguously from 0 to Np-1 by using the MNTable3D.renumberParticlesContinuous() subroutine prior to writing the geometry file. In the example above, the first particle has a particle_id = 47; the second particle_id = 58 and the last particle_id = 98.

Groups of particles may share a common particle_tag. In the example above, all three particles have particle_tag = 999.

After the information for each particle, the particles section ends with the keyword "EndParticles". The next section will specify which pairs of particles are connected to each other. Note that this section will be omitted if no bonds were generated by the GenGeo script.

The connections section commences with the keyword "BeginConnect" followed by the total number of connections (Nc) on the subsequent line. Thereafter Nc lines specify which pairs of particles are connected and their relevant bond_tag. The format is:
particle_id1 particle_id2 bond_tag

In the example above, all connections have a bond_tag = 987. In many cases, different groups of connections can have different bond_tags, permitting specification of bonded interactions with different properties in ESyS-Particle simulations.

The connections section of the "geo" file ends with the keyword "EndConnect".