In the following sections, all of the available XML tags and
attributes of the configuration file are listed and all of the
options are detailed for each tag type. Below is a hyperlinked
hierarchy of the tags in the configuration file.

Scheduler

The Scheduler specifies how DynamO searches the simulation for
events. How the events are actually sorted by the scheduler is
specified through the Sorter tag.

Type="Dumb"

Description

The "Dumb" scheduler is the most basic and
slowest scheduler available. When particles undergo an event, the
Dumb scheduler tests for new events against all other particles in
the system (regardless of where they are). This cost scales linearly
with the system size ($\mathcal{O}(N)$), resulting in an overall
$\mathcal{O}(N^2)$ scaling of the computational cost. This Scheduler
type is only provided for debugging and testing purposes.

Example usage

<Scheduler Type="Dumb">
<Sorter .../>
</Scheduler>

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "Dumb" to select this Scheduler type.

Sorter(tag): This tag specifies the type of event
sorter used in the Scheduler. See the section
on Sorters for more information on this tag.

Type="NeighbourList"

Description

The "NeighbourList" scheduler uses a
NeighbourList to optimise the detection of events. When particles
undergo an event, the NeighbourList scheduler only tests for new
events against nearby particles. This cost is independent of the
system size ($\mathcal{O}(1)$), resulting in an overall linear
($\mathcal{O}(N)$) scaling of the computational cost.

Note

The NeighbourList scheduler will automatically add
a Global neighbour-list interaction to the
system if one has not already been specified. The current default is
the Cells
type Global.

If you want to specify the neighbour list type or change its
parameters, please add a Global with the name
attribute set to "SchedulerNBList" to allow the NeighbourList
Scheduler to identify it.

Example usage

<Scheduler Type="NeighbourList">
<Sorter .../>
</Scheduler>

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "NeighbourList" to select this Scheduler type.

Sorter(tag): This tag specifies the type of event
sorter used in the Scheduler. See the section
on Sorters for more information on this tag.

Sorter

The Sorter tag specifies the method DynamO uses to sort events when
determining the next event to occur.

Type="CBT"

Description

