Input file¶
The input file, also known as a .bod
file, contains the description
of the object and some additional input parameters.
Defining the object(s)¶
A single object of interest must be described by a collection of spheres
and cuboids, which may or may not be overlapping. The code has also be extended for the case of running not just a single snapshot composed of a collection of spheres, but also a trajectory or series of snapshots each composed of a collection of spheres. In all cases the shape of the object is defined in the .bod
file.
Spheres¶
Spheres are defined by lines of the form
SPHERE x y z r
where x
, y
, and z
are the coordinates of the center of the
sphere and r
is the radius.
For example, a .bod
file that contains the
following describes an object composed of two spheres: one of radius 2
at \(x=0\), \(y=0\), and \(z=1\) and one of radius 3 at
\(x=0\), \(y=0\), and \(z=1\).
SPHERE 0 0 1 2
SPHERE 0 0 1 3
Cuboids¶
Cuboids can be defined in several ways. The most basic is a line of the form
CUBOID x1 y1 z1 x2 y2 z2
where x1
, y1
, and z1
are the coordinates of one corner of the
cuboid and x2
, y2
, and z2
are the coordinates of the opposite
corner. The edges of the cuboid are aligned with the \(x, y, z\) axes.
A cuboid with all edges the same length is a cube. Cubes can be defined with lines of the form
CUBE x y z L
where x
, y
, and z
are the coordinates of one corner of the cube
and L
is the edge length. This is equivalent to
CUBOID x y z x+L y+L z+L
For example, a .bod
file that contains the following describes an
object composed of two cuboids: one with a corner at \(x=0, y=0, z=0\)
and opposite corner at \(x=1, y=2, z=3\) and one with a corner at
\(x=1, y=0, z=0\) and opposite corner at \(x=5, y=4, z=4\).
CUBOID 0 0 0 1 2 3
CUBE 1 0 0 4
Finally, sets of cuboids can be defined in a binary file in the .fits.gz
format [1] using the voxels command. Voxels are specified with lines of the
form
VOXELS <relative path to .fits.gz file>
Paths to the .fits.gz
file are relative to the location of the .bod
file. So, for example, if you had a voxels file voxels.fits.gz
in the
same directory as the .bod
file, you could simply specify it as
VOXELS voxels.fits.gz
[1]  https://fits.gsfc.nasa.gov/ 
Multiple snapshots or trajectories of spheres¶
In order to be compatible with a variety of existing software packages, the trajectories of spheres are defined using the xyz file format and referenced in the .bod
file. The format of the xyz file is
<number of atoms>
comment line
<atom type> <x> <y> <z>
...
where atom type
can be either a number or string, such as an element symbol. This structure can be repeated multiple times for multiple snapshots. For example,
2
snapshot 1
A 1 0 0
B 0.25 0 0
1
snapshot 2
A 0 0 0
would define two spheres of different types for the first snapshot and one sphere for the second snapshot where that sphere is the same type as the first sphere in the first snapshot. As the xyz file format does not contain radii information, a second conversion file that defines the radius of each atom type is needed. The conversion file format is
<atom type> <radius>
Each atom type in the xyz file must be defined. A corresponding conversion file for the xyz file example could be
A 1
B 0.25
In this case, together the two examples define a system of two touching spheres one of radius 1 and one of radius 1/4 for the first snapshot and a single sphere of radius 1 for the second snapshot.
The xyz file and the conversion file are specified in the .bod
file as
TRAJECTORY <relative path to xyz file> <relative path to conversion file>
Note that if a trajectory is given, no other geomerty may be included in the .bod
file.
Optional inputs¶
Launch radius¶
Command:  rlaunch double 
Explanation:  Sets the radius, which is radius of the sphere from which random walks are launched. The radius must be large enough to enclose the entire object. 
Default value:  The smallest radius that encloses the smallest axisaligned boundingbox of the object. 
Example:  rlaunch 20 means that the
launch radius is 20. 
Skin thickness¶
Command:  st double 
Explanation:  Sets the skin thickness. A random walker is assumed to have hit the surface of the object if the distance between the surface and the walker is less than the skin thickness. 
Default value:  1e6 times the launch radius 
Example:  st 0.01 means that the skin
thickness is 0.01. 
Units for length¶
Command:  hunits double string 
Explanation:  Specifies the units for the length for all objects. 
Options:  The string can take the following values:

Default value:  1 L 
Example:  hunits 10 cm means that a
length of 1 for an object is
equivalent to 10 cm. 
Temperature¶
Command:  temp double string 
Explanation:  Specifies the temperature, which is used for computing the diffusion coefficient. 
Options:  The string can take the following values:

Default value:  None 
Example:  temp 20 C means that the
temperature is
20\(^\circ\)C. 
Mass¶
Command:  mass double string 
Explanation:  Specify the mass of the object, which is used for computing the intrinsic viscosity in conventional units and the sedimentation coefficient. 
Options:  The string can take the following values:

Default value:  None 
Example:  mass 2 g means that the mass
of the object is 2 grams. 
Solvent viscosity¶
Command:  viscosity double string 
Explanation:  Specify the solvent viscosity, which is used for computing the diffusion coefficient, the friction coefficient, and the sedimentation coefficient. 
Options:  The string can take the following values:

Default value:  None 
Example:  viscosity 2 cp means that the
solvent has a viscosity of 2
centipoise. 
Buoyancy factor¶
Command:  bf double 
Explanation:  Specify the buoyancy factor, which is used for computing the sedimentation coefficient. 
Default value:  None 
Example:  bf 2 means that the buoyancy
factor is 2. 