How can I import a particle geometry from file?

Created by Dion Weatherley on on 2009-12-28
Keywords:
geometry files
Last updated by:
Vince Boros on on 2012-03-08

ESyS-Particle provides a subroutine LsmMpi.readGeometry(..) to import a list of particles and bonds between particles into a simulation. The companion tool GenGeo can be used to create geometry files for ESyS-Particle simulations. Alternatively, one may create one's own geometry file. This FAQ describes the file format for ESyS-Particle geometry files.

A geometry file is an ASCII text file consisting of three parts: 1) a header, 2) a list of particles, and 3) a list of bonds between particles. Each of these sections are described below:

1) geometry file header:
LSMGeometry 1.2
BoundingBox 0 0 0 10 20 30
PeriodicBoundaries 1 0 0
Dimension 3D

The first line specifies the geometry file version: "LSMGeometry 1.2". This line is mandatory and should not be changed. The next line defines the bounding box for the spatial domain of the simulation. In this case the left, lower, front corner is at the origin (0,0,0) and the right, upper, back corner is at (10,20,30). The following line specifies which of the three spatial dimensions has periodic (or circular) boundaries. In this case, the x-direction has periodic boundaries. If no periodic boundaries are required, use "PeriodicBoundaries 0 0 0". The next line specifies whether the simulation is 2D or 3D (as in this case).

2) list of particles:
BeginParticles
Simple
2
1.1 2.2 3.3 0.7 0 12345
4.4 5.5 6.6 1.2 1 12345
EndParticles

Immediately following the header, a list of particles, their positions, radii, ID and tag are provided. The list commences with the "BeginParticles" line followed by the type of particles: "Simple". Only "Simple" particles are currently supported in ESyS-Particle. The number on the following line ('2') specifies the total number of particles in the list - two in this case. What follows is a list of particles, one per line. Each line is formatted as follows:

X Y Z Radius ID tag

where (X,Y,Z) is the position of the particle centre, Radius is the particle radius, ID is a unique integer identifier for the particle and tag is used to denote groups of similar particles. The particle tag can be used to specify initial velocities or densities of particles or different types of interactions between particles with different tags.

The particle list concludes with the "EndParticles" line.

3) list of bonds between particles:
BeginConnect
1
0 1 98765
EndConnect

The last part of the geometry file is a list of bonds between particles. Similar to the particle list, the bond list commences with the "BeginConnect" line followed by the number of bonds (one in this example). Following the number of bonds is a list of bonds, one per line. A bond is defined by the IDs of the two particles to bond (particles '0' and '1' here) and a bond tag ('98765' here). The bond tag is used to group together bonds of different types for specifying different types of bonded interactions for bonds with differing tags. The bond list concludes with the "EndConnect" line.

The ESyS-Particle geometry file format is designed to be easy to create and is human readable. It offers the possibility to import relatively complicated particle geometries created with either GenGeo or another program of the user's choice. If you desire an initial particle geometry with a particular particle size-distribution for example, one can create a program to construct the desired geometry then import it into ESyS-Particle via a geometry file.

For completeness, the complete geometry file example described above is provided below:

LSMGeometry 1.2
BoundingBox 0 0 0 10 20 30
PeriodicBoundaries 1 0 0
Dimension 3D
BeginParticles
Simple
2
1.1 2.2 3.3 0.7 0 12345
4.4 5.5 6.6 1.2 1 12345
EndParticles
BeginConnect
1
0 1 98765
EndConnect