The "CBT" Sorter uses a STL priority queue for
each particle and inserts this into a Complete Binary Tree (CBT) to
sort the events. This type of Sorter is very robust to unusual
systems (such as systems with zero or one particle) but, as the
computational cost scales as $\mathcal{O}(\log_2(N)$ with the system
size, it is not the default Sorter used by DynamO.

Example usage

<Sorter Type="CBT"/>

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "CBT" to select this Sorter type.

Type="BoundedPQMinMax3"

Description

The "BoundedPQMinMax3" Sorter uses a bounded
MinMax heap of size 3 to sort particle events. These particle queues
are then presorted using a bounded priority queue. The earliest
entry in the bounded priority queue is then sorted using a Complete
Binary Tree. In this way, the lazy deletion scheme can be combined
with a fixed size event queue and a bounded priority queue to yield
a constant ($\mathcal{O}(1)$) scaling of the computational cost with
the system size. There are variants of this scheduler with different
sizes of the MinMax heaps ranging from 2 to 8 (e.g.,
"BoundedPQMinMax8" is also available). After many years of testing
this has proven to be the fastest and lowest memory event sorter for
a range of event-driven particle simulations. In small systems the
CBT Sorter is slightly faster and, depending on the system studied,
you may find the MinMax heap size might be increased or decreased to
increase performance.

Example usage

<Sorter Type="BoundedPQMinMax3"/>

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "BoundedPQMinMax3" to select this Sorter
type. Other variants from "BoundedPQMinMax2" to
"BoundedPQMinMax8" are also available.

SimulationSize

Description

The SimulationSize tag specifies the dimensions
of the primary image for periodic boundary conditions. When the
system is not periodic, it specifies the size of the tiled
neighbourlist (if one is used). If no neighbour list is used in an
infinite system, this tag has no effect.

Example usage

This example specifies a $10\times10\times10$ primary image.

<SimulationSize x="10" y="10" z="10"/>

Full Tag, Subtag, and Attribute List

x(attribute): The size in the $x$ dimension.

y(attribute): The size in the $y$ dimension.

z(attribute): The size in the $z$ dimension.

Species

Species are vital tags used to specify the mass and inertia data of
a set of particles. They also provide a unique identifier/name for
groups of particles as each particle must belong to exactly one
species. Many output plugins use the species of a particle to
separate results (for example, a radial distribution function will
be generated for all pairings of species in the system).

Particles will have rotational degrees of freedom if they have a
Species which provides a non-zero inertia tensor
(e.g. "SphericalTop"). Other Species
types such as "Point"
and "FixedCollider" will avoid the
computational overhead of tracking the rotation of the particles.

Type="Point"

Description

This Species type corresponds to point mass
(zero inertia) particles, but this type is also used in systems
where inertial data is unimportant (atomic or frictionless
systems). It is the simplest type of Species available.

Example usage

<Species Mass="1" Name="Bulk" Type="Point">
<IDRange .../>
</Species>

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "Point" to select this Species type.

Mass(attribute): The mass of the particles
represented by this Species.
This attribute is a Property specifier with units
of Mass (see the section on Properties
for more information).

Name(attribute): The name of the particles
represented by this Species. This is used in output, so species
"A" or "Carbon" are examples. If the system is monocomponent,
dynamod often uses the name "Bulk".

IDRange(tag): A IDRange which specifies the
Particles represented by this Species tag. The IDRanges of each
Species must not overlap with any other Species in the
system. All particles must belong to exactly one Species.

Type="FixedCollider"

Description

This Species type corresponds to particles which
have infinite mass and no inertia tensor. This is useful for
particles which are used as the boundaries of a system (also called
a particle mesh).

Example usage

<Species Name="Bulk" Type="FixedCollider">
<IDRange .../>
</Species>

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "FixedCollider" to select this Species type.

Name(attribute): The name of the particles
represented by this Species. This is used in output, so species
"A" or "Carbon" are examples. If the system is monocomponent,
dynamod often uses the name "Bulk".

IDRange(tag): A IDRange which specifies the
Particles represented by this Species tag. The IDRanges of each
Species must not overlap with any other Species in the
system. All particles must belong to exactly one Species.

Type="SphericalTop"

Description

This Species type corresponds to particles where
the three principal momenta of inertia are identical. It is also
used in systems where only two of the principal momenta of inertia
are equal but the rotation is constrained such that the particle
cannot precess.

Example usage

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "SphericalTop" to select this Species type.

Mass(attribute): The mass of the particles
represented by this Species.
This attribute is a Property specifier with units
of Mass (see the section on
Properties for more information).

InertiaConstant(attribute): The area factor of the
principal momenta of inertia of the particles represented by this
Species. This is value is multiplied by the mass of the particle
to obtain the value of the principal momenta of inertia.For a
solid sphere this value should be $\sigma^2/10$ where $\sigma$ is
the particle
diameter. A
list of inertia constants is available at wikipedia.

Name(attribute): The name of the particles
represented by this Species. This is used in output, so species
"A" or "Carbon" are examples. If the system is monocomponent,
dynamod often uses the name "Bulk".

IDRange(tag): A IDRange which specifies the
Particles represented by this Species tag. The IDRanges of each
Species must not overlap with any other Species in the
system. All particles must belong to exactly one Species.

BC (Boundary Conditions)

The BC tag in the configuration file controls the boundary
conditions of the simulation.

Type="None"

Description

The "None" boundary condition actually
corresponds to an infinite system, without boundaries. The positions
of the particles are not restricted in any dimension.

Example usage

<BC Type="None"/>

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "None" to select this BC type.

Type="PBC"

Description

The "PBC" boundary condition applies periodic
boundary conditions to every dimension. The positions of the
particles are wrapped to fit within the primary image, whose
dimensions are specified by
the SimulationSize tag.

When we want to study molecular fluids we often want the "bulk"
properties of the fluid. Effects like surface tension will have a
strong influence if there are any free surfaces or boundaries in
contact with the fluid, as systems simulated are usually relatively
small ($\approx10^5$ molecules). On the other hand, there must be
some boundary used to contain the fluid, as using an open (infinite
size) system will cause the fluid to either evaporate or form
droplets, again with surface effects. To avoid the effects of
boundaries/walls while still "containing" the
system, periodic
boundary conditions are often used. With periodic boundaries, a
small representative amount of fluid, called the "primary image," is
simulated. This primary image is then surrounded with periodic
images which are copies of the primary image as illustrated in the
figure below:

An illustration of periodic boundary conditions and the effective wraparound of particle positions.

These boundaries allow the approximation of an infinite fluid using
a small repeating image. This is an approximation as the periodicity
adds additional correlations to the system, but it is a convenient
technique to avoid using real boundaries such as walls to contain
the system. When using periodic boundary conditions it is still
possible to enter into two-phases if the simulation has attractive
interactions, so care must still be taken.

Example usage

<BC Type="PBC"/>

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "PBC" to select this BC type.

Type="LE"

Description

The "LE" boundary condition applies
Lees-Edwards boundary conditions to the system. These are periodic
boundary conditions but they shear the system by setting the
periodic images in the $y$ direction in motion in the $x$ direction
(see figure below). They are also known as sliding-brick boundary
conditions.

An illustration of
the Lees-Edward sliding-brick boundary condition

Example usage

<BC Type="LE" DXD="0" Rate="1"/>

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "LE" to select this BC type.

DXD(attribute): This attribute stores the current
displacement of the nearest periodic images in the $x$-direction
(units of length).

Rate(attribute): This specifies how fast the
boundary is shearing (units of primary image length per unit
time).

Structure

Structure tags are used to specify multi-particle structures, such
as molecules. This is to mark these structures to allow specialized
data collection and to simplify the implementation of complex
interactions.

Each Structure tag contains one or
more IDRange tags, each of which specifies a
single structure of the same type. So one Structure tag has at least
the following basic format:

Interaction

Interaction tags are used to specify how pairs of particles interact
and generate Interaction events.

Each pair of Particle ID's must have a corresponding
Interaction. Every possible pairing of particles
(including self pairings)
must have a corresponding Interaction, even if they don't
interact. If you don't want them to interact at all, you must use a
Null Interaction.

The order in which Interactions are listed in the configuration
file is important. When DynamO tests for
interactions/events between a pair of particles, it moves through
the list of interactions in the order in which they are specified,
testing if the ID's of the pair match the
Interaction's IDPairRange. Interactions
which are higher in the configuration file will override matching
Interactions which are lower down.

Each particle must also have a self-Interaction. This
self-Interaction does not generate events, but is used to decide how
to draw the particle in the visualiser and to calculate some single
particle properties, such as the excluded volume.

Type="Null"

Description

The "Null" Interaction is used to mark particle
pairs out as non-interacting. All particle pairs must have a
corresponding Interaction defined, so this Interaction is the only
way to prevent events being generated for a set of particle pairs.

Example usage

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "Null" to select this Interaction type.

Name(attribute): The name of the
Interaction. This name is used to identify the Interaction in
the configuration file (e.g.,
see Species) and in the output generated
by the dynarun command. Each Interaction must have a name which
is unique.

Type="HardSphere"

Description

The "HardSphere" Interaction implements the
hard-sphere interaction potential. This is one of the simplest
event-driven potentials available.

A hard sphere is a simple molecular model used to capture the
fundamental effects of "excluded-volume" interactions. You may think
of the hard-sphere fluid as an extension of the ideal-gas model,
where each molecule now has a diameter, $\sigma$, and cannot overlap
the volume of this diameter with the volume of other molecules. The
parameters of this model are illustrated below:

The interparticle potential energy of a hard-sphere molecule.

where $u(r)$ is the interparticle potential (which is the potential
energy between two particles separated by a distance of
$r$). Particles do not interact at separations greater than the
diameter of the molecule ($u(r)=0$ for $r\in[\sigma,\,\infty]$). The
infinite interaction energy of the hard core ($u(r)=+\infty$ for
$r\in[0,\,\sigma]$) makes it energetically impossible for particles
to "overlap", therefore the particles will elastically bounce-off of
each other when they come into contact.

The effects of this additional "excluded volume" interaction is
dramatic and leads to complex transport coefficients as a function of
density and the appearance of a fluid-solid freezing transition. This
model is too simple to capture any complex temperature effects, such
as a liquid/gas phase transition, as it has no finite interaction
energies (unlike the square-well
fluid). Despite its simplicity, the structure of many real
crystals is dominated by the repulsive "excluded-volume" interactions
caused by overlapping electron clouds which may be effectively
captured by the hard-sphere model. It is also at the heart of kinetic
theory which is the most successful attempt to predict the transport
properties of fluids from their molecular interactions. The
interparticle potential of this model is given in the figure below:

Collision rule

To perform an interaction we need a collision rule which calculates
the post-collision velocities of the two particles undergoing the
Interaction. The collision rule expresses the post-collision
velocities in terms of the pre-collision values.

Using the definition of the relative velocity
$\boldsymbol{v}_{ij}=\boldsymbol{v}_{i}-\boldsymbol{v}_{j}$ of two
particles $i$ and $j$, and the identities
$\boldsymbol{v}_i=\boldsymbol{v}_{ij}+\boldsymbol{v}_j$ and
$\boldsymbol{v}_j=\boldsymbol{v}_i-\boldsymbol{v}_{ij}$, we have
\[\begin{align}
\boldsymbol{v}_j'-\boldsymbol{v}_j&=\boldsymbol{v}_i'-\boldsymbol{v}_i - \boldsymbol{v}_{ij}'+\boldsymbol{v}_{ij}
\end{align}\]
where the primes denote post-collision values. Using the conservation
of momentum, we can write
\[\begin{align}
m_i\,\boldsymbol{v}_i'+m_j\,\boldsymbol{v}_j'&=m_i\,\boldsymbol{v}_i+m_j\,\boldsymbol{v}_j\\
\boldsymbol{v}_i'-\boldsymbol{v}_i&=-\frac{m_j}{m_i}\left(\boldsymbol{v}_j'-\boldsymbol{v}_j\right)
\end{align}\]
where $m_i$ is the mass of particle $i$. Using the equation
derived from the conservation of momentum to eliminate
$\boldsymbol{v}_j$ terms, we have
\[\begin{align}
\boldsymbol{v}_i'-\boldsymbol{v}_i&=-\frac{m_j}{m_i}\left(\boldsymbol{v}_i'-\boldsymbol{v}_i - \boldsymbol{v}_{ij}'+\boldsymbol{v}_{ij}\right)\\
&=m_i^{-1}\,\mu\left(\boldsymbol{v}_{ij}'-\boldsymbol{v}_{ij}\right)
\end{align}\]
where $\mu_{ij}=\left(m_i^{-1}+m_j^{-1}\right)^{-1}$ is the reduced
mass. Therefore we can calculate the post-collision velocities of the
particles if we know the change in the relative velocities. For smooth
particles the velocities only change along the line of contact, and we
have:
\[\begin{align*}
\left[\boldsymbol{v}_{ij}'\right]_\parallel&=-\varepsilon\left[\boldsymbol{v}_{ij}\right]_\parallel &
\left[\boldsymbol{v}_{ij}'\right]_\perp&=\left[\boldsymbol{v}_{ij}\right]_\perp
\end{align*}\]
where $\varepsilon$ is the elasticity/coefficient of restitution
and the subscript $\parallel$ and $\perp$ denote the components
parallel and perpendicular to the line of contact. These are
calculated like so
$\boldsymbol{v}_{ij,\parallel}=\hat{\boldsymbol{r}}_{ij}\left(\hat{\boldsymbol{r}}_{ij}\cdot\boldsymbol{v}_{ij}\right)$
and
$\boldsymbol{v}_{ij,\perp}=-\hat{\boldsymbol{r}}_{ij}\times\left(\hat{\boldsymbol{r}}_{ij}\times\boldsymbol{v}_{ij}\right)$
where $\hat{\boldsymbol{r}}_{ij}$ is the unit vector in the
direction of the relative separation at contact,
$\boldsymbol{r}_{ij}=\boldsymbol{r}_i-\boldsymbol{r}_j$, and
$\boldsymbol{r}_i$ is the position of particle $i$. Combining
these rules results in the following expression
\[\begin{align*}
\boldsymbol{v}_{ij}'-\boldsymbol{v}_{ij}=-(1+\varepsilon)\left(\hat{\boldsymbol{r}}_{ij}\cdot\boldsymbol{v}_{ij}\right)\hat{\boldsymbol{r}}_{ij}
\end{align*}\]
This leads to the final expressions for smooth particles:
\[\begin{align}
\boldsymbol{v}_i'-\boldsymbol{v}_i&=-m_i^{-1}\,\mu_{ij}(1+\varepsilon)\left(\hat{\boldsymbol{r}}_{ij}\cdot\boldsymbol{v}_{ij}\right)\hat{\boldsymbol{r}}_{ij}\\
\boldsymbol{v}_j'-\boldsymbol{v}_j&=+m_j^{-1}\,\mu_{ij}(1+\varepsilon)\left(\hat{\boldsymbol{r}}_{ij}\cdot\boldsymbol{v}_{ij}\right)\hat{\boldsymbol{r}}_{ij}
\end{align}\]
In rough systems, particles will change rotation due to
interactions. To define the dynamics in such a system we need to
consider the relative surface velocity at the point of contact,
$\boldsymbol{g}_{ij}$, calculated as follows \[\begin{align*}
\boldsymbol{g}_{ij}&=\left(\boldsymbol{v}_i-\boldsymbol{\omega}_i\times
R_i\,\hat{\boldsymbol{r}}_{ij}\right)-\left(\boldsymbol{v}_j+\boldsymbol{\omega}_j\times
R_j\hat{\boldsymbol{r}}_{ij}\right)\\
&=\boldsymbol{v}_{ij}-\left(R_i\,\boldsymbol{\omega}_i+R_j\,\boldsymbol{\omega}_j\right)\times\hat{\boldsymbol{r}}_{ij}
\end{align*}\] where $\boldsymbol{\omega}_j$ is the angular velocity
and $R_i$ is the radus of particle $i$. In this case, we can define a
normal and a tangential coefficient of restitution as follows
\[\begin{align}
\left[\boldsymbol{g}_{ij}\right]_\parallel'&=-\varepsilon^n\left[\boldsymbol{g}_{ij}\right]_\parallel
&
\left[\boldsymbol{g}_{ij}\right]_\perp'&=\varepsilon^t\left[\boldsymbol{g}_{ij}\right]_\perp
\end{align}\]
where
$\boldsymbol{g}_{ij,\parallel}=\hat{\boldsymbol{r}}_{ij}\left(\hat{\boldsymbol{r}}_{ij}\cdot\boldsymbol{g}_{ij}\right)$
and
$\boldsymbol{g}_{ij,\perp}=-\hat{\boldsymbol{r}}_{ij}\times\left(\hat{\boldsymbol{r}}_{ij}\times\boldsymbol{g}_{ij}\right)$. Noting
that
$\boldsymbol{x}=\hat{\boldsymbol{e}}(\hat{\boldsymbol{e}}\cdot\boldsymbol{x})-\hat{\boldsymbol{e}}\times\left(\hat{\boldsymbol{e}}\times\boldsymbol{x}\right)$,
these definitions lead to the following expressions
\[\begin{align*}
\hat{\boldsymbol{r}}_{ij}\left(\hat{\boldsymbol{r}}_{ij}\cdot\left[\boldsymbol{g}_{ij}'-\boldsymbol{g}_{ij}\right]\right)&=-(1+\varepsilon^n)\hat{\boldsymbol{r}}_{ij}\left(\hat{\boldsymbol{r}}_{ij}\cdot\boldsymbol{g}_{ij}\right)
&
\hat{\boldsymbol{r}}_{ij}\times\left(\hat{\boldsymbol{r}}_{ij}\times\left[\boldsymbol{g}_{ij}'-\boldsymbol{g}_{ij}\right]\right)&=(\varepsilon^t-1)\hat{\boldsymbol{r}}_{ij}\times\left(\hat{\boldsymbol{r}}_{ij}\times\boldsymbol{g}_{ij}\right)
\end{align*}\]
We need to find an expression which closes the linear momentum balance
by providing a relationship between $\boldsymbol{v}_{ij}'-\boldsymbol{v}_{ij}$ and
$\boldsymbol{g}_{ij}'-\boldsymbol{g}_{ij}$, as well as determining how the angular velocity
changes. Beginning with the angular velocity, we take the contact
point as the origin about which the angular momentum is defined. We
then note that all contact forces act through the origin and see that
angular velocity is conserved for both particles separately. Thus we
will have two separate angular-momentum conservation rules:
\[\begin{align*}
m_i\,R_i\,\hat{\boldsymbol{r}}_{ij}\times\boldsymbol{v}_i' + \boldsymbol{I}_i\cdot\boldsymbol{\omega}_i' &= m_i\,R_i\,\hat{\boldsymbol{r}}_{ij}\times\boldsymbol{v}_i + \boldsymbol{I}_i\cdot\boldsymbol{\omega}_i\\
m_j\,R_j\,\hat{\boldsymbol{r}}_{ij}\times\boldsymbol{v}_j' - \boldsymbol{I}_j\cdot\boldsymbol{\omega}_j' &= m_j\,R_j\,\hat{\boldsymbol{r}}_{ij}\times\boldsymbol{v}_j - \boldsymbol{I}_j\cdot\boldsymbol{\omega}_j
\end{align*}\]
For symmetric objects we have an isotropic inertia tensor
$\boldsymbol{I}_i=I_i\,\boldsymbol{1}$, and can define a reduced moment of inertia as
$\tilde{I}_i=I_i/m_i\,R_i^2$ and can rearrange these two equations
like so
\[\begin{align*}
\boldsymbol{\omega}_i'- \boldsymbol{\omega}_i&=- R_i^{-1}\tilde{I}_i^{-1}\left[\hat{\boldsymbol{r}}_{ij}\times\left(\boldsymbol{v}_i' -\boldsymbol{v}_i\right)\right]\\
\boldsymbol{\omega}_j'- \boldsymbol{\omega}_j &= + R_j^{-1}\tilde{I}_j^{-1}\left[\hat{\boldsymbol{r}}_{ij}\times\left(\boldsymbol{v}_j' -\boldsymbol{v}_j\right)\right]
\end{align*}\]
We need to find the post-collision linear velocities to close these
expressions. We can define the pre and post collision relative
velocity at the surface as follows
\[\begin{align*}
\boldsymbol{g}_{ij}&=\left(\boldsymbol{v}_i-\boldsymbol{\omega}_i\times
R_i\,\hat{\boldsymbol{r}}_{ij}\right)-\left(\boldsymbol{v}_j+\boldsymbol{\omega}_j\times
R_j\hat{\boldsymbol{r}}_{ij}\right)\\
&=\boldsymbol{v}_{ij}-\left(R_i\,\boldsymbol{\omega}_i+R_j\,\boldsymbol{\omega}_j\right)\times\hat{\boldsymbol{r}}_{ij}
\end{align*}\]
Finding the post collision value of this
\[\begin{align*}
\boldsymbol{g}_{ij}'&=\boldsymbol{v}_{ij}'-\left(R_i\,\boldsymbol{\omega}_i'+R_j\,\boldsymbol{\omega}_j'\right)\times\hat{\boldsymbol{r}}_{ij}\\
&=\boldsymbol{v}_{ij}' - \left(R_i\left(\boldsymbol{\omega}_i - R_i^{-1}\,\tilde{I}_i^{-1}\left[\hat{\boldsymbol{r}}_{ij}\times\left(\boldsymbol{v}_i' -\boldsymbol{v}_i\right)\right]\right)+R_j\left(\boldsymbol{\omega}_j + R_j^{-1}\,\tilde{I}_j^{-1}\left[\hat{\boldsymbol{r}}_{ij}\times\left(\boldsymbol{v}_j' -\boldsymbol{v}_j\right)\right]\right)\right)\times\hat{\boldsymbol{r}}_{ij}\\
&=\boldsymbol{v}_{ij}'-\left(R_i\,\boldsymbol{\omega}_i +
R_j\,\boldsymbol{\omega}_j\right)\times\hat{\boldsymbol{r}}_{ij} +
\left(\tilde{I}_i^{-1}\left[\hat{\boldsymbol{r}}_{ij}\times\left(\boldsymbol{v}_i'
-\boldsymbol{v}_i\right)\right]
-\tilde{I}_j^{-1}\left[\hat{\boldsymbol{r}}_{ij}\times\left(\boldsymbol{v}_j'
-\boldsymbol{v}_j\right)\right]\right)\times\hat{\boldsymbol{r}}_{ij}
\end{align*}\]
Subtracting the pre-collision value from this value, and assuming that
all particles have the same reduced moment of inertia, we have
\[\begin{align*}
\boldsymbol{g}_{ij}'-\boldsymbol{g}_{ij}&=\boldsymbol{v}_{ij}'-\boldsymbol{v}_{ij}+
\tilde{I}^{-1}\left(\left[\hat{\boldsymbol{r}}_{ij}\times\left(\boldsymbol{v}_i'
-\boldsymbol{v}_i\right)\right]
-\left[\hat{\boldsymbol{r}}_{ij}\times\left(\boldsymbol{v}_j'
-\boldsymbol{v}_j\right)\right]\right)\times\hat{\boldsymbol{r}}_{ij}\\
&=\boldsymbol{v}_{ij}'-\boldsymbol{v}_{ij}-
\tilde{I}^{-1}\,\hat{\boldsymbol{r}}_{ij}\times\left[\hat{\boldsymbol{r}}_{ij}\times\left(\boldsymbol{v}_{ij}'
-\boldsymbol{v}_{ij}\right)\right]
\end{align*}\]
Now that we have the relationship between $\boldsymbol{g}_{ij}'-\boldsymbol{g}_{ij}$
and $\boldsymbol{v}_{ij}'-\boldsymbol{v}_{ij}$, we look to insert the coefficients of
restitution. We notice that the second term is perpendicular to
$\hat{\boldsymbol{r}}_{ij}$, therefore we have
\[\begin{align}
\hat{\boldsymbol{r}}_{ij}\cdot\left(\boldsymbol{v}_{ij}'-\boldsymbol{v}_{ij}\right) = \hat{\boldsymbol{r}}_{ij}\cdot\left(\boldsymbol{g}_{ij}'-\boldsymbol{g}_{ij}\right)
\end{align}\]
Taking the vector product instead and we have
\[\begin{align*}
\hat{\boldsymbol{r}}_{ij}\times\left[\boldsymbol{g}_{ij}'-\boldsymbol{g}_{ij}\right] &=\hat{\boldsymbol{r}}_{ij}\times\left[\boldsymbol{v}_{ij}'-\boldsymbol{v}_{ij}\right]-
\tilde{I}^{-1}\hat{\boldsymbol{r}}_{ij}\times\left[\hat{\boldsymbol{r}}_{ij}\times\left[\hat{\boldsymbol{r}}_{ij}\times\left(\boldsymbol{v}_{ij}'
-\boldsymbol{v}_{ij}\right)\right]\right]
\end{align*}\]
we note that
$\hat{\boldsymbol{e}}\times\left(\hat{\boldsymbol{e}}\times\left(\hat{\boldsymbol{e}}\times\boldsymbol{x}\right)\right)=-\hat{\boldsymbol{e}}\times\boldsymbol{x}$,
giving
\[\begin{align}
\hat{\boldsymbol{r}}_{ij}\times\left[\boldsymbol{g}_{ij}'-\boldsymbol{g}_{ij}\right]
&=\hat{\boldsymbol{r}}_{ij}\times\left[\boldsymbol{v}_{ij}'-\boldsymbol{v}_{ij}\right]+
\tilde{I}^{-1}\,\hat{\boldsymbol{r}}_{ij}\times\left(\boldsymbol{v}_{ij}'
-\boldsymbol{v}_{ij}\right)\nonumber\\
\hat{\boldsymbol{r}}_{ij}\times\left[\boldsymbol{v}_{ij}'-\boldsymbol{v}_{ij}\right]&=\left(1+\tilde{I}^{-1}\right)^{-1}\hat{\boldsymbol{r}}_{ij}\times\left[\boldsymbol{g}_{ij}'-\boldsymbol{g}_{ij}\right]
\end{align}\]
Noting again that in general we have
$\boldsymbol{x}=\hat{\boldsymbol{e}}(\hat{\boldsymbol{e}}\cdot\boldsymbol{x})-\hat{\boldsymbol{e}}\times\left(\hat{\boldsymbol{e}}\times\boldsymbol{x}\right)$, and
we can write
\[\begin{align}
\boldsymbol{v}_{ij}'-\boldsymbol{v}_{ij}&=\hat{\boldsymbol{r}}_{ij}\left(\hat{\boldsymbol{r}}_{ij}\cdot(\boldsymbol{v}_{ij}'-\boldsymbol{v}_{ij})\right) -\hat{\boldsymbol{r}}_{ij}\times\left[\hat{\boldsymbol{r}}_{ij}\times\left(\boldsymbol{v}_{ij}'-\boldsymbol{v}_{ij}\right)\right]\\
&=\hat{\boldsymbol{r}}_{ij}\left(\hat{\boldsymbol{r}}_{ij}\cdot\left(\boldsymbol{g}_{ij}'-\boldsymbol{g}_{ij}\right)\right) -\left(1+\tilde{I}^{-1}\right)^{-1}\hat{\boldsymbol{r}}_{ij}\times\left[\hat{\boldsymbol{r}}_{ij}\times\left[\boldsymbol{g}_{ij}'-\boldsymbol{g}_{ij}\right]\right]
\end{align}\]
Inserting in the coefficients of restitution, we have
\[\begin{align}
\boldsymbol{v}_{ij}'-\boldsymbol{v}_{ij}&=-(1+\varepsilon^n)\hat{\boldsymbol{r}}_{ij}\left(\hat{\boldsymbol{r}}_{ij}\cdot\boldsymbol{g}_{ij}\right) -\left(1+\tilde{I}^{-1}\right)^{-1}(\varepsilon^t-1)\hat{\boldsymbol{r}}_{ij}\times\left(\hat{\boldsymbol{r}}_{ij}\times\boldsymbol{g}_{ij}\right)
\end{align}\]
Using this we can complete the expression for the linear velocity
change:
\[\begin{align}
\boldsymbol{v}_i'-\boldsymbol{v}_i&=-m_i^{-1}\,\mu_{ij}\left((1+\varepsilon^n)
\hat{\boldsymbol{r}}_{ij}\left(\hat{\boldsymbol{r}}_{ij}\cdot\boldsymbol{g}_{ij}\right)
+\left(1+\tilde{I}^{-1}\right)^{-1}(\varepsilon^t-1)
\hat{\boldsymbol{r}}_{ij}\times\left(\hat{\boldsymbol{r}}_{ij}\times\boldsymbol{g}_{ij}\right)\right)
\end{align}\]
Inserting this into the expression for the change in angular velocity,
we have
\[\begin{align*}
\boldsymbol{\omega}_i'- \boldsymbol{\omega}_i&=- R_i^{-1}\tilde{I}_i^{-1}\left[\hat{\boldsymbol{r}}_{ij}\times\left(\boldsymbol{v}_i' -\boldsymbol{v}_i\right)\right]\\
&=
m_i^{-1}\,\mu_{ij}\,R_i^{-1}\left(1+\tilde{I}\right)^{-1}(\varepsilon^t-1)\hat{\boldsymbol{r}}_{ij}\times\left[
\hat{\boldsymbol{r}}_{ij}\times\left(\hat{\boldsymbol{r}}_{ij}\times\boldsymbol{g}_{ij}\right)\right]\\
&=
-m_i^{-1}\,\mu_{ij}\,R_i^{-1}\left(1+\tilde{I}\right)^{-1}(\varepsilon^t-1)\hat{\boldsymbol{r}}_{ij}\times\boldsymbol{g}_{ij}
\end{align*}\]
The corresponding rules for particle $j$ follow with similar
reasoning or through relabing and noting that
$\boldsymbol{g}_{ji}=-\boldsymbol{g}_{ij}$. In summary, we have

\[\begin{align*}
\boldsymbol{v}_i'-\boldsymbol{v}_i&=-\frac{\mu_{ij}}{m_i}\left((1+\varepsilon^n)
\hat{\boldsymbol{r}}_{ij}\left(\hat{\boldsymbol{r}}_{ij}\cdot\boldsymbol{g}_{ij}\right)
+\frac{\varepsilon^t-1}{1+\tilde{I}^{-1}}
\hat{\boldsymbol{r}}_{ij}\times\left(\hat{\boldsymbol{r}}_{ij}\times\boldsymbol{g}_{ij}\right)\right)\\
\boldsymbol{v}_j'-\boldsymbol{v}_j&=\frac{\mu_{ij}}{m_j}\left((1+\varepsilon^n)
\hat{\boldsymbol{r}}_{ij}\left(\hat{\boldsymbol{r}}_{ij}\cdot\boldsymbol{g}_{ij}\right)
+\frac{\varepsilon^t-1}{1+\tilde{I}^{-1}}
\hat{\boldsymbol{r}}_{ij}\times\left(\hat{\boldsymbol{r}}_{ij}\times\boldsymbol{g}_{ij}\right)\right)\\
\boldsymbol{\omega}_i'-
\boldsymbol{\omega}_i&=-\frac{\mu_{ij}(\varepsilon^t-1)}{m_i\,R_i\left(1+\tilde{I}\right)}
\hat{\boldsymbol{r}}_{ij}\times\boldsymbol{g}_{ij}
\\
\boldsymbol{\omega}_j'-
\boldsymbol{\omega}_j&=-\frac{\mu_{ij}(\varepsilon^t-1)}{m_j\,R_j\left(1+\tilde{I}\right)}\hat{\boldsymbol{r}}_{ij}\times\boldsymbol{g}_{ij}
\end{align*}\]
where $\varepsilon^n$ and $\varepsilon^t$ are the normal and
tangential coefficient of elasticity respectively. See the
derivation above for more information on the symbols and their
meaning.

Example usage

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "HardSphere" to select this Interaction type.

Diameter(attribute): The interaction diameter
($\sigma$) of the particle pairs corresponding to this
Interaction.
This attribute is a Property specifier with a unit
of Length (see the section on
Properties for more information).

Elasticity(attribute): This is an optional
attribute. The elasticity, $\varepsilon^n$, controls the dissipation of
translational energy between interacting particles. This value is
typically 1 for molecular systems and between zero and one for
granular systems. If the attribute is unset, it is equivalent
to Elasticity="1".
This attribute is a Property specifier
with Dimensionless units (see
the section on Properties for more
information).

TangentialElasticity(attribute): This is an
optional attribute. The tangential elasticity, $\varepsilon^t$,
controls the dissipation/generation of energy between interacting
particles in the tangential/rotational direction and is typically
in the range $[-1,1]$. If the tangential elasticity is one, there
is no tangential interaction,
whereas TangentialElasticity="-1" corresponds to a complete
reversal of the relative surface velocities. It is important to
note that setting the TangentialElasticity attribute
requires that the particles have a Species
with inertia information. If the attribute is unset then
rotational dynamics are ignored and the particles can have
any Species type.
This attribute is a Property specifier
with Dimensionless units (see
the section on Properties for more
information).

Name(attribute): The name of the Interaction. This
name is used to identify the Interaction in the output generated
by the dynarun command. Each Interaction must have a name which is
unique.

Type="SquareWell"

Description

The "SquareWell" Interaction implements the
square-well interaction potential, illustrated in the figure below.

A square-well molecule is a particle which has a hard-core diameter
of $\sigma$ and is surrounded by an attractive well with a diameter
of $\lambda\,\sigma$ and a depth of $\varepsilon$. These variables
are illustrated in the diagram below:

A diagram of a square-well molecule including its parameters.

where $u(r)$ is the interparticle potential (which is the potential
energy between two particles separated by a distance of $r$).

Square-well molecules are simple models which display the two
fundamental features of real molecules, a short range repulsion (due
to overlapping electron clouds) and longer ranged attraction (due to
van-der-waals/London/dispersion forces). A comparison of the
square-well model (black) and a "realistic" interatomic potential
(red) is given in
the figure below:

A comparision of a square-well potential and a "realistic" potential..

It is clear that the square-well potential is a rough approximation
of the "realistic" potential, but its dynamics are not immediately
clear. With the "realistic" potential, it is easy to see how a pair
of particles might "fall down" the potential and attract or repulse
each other, but how does this behaviour appear in the square-well
model? When two distant square-well particles approach each other
and reach a separation of $r=\lambda\,\sigma$, they enter the well
(or "capture" each other) and a momentum impulse increases their
kinetic energy by $\varepsilon$ (they are attracted to each
other). If they then approach the inner core and reach a separation
of $r=\sigma$, they will be unable to pay the infinite energy cost
to enter the core and will instead elastically bounce off it. Once
they begin to retreat from each other (either by bouncing off the
core or by missing it) and reach a separation of
$r=\lambda\,\sigma$, they must have enough kinetic energy in the
direction of the well to escape it and pay the energy cost,
$\varepsilon$, otherwise they will bounce off the inside of the well
(both are attractive interactions).

If we used more steps to more accurately approximate the "realistic"
potential (see the "Stepped" type
Interaction), we can quite quickly capture the full behaviour of
the smooth/"realistic" potential. However, the square-well model is
so interesting because it is so simple! We can make progress in
understanding it theoretically and, if we can understand the
fundamental behaviour of square-well molecules, the fundamental
behaviour of realistic potentials can also be explained.

Example usage

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "SquareWell" to select this Interaction type.

Diameter(attribute): The interaction diameter
($\sigma$) of the particle pairs corresponding to this
Interaction.
This attribute is a Property specifier with a
unit of Length (see the section on
Properties for more information).

Elasticity(attribute): The elasticity of the
particle pairs corresponding to this Interaction. This value is
typically 1 for molecular systems and between zero and one for
granular systems.
This attribute is a Property specifier with
Dimensionless units (see the section on
Properties for more information).

Lambda(attribute): The well-width factor
($\lambda$) of the particle pairs corresponding to this
Interaction. Values below 1 are not valid.
This attribute is a Property specifier with
Dimensionless units (see
the section on Properties for more
information).

WellDepth(attribute): The interaction energy
($\varepsilon$) of the particle pairs corresponding to this
Interaction.
This attribute is a Property specifier with a unit
of Energy (see the section on
Properties for more information).

Name(attribute): The name of the Interaction. This
name is used to identify the Interaction in the output generated
by the dynarun command. Each Interaction must have a name which is
unique.

CaptureMap(tag): If present, the CaptureMap tag
should store the particle pairs which are within the well. If it
is not present, it will be automatically generated when the
configuration is next loaded by dynarun or dynamod. The data in
this tag must be correct at all times otherwise errors in the
dynamics will occur so take care when manually editing the
configuration file. See the reference entry
on CaptureMap for more details.

Example usage

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "ParallelCubes" to select this Interaction type.

Diameter(attribute): The interaction diameter is
the length at which the particle pairs collide with this
Interaction (the length of a cube side).
This attribute is a Property specifier with a unit of
Length (see the section on
Properties for more information).

Elasticity(attribute): The elasticity of the
particle pairs corresponding to this Interaction. This value is
typically 1 for molecular systems and between zero and one for
granular systems.
This attribute is a Property specifier
with Dimensionless units (see
the section on Properties for more
information).

Name(attribute): The name of the Interaction. This
name is used to identify the Interaction in the output generated
by the dynarun command. Each Interaction must have a name which is
unique.

Example usage

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "Lines" to select this Interaction type.

Length(attribute): The length of the lines.
This attribute is a Property specifier with a unit
of Length (see the section on
Properties for more information).

Elasticity(attribute): The elasticity of the
particle pairs corresponding to this Interaction. This value is
typically 1 for molecular systems and between zero and one for
granular systems.
This attribute is a Property specifier with
Dimensionless units (see
the section on Properties for more
information).

Name(attribute): The name of the Interaction. This
name is used to identify the Interaction in the output generated
by the dynarun command. Each Interaction must have a name which is
unique.

Type="Stepped"

Description

The "Stepped" Interaction wraps a generic spherically-symmetric
stepped Potential and uses it for
two-particle interactions. This can be used to implement many simple
systems (hard-spheres, square-wells) and many complex systems such
as a discontinuous Lennard-Jones potential. An alternative approach
is to use a "Umbrella" System event to
bind collections of particles together using
a Potential.

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "Stepped" to select this Interaction type.

Name(attribute): The name of the Interaction. This
name is used to identify the Interaction in the output generated
by the dynarun command. Each Interaction must have a name which is
unique.

LengthScale(attribute): The length scale by which
the Potential is scaled for each
particle. For example, if
a Lennard-Jones type
Potential is used, this sets the $\sigma$ value for each
particle.
This attribute is a Property specifier with a unit
of Length (see the section on
Properties for more information).

EnergyScale(attribute): The energy scale by which
the Potential is scaled for each
particle. For example, if
a Lennard-Jones type
Potential is used, this sets the $\varepsilon$ value for each
particle.
This attribute is a Property specifier with a unit
of Length (see the section on
Properties for more information).

Potential(tag):
The Potential tag specifies the stepped
potential used for this interaction. Please see the section on
the Potential tag for more information.

CaptureMap(tag): If present, the CaptureMap tag
should store the current step of any particle pairs which are
inside the Interaction range of the potential. If it is not
present, it will be automatically generated when the configuration
is next loaded by dynarun or dynamod. The data in this tag must be
correct at all times otherwise errors in the dynamics will occur
so take care when manually editing the configuration file. See the
reference entry on CaptureMap for more
details.

Type="ThinThread"

Description

The "ThinThread" Interaction implements a
square-well potential which has hysteresis. The particle behaves as
a hard sphere, but once a pair of particles collide with the hard
core, they enter the well. The energy of this well must be paid to
escape, thus the model loses energy each time particles enter the
well. Once particles escape the well, they must again collide with
the core before they can re-enter the well (as illustrated in the
figure below). This model may be used to model wet granulate and the
formation of liquid bridges as when wet granular particles contact
each other a liquid bridge stretches between them. Breaking this
bridge requires an amount of energy and distance to overcome the
surface tension (modelled by the well), but once the bridge is
broken the particles will only interact again at short distances.

The interaction
potential of a thin thread molecule demonstrating its hysteresis and
its parameters

Example usage

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "ThinThread" to select this Interaction type.

Diameter(attribute): The interaction diameter
($\sigma$) of the particle pairs corresponding to this
Interaction.
This attribute is a Property specifier with a unit
of Length (see the section on
Properties for more information).

Elasticity(attribute): The elasticity of the
particle pairs corresponding to this Interaction. This value is
typically 1 for molecular systems and between zero and one for
granular systems.
This attribute is a Property specifier with
Dimensionless units (see
the section on Properties for more
information).

Lambda(attribute): The well-width factor
($\lambda$) of the particle pairs corresponding to this
Interaction. Values below 1 are not valid.
This attribute is a Property specifier with
Dimensionless units (see
the section on Properties for more
information).

WellDepth(attribute): The interaction energy
($\varepsilon$) of the particle pairs corresponding to this
Interaction.
This attribute is a Property specifier with a unit
of Energy (see the section on
Properties for more information).

Name(attribute): The name of the Interaction. This
name is used to identify the Interaction in the output generated
by the dynarun command. Each Interaction must have a name which is
unique.

CaptureMap(tag): If present, the CaptureMap tag
should store the particle pairs which are within the well. If it
is not present, it will be automatically generated when the
configuration is next loaded by dynarun or dynamod. The data in
this tag must be correct at all times otherwise errors in the
dynamics will occur so take care when manually editing the
configuration file. See the reference entry
on CaptureMap for more details.

Example usage

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "SquareBond" to select this Interaction type.

Diameter(attribute): The interaction diameter
($\sigma$) of the particle pairs corresponding to this
Interaction.
This attribute is a Property specifier with a unit
of Length (see the section on
Properties for more information).

Elasticity(attribute): The elasticity of the
particle pairs corresponding to this Interaction. This value is
typically 1 for molecular systems and between zero and one for
granular systems.
This attribute is a Property specifier with
Dimensionless units (see
the section on Properties for more
information).

Lambda(attribute): The bond-width factor
($\lambda$) of the particle pairs corresponding to this
Interaction. Values below 1 are not valid.
This attribute is a Property specifier with
Dimensionless units (see
the section on Properties for more
information).

Name(attribute): The name of the Interaction. This
name is used to identify the Interaction in the output generated
by the dynarun command. Each Interaction must have a name which is
unique.

CaptureMap

CaptureMaps are used by DynamO to track which particles are
currently interacting with other particles using that
Interaction. For example,
the SquareWell
type Interactions uses the capture map to record all
pairs of particles who are inside each others attractive well. This
information must be saved and loaded with the configuration file as,
if a particle is on the edge of the well, it is impossible to
determine if they are captured or not from their position
alone. Without using a CaptureMap, this ambiguity would lead to the
simulation either losing or gaining energy after a save/load.

If DynamO does not see a CaptureMap in the configuration
file, but the Interaction requires one it will automatically
calculate the CaptureMap from the particle positions.

Whenever we change a configuration file by hand, its very likely
that we will invalidate any data stored within CaptureMap
tags inside the file. The simplest way of correcting this error is
to delete the CaptureMap tags. This forces DynamO to rebuild
them when it next loads the configuration file. You should note that
deleting the CaptureMap might cause the potential energy of the
system to change slightly, so it should be avoided if energy
conservation is desired.

Local

Locals are sources of events for particles where each event only
involves a single particle and this event only occurs when the
particle is within certain regions of the simulation. The standard
example of a Local is a wall or some other boundary of the
simulation.

Type="Wall"

Description

The "Wall" Local implements an infinite
plane/wall. This Local is typically used as a boundary of the
simulation and may also be "thermalised" to inject or remove energy
from the system. As these planes/walls are infinite, you must take
care that they are axis-aligned if the system is periodic. They are
not compatible with shearing simulations
(see Lees-Edwards boundary conditions) unless the
normal is aligned with the $y$-axis (which would defeat the purpose
of using Lees-Edwards boundaries).

Example usage

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "Wall" to select this Interaction type.

Diameter(attribute): The diameter of the
particles which interact with this wall. Although the diameter
must be given here (to be consistent with Interactions), you
should note that particles actually collide with the wall when
they reach a separation equal to half the diameter.
This attribute is a Property specifier with a unit
of Length (see the section on
Properties for more information).

Elasticity(attribute): The elasticity of the
particle collisions. This value is typically 1 for molecular
systems and between zero and one for granular systems.
This attribute is a Property specifier with
Dimensionless units (see
the section on Properties for more
information).

Temperature(attribute): The temperature is an
optional tag. If it is present, whenever a particle hits the
wall, the normal component of its velocity will be randomly
reassigned from a distribution with the specified
temperature. If it is not present, the particles will collide
according to the elasticity.

Name(attribute): The name of the Local. This name
is used to identify the Local in the output generated by the
dynarun command. Each Local must have a name which is
unique.

Norm(tag): The normal of the plane of the
wall. The value is renormalised by DynamO on load.

x(attribute): The $x$-component of the normal.

y(attribute): The $y$-component of the normal.

z(attribute): The $z$-component of the normal.

Origin(tag): A point on the plane of the
wall.

x(attribute): The $x$-coordinate of the point.

y(attribute): The $y$-coordinate of the point.

z(attribute): The $z$-coordinate of the point.

Global

Globals, like Locals, specify events which only affect a single
particle in the system. The difference between Globals and Locals is
that a Global event will occur to a particle, regardless of its
location in the system. The most common type of Global used is the
cellular neighbour list.

Type="Cells"

Description

The "Cells" Global implements a cellular
neighbour list, which may be used by the Scheduler to optimise the
simulation. The neighbourlist will track all particles that match
its IDRange and can provide information on which tracked particles
are within the neighbourhood of other particles or points.

Example usage

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "Cells" to select this Global type.

Name(attribute): The name of the Global. This
name is used to identify the Global in the output generated by
the dynarun command. Each Global must have a name which is
unique. In particular, if this cellular neighbour list is to be
used by the "NeighbourList" type Scheduler, it should have the
name "SchedulerNBList".

NeighbourhoodRange(attribute): This optional
attribute sets the minimum distance at which particles are
considered to be in the neighbourhood of other particles or
points. If the neighbour list is used by
the "NeighbourList" type
Scheduler, this distance should be at least equal to or
greater than the maximum Interaction distance in the system. If
this tag is unset, the maximum interaction distance is
automatically calculated.

IDRange(tag): This IDRange tag specifies the
particles which are tracked in the cellular neighbour list. See
the section on IDRanges for more
information on the format of this tag.

System

System tags represent events which are unique. There is only one
event time generated by a System, and this event may alter zero or
many particles at once. If an event type does not fit into the
categories of
Global, Local,
or Interaction, it will be implemented
via a System event. The most common type of system event is the
Andersen thermostat.

Type="Andersen"

Description

The "Andersen" System implements an Andersen
thermostat. An Andersen thermostat functions by randomly reassigning
the velocities of individual particles from a Gaussian distribution
with a specified temperature. These reassignments occur at random
time intervals given by a Poisson distribution with a specified mean
free time.

This thermostat adds thermal "noise" into the system, and so
dynamical properties will be affected by its action. To avoid
completely losing the dynamics of the system, the thermostat is
usually controlled to ensure that only a certain fraction of the
total events of the system are thermostat events. In DynamO, this
fraction is specified by a
SetPoint attribute. Every SetFrequency events, the
mean free time of the thermostat is adjusted to try to match
the SetPoint.

If you want the mean free time to remain fixed during a simulation
and want to disable the frequency control please ensure that you do
not define the SetFrequency or
SetPoint attributes. If either attribute is missing the
frequency control will be disabled.

Example usage

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "Andersen" to select this System type.

Name(attribute): The name of the System event. This
name is used to identify the System in the output generated by the
dynarun command. Each System must have a name which is unique.

MFT(attribute): The current mean free time over
which the thermostat is applied. Please note, this is the
mean free time of the thermostat not the mean free time
per particle.

Temperature(attribute): The temperature ($k_B\,T$)
of the thermostat.

SetPoint(attribute): This attribute is optional and
only takes effect if the SetFrequency attribute is also
defined. The target fraction of events which should be
applications of the thermostat. This is effectively the damping
constant of the thermostat.

SetFrequency(attribute): This attribute is optional
and only takes effect if the SetPoint attribute is also
defined. The thermostat mean free time is adjusted every
SetFrequency events to attempt to match the SetPoint fraction of
events.

Dimensions(attribute): A number indicating how many
dimensions of the particles are to be thermostatted. The default
is all (=3). If set to 2, the $z$ dimension is not affected by the
thermostat, and if set to 1, neither the $y$ or $z$-dimensions are
affected.

IDRange(tag): This IDRange tag specifies the
particles to which the thermostat is applied. See
the section on IDRanges for more
information on the format of this tag.

Type="Umbrella"

Description

The "Umbrella" System implements an umbrella potential, allowing
a Potential to be specified between the
centres of mass of two collections of particles.

IDRange(tag$\times$2): There
are two IDRange tags which specify the two
ranges of particles which interact using the umbrella
potential. See the section on IDRanges for
more information on the format of these tags.

Potential(tag):
The Potential tag specifies the stepped
potential used for the umbrella potential. Please see the section
on the Potential tag for more
information.

Dynamics

The Dynamics tag specifies the equations of motion of the
system. The standard variant is the "Newtonian" type, but there are
other types available which allow the addition of an external force
such as gravity.

Type="Newtonian"

Description

The "Newtonian" Dynamics type is the standard
Dynamics implementation in DynamO. All particles are moving under
standard Newtonian dynamics, without the influence of external
forces.

Example usage

<Dynamics Type="Newtonian"/>

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "Newtonian" to select this Dynamics type.

Type="NewtonianGravity"

Description

The "NewtonianGravity" Dynamics type allows an
external acceleration to be included in the dynamics.

Example usage

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "NewtonianGravity" to select this Dynamics type.

ElasticV(attribute): An optional tag. If this tag
is present, this tag specifies the velocity below which particle
interactions will be turned elastic (used to prevent inelastic
collapse).

tc(attribute): An optional tag. If this tag is
present, this tag specifies the minimum re-collision rate which
turns an interaction elastic (used to prevent inelastic
collapse). For more information
see this
paper
(also available on
arxiv).

If we are in the canonical ensemble, the probability of being in a
certain configurational energy, $E$, is
\[P_c(E)=\frac{1}{Z_{c}} n(E) \exp\left[-E/k_BT\right] \]
But for efficient sampling of all energies we would prefer it if the
probability of each energy is constant and equal.
\[ P_{mc} (E) = \frac{1}{Z_{mc}} n(E) \exp\left[-E/k_BT-W(E)\right] = \textrm{constant} \]
This is the ideal multi-canonical simulation, as we sample all
energies equally. However, to perform the ideal multi-canonical
simulation we need to know the $W(E)$ function.
\[ W(E) = \ln n(E) - E / k_B T = \ln P_c(E) \]
This requires knowing the density of states ($n(E)$), but if these
quantities are known, the problem of sampling the system is already
solved. So what we need is an iterative way to determine the $W(E)$
function. The simplest technique is to run a simulation with
$W^{(0)}(E)=0$, and then iterate towards the optimal weighting with
this expression:
\[ W^{(i+1)}(E) = W^{(i)}(E) + \ln P^{(i)}_{mc}(E) \]
There are more advanced techniques available in the literature which
have been implemented and these are available as scripts which are
run outside of DynamO. These are discussed elsewhere and only the
DynamO interface is described here.

It should be noted that the $W$ function is effectively an
additional potential in the Hamiltonian of the system:
\[ P_{mc} (E) = \frac{1}{Z_{mc}} n(E) \exp\left[-(E+E_{MC}(E))/k_B\,T\right] \]
where $E_{MC}(E) = k_B\,T\,W(E)$ is the multicanonical potential.
If we want to specify a multicanonical potential (or $W$ function)
in DynamO, we must do so using a stepped function. Each step has the
same width and is centered around an energy value. The width of all
steps is set using the EnergyStep attribute of
the PotentialDeformation tag. The energy and $W$ value of
each step is specified in a list of W tags inside
the PotentialDeformation tag. If there is no step specified
for an energy, its $W$ value is automatically assumed to be zero.

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "NewtonianMC" to select this Dynamics type.

PotentialDeformation(tag): This tag encloses the
stepped deformation potential used in the multicanonical
simulation.

EnergyStep(attribute): The width of each
deformation potential step.

W(tag): This tag contains the location of the
deformation potential step and its $W$ value.

Energy(attribute): The centre energy of the
deformation energy step.

Value(attribute): The $W$ value of the
deformation energy step.

Property

Property tags are a mechanism which allows you to specify large
amounts of information which may or may not vary on a per-particle
basis. For example, if every Particle in the system is
a HardSphere type Interaction with the
same diameter of 1.5, you might use the following Interaction:

The values of the Diameter and Elasticity are called
a numeric properties where the value of the property
specifier is the value of the property. But what if you want a
polydisperse system, where each particle may have a unique mass and
diameter? In this case we would use named Properties:

Here we've used the name "D" to refer to a new named
Property. Whenever DynamO encounters a property specifier, such as
the Diameter attribute above, and fails to convert it directly into
a floating-point number due to the presence of letters in its name,
it assumes that the property is a named property. This named
property can also be reused in other property specifiers at the same
time, such as in a Wall type Local:

And now both the Wall Local and the HardSphere Interaction will use
the same diameter for each particle. Each named Property must be
defined in the Properties tag in the configuration file. For
example, if we wanted to define the mass and diameter of each
particle individually, we would define two "PerParticle" Properties
like so:

You should note that the units of the Property must correspond to
the units of the property specifier. If you check
the HardSphere Interaction
documentation, you can confirm that the Diameter attribute has units
of Length (The available units
include Dimensionless, Length, Area, Volume, Time, Mass,
and Energy).

Once the per-particle Property has been defined and referred to in
other parts of the configuration file, you must specify the value of
the property for each particle. This is done by adding an attribute
to the Pt (particle) tags with the same name as
the property. For example:

<Pt ID="0" M="1.11" D="0.323451">
<P .../>
<V .../>
</Pt>

At the moment, there is only the PerParticle type of named property,
and every single particle must have the corresponding property
attribute (in the example above, each Pt tag must have
a D and M attribute).

Pt (Particle)

Description

A Pt or Particle tag represents the
unique data of a single particle. Each particle must have at least a
position and velocity tag, but it may also include additional
attributes and tags corresponding
to Properties.

Example usage

Full Tag, Subtag, and Attribute List

ID(attribute): DynamO loads and assigns ID's to
particles in the order in which they appear in the configuration
file. This tag is therefore not read by DynamO, but is provided
in generated configuration files to make it easy to identify
particles.

P(tag): This tag contains the position of the
particle. In systems with periodic boundary conditions, the
dynamod/dynarun commands will output the position of the
particle image which is in the primary image (the "wrapped"
particle position). This behaviour may be disabled using
the --unwrapped option of the dynamod and dynarun
commands (the particle positions correspond to the initial
particle image's final location).

x(attribute): The particles $x$-coordinate.

y(attribute): The particles $y$-coordinate.

z(attribute): The particles $z$-coordinate.

V(tag): This tag contains the velocity of the
particle.

x(attribute): The $x$-component of the particle velocity.

y(attribute): The $y$-component of the particle velocity.

z(attribute): The $z$-component of the particle velocity.

Potential

The Potential tag represents a collection of discontinuities and
energies which make up a stepped potential. The location of these
steps may be manually entered using
the "Stepped" type or
automatically generated, such as in
the Lennard-Jones type.

Type="Stepped"

Description

This Potential type allows a stepped potential to be manual entered
and is the most general stepped potential available. There are two
classes of stepped potential, Left or Right, depending on which
"side" of the discontinuity is specified by the discontinuity's
energy. An illustration is given below:

A
comparison of the two types of stepped potential. The discontinuity
locations are marked with a cross, and the adjacent line marks the
location of the corresponding step. The internal numbering DynamO uses
for each step is also outlined.

In both potentials, there is an implicit step (the zero step) which
has an energy of zero. Left stepped potentials are best used for
forces which decay with $r$, whereas Right stepped potentials are
often used for forces which increase with $r$. This is for
efficiency due to two factors: The step number for a pair of
particles is not stored in memory if it has a value of zero and, for
automatically generated potentials, steps are computed from step 0
upwards (as required). Therefore, a stepped Lennard-Jones potential
is most efficiently implemented as a Left potential as most possible
particle pairs are not interacting and will be within the zero
step. A computed bond (constraining) spring potential is most
efficiently implemented using a Right potential.

Example usage

An implementation of the sixth hand stepped approximation of the
Lennard-Jones potential reported
by Chapela
et al. (1989):

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "Stepped" to select this Potential type.

Direction(attribute): This sets the direction of
the stepping.
For example, for potentials which have zero
interaction energy at long distances, the "Left" direction is the
most convenient. The Lennard-Jones potential is an example of such
a potential. In this case, each Step tag specifies a
location of a discontinuity and the energy on its left hand side
($r^-$). The outermost step is assumed to have an energy of zero.
A spring potential is an example where the "Right" direction
is most convenient as it has zero interaction energy at $r=0$. In
this case, each Step tag specifies a location of a
discontinuity and the energy on its right hand side ($r^+$). The
innermost step has a energy of zero

Step(tag): This tag represents a single
discontinuity/step of the stepped potential. On load these steps
are sorted by their R value and allocated numbers as outlined above.

R(attribute): The radial separation of the
discontinuity.

E(attribute): The energy of the potential on
either the left or right hand side of the discontinuity
(depending on the Direction).

The continuous
Lennard-Jones potential and a stepped approximation using the
optimal/default settings and $10.8$ attractive steps. Both potentials
have a cut-off radius of 3. The figure is in reduced units
corresponding to $\varepsilon=1$ and $\sigma=1$

Example usage

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "LennardJones" to select this Potential type.

Sigma(attribute): Sets the distance $\sigma$ at
which the interaction energy is zero.

Epsilon(attribute): Sets the energy $\varepsilon$
of the attractive well.

Cutoff(attribute): The cutoff radius of the
potential.

AttractiveSteps(attribute): The order of
approximation of the potential. Setting AttractiveSteps="10.8" is
sufficient for a close reproduction of the thermodynamic
properties provided the default UMode and RMode values are used.

RMode(attribute, optional): Select the method used
to calculate the position of each step. This may be "DeltaR",
"DeltaU", or "DeltaV". If this attribute is not set, the
default/recommended value is used (currently "DeltaU").

UMode(attribute, optional): Select the method used
to calculate the energy of each step. This may be "Left", "Right",
"Midpoint", "MidVolume", "Virial", or "Volume". If this attribute
is not set, the default/recommended value is used (currently
"Volume"). If "Virial" is selected, the Temperature
attribute must also be set.

Temperature(attribute, optional): If
the UMode is set to "Virial" you must provide the
temperature used for the approximation in this attribute.

Example usage

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "List" to select this range type.

ID(tag): A tag containing an ID/entry in the
list.

val(attribute): The ID of the entry.

Type="Union"

Description

An IDRange which combines several IDRanges into
one.

Example usage

<IDRange Type="Union">
<IDRange .../>
<IDRange .../>
...
</IDRange>

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "Union" to select this range type.

IDRange(tag): A list of IDrange subtags which
describe the IDRanges to be combined.

IDPairRange

IDPairRanges are used to specify the pairs of particles to
which an Interaction applies. Each IDPairRange represent a
collection or set of ID pairs.

Type="All"

Description

An ID Range which maps to all pairs of particles
in the simulation.

Example usage

<IDPairRange Type="All"/>

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the value "All"
to select this range type.

Type="None"

Description

An ID Range which doesn't map to any pair of
particles.

Example usage

<IDPairRange Type="None"/>

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "None" to select this range type.

Type="Pair"

Description

This creates a IDPairRange from two
IDRanges. Each particle ID in the first range is paired with all of
the particle IDs in the second range. Pairs of particle IDs which
only match one range are not included in the pair range.

Example usage

This example pairs particle IDs 0,1,2 with IDs 3,4,5. Pairs only
within one range, such as (0,1) or (3,4), are not included. All
IDRangePairs are symmetric, so both (1,4) and (4,1) are included in
this example range.

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "Pair" to select this range type.

IDRange($2\times$tag): There must be two IDRange tags
present and each specifies one of the IDRanges used to make the
IDPairRange. The order in which the IDRanges are specifed is
unimportant. See the section on the available
IDRange types for more information.

Type="Single"

Description

This creates a IDPairRange from one
IDRange. Every particle ID in the IDRange is paired with every other
particle in the IDRange.

Full Tag, Subtag, and Attribute List

Type="List"

Description

This is the most versatile IDPairRange available
as it allows you to specify the particle pairings individually.

Example usage

This example matches the particle pairings (0,1), (1,2), and
(2,3). As IDPairRanges are symmetric, the pairings (1,0), (2,1), and
(3,2) are also included. This example might be used to bond
particles together into a chain.

Example usage

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "Union" to select this range type.

IDPairRange(tag): Each IDPairRange sub tag
represents one of the IDPairRanges to be combined.

Type="Chains"

Description

This IDPairRange is provided as a convenient way
to bond sequential particle IDs into linear chains.

Example usage

If the example below was used with
a square-bond Interaction, it would
bond a set of particles together into chains of 4.
This example matches the particle pairings (0,1), (1,2), (2,3) and
(4,5), (5,6), (6,7). As IDPairRanges are symmetric, the pairings
(1,0), (2,1), etc. are also included.

<IDPairRange Type="Chains" Start="0" End="7" Interval="4"/>

Full Tag, Subtag, and Attribute List

Type(attribute): Must have the
value "Chains" to select this range type.

Start(attribute): The first ID of the sequential
particle IDs.

End(attribute): The last ID of the sequential
particle IDs.

Interval(attribute): How long the chains
are. Please note that End - Start must be a whole multiple of
Interval.