API reference manual

General notes

The following sections describe the various components of the API one by one. There are some common aspects among many of those components, which are explained in the present section.

Unless otherwise stated, the physical units for time, length, mass, energy and temperature are picosecond (ps), angstrom (Å), dalton (Da), electronvolt (eV) and kelvin (K) respectively.

Each atom in FMD has a group-ID, which determines to which group it belongs. Groups make it possible to perform certain actions on specific groups of atoms without other atoms being affected. For example, the functions fmd_matt_translate() and fmd_matt_addVelocity() can be used to translate the atoms of a single group in position space and velocity space, respectively. These functions have a GroupID parameter, specifying on what group the functions act. This parameter can take the special value FMD_GROUP_ALL. In that case, the functions act on all atoms, regardless of the groups to which they belong.

At each moment, either all or one of atom groups is dynamically active, which means time integrators update the positions and velocities of the atoms belonging to it, and physical quantities such as kinetic and potential energy are calculated for it. A function like fmd_matt_getKineticEnergy() returns the physical quantity of the active group only. Initially, all groups are active. Time integration functions fmd_dync_equilibrate() and fmd_dync_integrate() can change the active group. Passing FMD_GROUP_ALL to the time integrator functions makes all groups active.

When the size of the simulation box is set to be \(l_x\), \(l_y\) and \(l_z\) in the three directions by calling fmd_box_setSize(), the three coordinates of any point inside the box lie in the intervals \(\left[0, l_x\right)\), \(\left[0, l_y\right)\) and \(\left[0, l_z\right)\), respectively. Please keep this in mind when translating a group of atoms by fmd_matt_translate() or adding matter to the box by fmd_matt_makeCuboidSC(), fmd_matt_makeCuboidSC_mix(), fmd_matt_makeCuboidBCC(), fmd_matt_makeCuboidBCC_mix(), fmd_matt_makeCuboidFCC() and fmd_matt_makeCuboidFCC_mix().

FMD utilizes MPI for parallel computation. Users of the library do not need to call any MPI subroutine directly. The parallelization strategy used in FMD is called spatial decomposition: the simulation box is partitioned into a number of subdomains (set by fmd_box_setSubdomains()) and each subdomain together with everything inside it is assigned to a distinct MPI process. Therefore, the number of processes is not allowed to be less than the number of subdomains. Usually, the number of processes is determined when launching an MPI program. For example, with the command mpirun -n 4 ./program.x in a terminal emulator, four processes are created from the executable file program.x.

Many functions deal with special kinds of grids called turies, and fields defined on them. Temperature and density are examples of fields. Turies and fields can be used either to obtain physical quantities like temperature as functions of position or to combine molecular dynamics with finite difference solvers of partial differential equations representing continuum models. All cells of a turi are of the same size, which is determined by the dimensions of the turi and simulation box. A turi-cell may completely lie within a single subdomain or span two or more subdomains. A turi-cell can even be as large as the simulation box and span all of the subdomains (that is when the dimensions of the turi is \(1\times 1\times 1\)). In a simulation, each turi together with its fields is treated as independent from other turies, but different fields of the same turi may be dependent on each other. For instance, temperature field is dependent on center-of-mass velocity field. The dependencies are managed automatically by the library. For example, when a temperature field is added to a turi by a call to fmd_field_add(), the library also adds a center-of-mass velocity field, if not already added.

The version format is X.Y.Z.c, where X, Y, Z are non-negative integers and c is a character. This character is either ‘r’ or ‘d’, where ‘r’ stands for release and ‘d’ stands for development. Versions of the latter kind are for development and testing by the developers of the library, so here we limit our discussion to release versions. A program written for version X1.Y1.Z1 of the library must also work properly with version X2.Y2.Z2 if X1 = X2 and X1 ≠ 0 and Y1 ≯ Y2. In other cases, it may or may not work. The values of X, Y, Z, and c can be get by fmd_version_getMajor(), fmd_version_getMinor(), fmd_version_getRevision(), and fmd_version_getType(), respectively. The function fmd_version_getString() returns X.Y.Z as a string.

Types and values

fmd_array3_t

typedef void ***fmd_array3_t: The data type for a three-dimensional array.

fmd_array3s_t

typedef struct _fmd_array3s fmd_array3s_t: A variable of this data type is only used for freeing a three-dimensional array with fmd_array3s_free().

fmd_EventHandler_t

typedef void (*fmd_EventHandler_t)(fmd_t *md, fmd_event_t event, void *usp, fmd_params_t *params)

This type specifies the prototype of any function which can be accepted as an event-handler. In an event-handler, the value of event indicates what event has occurred. It also determines the number and types of the extra parameters sent to the event-handler. usp is a user-given pointer which is passed to the event-handler whenever any event occurs. If the event-handler needs to have access to data from outside of the scope of the event-handler, usp provides a way in addition to global variables. params points to an object of struct type fmd_params_t containing the extra parameters. fmd_params_t is an incomplete type, so the library user must typecast params properly before accessing its members. The following table shows the different events that may occur and the typecast that must be done to access the extra parameters for each event.

event	value of `event`	typecast
a user-defined timer ticks	`FMD_EVENT_TIMER_TICK`	(fmd_event_params_timer_tick_t*)params
a turi-field is updated	`FMD_EVENT_FIELD_UPDATE`	(fmd_event_params_field_update_t*)params

Functions

fmd_array3s_free()

void fmd_array3s_free(fmd_array3s_t *array)

Parameters:

array – the array to be freed

Frees a three-dimensional array.

fmd_box_setPBC()

void fmd_box_setPBC(fmd_t *md, bool PBCx, bool PBCy, bool PBCz)

Parameters:

md – an fmd_t
PBCx – the desired state of PBC in x direction
PBCy – the desired state of PBC in y direction
PBCz – the desired state of PBC in z direction

Sets periodic boundary conditions (PBC) in different directions. A value of true for any of the PBC state parameters causes PBC to be applied in the associated direction. In contrast, a value of false for any direction means that PBC is NOT to be applied in that direction. By default, PBC is not applied in any direction.

fmd_box_setSize()

void fmd_box_setSize(fmd_t *md, fmd_real_t sx, fmd_real_t sy, fmd_real_t sz)

Parameters:

md – an fmd_t
sx – the size in x direction
sy – the size in y direction
sz – the size in z direction

Sets the size of the simulation box.

fmd_box_setSubdomains()

bool fmd_box_setSubdomains(fmd_t *md, int dimx, int dimy, int dimz)

Parameters:

md – an fmd_t
dimx – dimension of the subdomain grid in x direction
dimy – dimension of the subdomain grid in y direction
dimz – dimension of the subdomain grid in z direction

Returns:

true, if the current process is associated with a subdomain; false, otherwise.

Defines how the simulation box is partitioned into subdomains. The dimensions of the subdomain grid are dimx \(\times\) dimy \(\times\) dimz. If the returned value is neglected, it can later be get by fmd_proc_hasSubdomain().

fmd_create()

fmd_t *fmd_create()

Returns:: a pointer to the created fmd_t object

Creates an fmd_t object and initializes it with default values for various parameters.

fmd_dync_equilibrate()

void fmd_dync_equilibrate(fmd_t *md, int GroupID, fmd_real_t duration, fmd_real_t timestep, fmd_real_t tau, fmd_real_t temperature)

Parameters:

md – an fmd_t
GroupID – the group to become active
duration – the duration of time integration
timestep – the timestep used in time integration (\(\delta t\))
tau – the parameter \(\tau\) of Berendsen thermostat
temperature – the desired temperature (\(T_0\))

Uses Berendsen thermostat and velocity Verlet algorithm to equilibrate an atom group to the desired temperature. At each time step, the atom velocities are scaled from \(\mathbf{v}\) to \(\lambda\mathbf{v}\), where \(\lambda\) is calculated by

\[\lambda = \left[1+\frac{\delta t}{\tau}\left(\frac{T_0}{T}-1\right)\right]^{1/2}.\]

Here, \(T\) is the instantaneous temperature. Other quantities in the equation are defined above. If GroupID is equal to FMD_GROUP_ALL, all groups become active. Otherwise, that particular group becomes active. The concept of active group is explained in General notes. This function first sets the simulation time to zero, but finally, when the time integration is done, restores the initial time. The function may not work properly in certain situations (for example, when the active group has non-zero center-of-mass velocity).

fmd_dync_getTime()

fmd_real_t fmd_dync_getTime(fmd_t *md)

Parameters:

md – an fmd_t

Returns:

the current simulation time

fmd_dync_getTimestep()

fmd_real_t fmd_dync_getTimestep(fmd_t *md)

Parameters:

md – an fmd_t

Returns:

the timestep used in MD time integration

The timestep is set by the last fmd_dync_integrate() or fmd_dync_equilibrate() call.

fmd_dync_integrate()

void fmd_dync_integrate(fmd_t *md, int GroupID, fmd_real_t duration, fmd_real_t timestep)

Parameters:

md – an fmd_t
GroupID – the group to become active
duration – the duration of time integration
timestep – the timestep used in time integration

Integrates the Newton’s equations of motion for all atoms of group GroupID for a duration equal to duration with a timestep of timestep. If a TTM turi is defined over md, semi-implicit Euler integration method is used (See fmd_turi_add() for more information). Otherwise, velocity Verlet algorithm is used for time integration. If GroupID is equal to FMD_GROUP_ALL, all groups become active. Otherwise, that particular group becomes active. The concept of active group is explained in General notes.

fmd_field_add()

fmd_handle_t fmd_field_add(fmd_t *md, fmd_handle_t turi, fmd_field_t cat, fmd_real_t interval)

Parameters:

md – an fmd_t
turi – the handle to the turi to which the field is to be added
cat – the category of the field
interval – the simulation-time interval between two subsequent field updates

Returns:

the handle to the field

Adds a field of category cat and its dependencies to the given turi, if not already added. It also makes sure that the field and its dependencies are updated with the given time interval between any two subsequent updates. A particular field can have multiple update time-intervals. The following table shows the different field categories a user can manually add to a turi and their immediate dependencies.

field category	dependencies
`FMD_FIELD_MASS`
`FMD_FIELD_VCM`	`FMD_FIELD_MASS`
`FMD_FIELD_TEMPERATURE`	`FMD_FIELD_VCM`, `FMD_FIELD_NUMBER`
`FMD_FIELD_NUMBER`
`FMD_FIELD_NUMBER_DENSITY`	`FMD_FIELD_NUMBER`

Turies and fields are introduced in General notes. See also fmd_field_t, fmd_field_find() and fmd_turi_add().

fmd_field_find()

fmd_handle_t fmd_field_find(fmd_t *md, fmd_handle_t turi, fmd_field_t cat)

Parameters:

md – an fmd_t
turi – the handle to the turi in which the search takes place
cat – the category of the field to search for

Returns:

the handle to the field, if found; a negative number, otherwise.

Searches for a field of category cat in the turi specified by turi.

fmd_field_getArray()

fmd_array3s_t *fmd_field_getArray(fmd_t *md, fmd_handle_t turi, fmd_handle_t field, fmd_array3_t *array, fmd_utriple_t dims)

Parameters:

md – an fmd_t
turi – the handle to the turi where the field exists
field – the handle to the field
array – the output array
dims – the dimensions of the output array

Returns:

a pointer which should be used for freeing the array

Note

This function must be called by all processes, but its outputs (i.e. the parameters array and dims) are valid only on the root process. To identify the root process, use fmd_proc_isRoot().

Makes a three-dimensional array from the field specified by turi and field. This function can be called in a event-handler when a field-update event has occurred. The parameters array and dims are used to output the array and its dimensions. The dimensions of the array are written in dims[0], dims[1] and dims[2]. As the following table shows, the data type of each element of the output array depends on the field category.

field category	element type
`FMD_FIELD_MASS`	`fmd_real_t`
`FMD_FIELD_VCM`	`fmd_rtriple_t`
`FMD_FIELD_TEMPERATURE`	`fmd_real_t`
`FMD_FIELD_NUMBER`	`unsigned int`
`FMD_FIELD_NUMBER_DENSITY`	`fmd_real_t`
`FMD_FIELD_TTM_TE`	`fmd_real_t`
`FMD_FIELD_TTM_XI`	`fmd_real_t`

Once the user has nothing more to do with the output array, it should be freed by passing the returned value to fmd_array3s_free().

fmd_field_save_as_hdf5()

void fmd_field_save_as_hdf5(fmd_t *md, fmd_handle_t turi, fmd_handle_t field, fmd_string_t filename)

Parameters:

md – an fmd_t
turi – the handle to the turi where the field exists
field – the handle to the field to be saved to disk
filename – the name of the file on disk

Saves the field specified by turi and field as an HDF5 file with the given name on disk. The file will include VizSchema metadata describing the data. It can be opened with visualization tools such as VisIt and ParaView. This function can be called in a event-handler when a field-update event has occurred. The path to the directory where the file is saved can be changed with fmd_io_setSaveDirectory().

fmd_free()

void fmd_free(fmd_t *md)

Parameters:

md – an fmd_t

Frees md and all associated resources.

fmd_io_loadState()

void fmd_io_loadState(fmd_t *md, fmd_string_t path, bool UseTime)

Parameters:

md – an fmd_t
path – the path to the state file on disk
UseTime – specifies whether to change the simulation time to the time inside the file

Loads a state file. If UseTime is equal to true, the simulation time is changed to the time value read from the file, which is the simulation time when the file was saved. If the dimensions of the simulation box are not already set (e.g. with a previous fmd_box_setSize() call), they are set with values read from the state file. Similarly, if the states of periodic boundary conditions (PBC) are not already set (e.g. with a previous fmd_box_setPBC()), they are set with values read from the file. All atoms inside the state file are added to the simulation box. Any atoms already existing in the simulation box are not affected. See also fmd_io_saveState(). Groups are explained in General notes.

fmd_io_printf()

void fmd_io_printf(fmd_t *md, const fmd_string_t restrict format, ...)

Parameters:

md – an fmd_t
format – the format string passed to printf()
... – the other parameters passed to printf()

Calls printf() of the C standard library on the root MPI process only. See also fmd_proc_isRoot().

fmd_io_saveState()

void fmd_io_saveState(fmd_t *md, fmd_string_t filename)

Parameters:

md – an fmd_t
filename – the name of the state file

Saves the state of a simulation to a file on disk. The saved data include the simulation time when the state was saved, the number of atoms, the dimensions of the simulation box, the state of periodic boundary conditions in the three directions, and the name, group-ID, position and velocity of each atom. The path to the directory where the file is saved can be changed with fmd_io_setSaveDirectory(). A state file can later be loaded with fmd_io_loadState() in order to, for example, continue a simulation. Groups are explained in General notes.

fmd_io_setSaveConfigMode()

void fmd_io_setSaveConfigMode(fmd_t *md, fmd_SaveConfigMode_t mode)

Parameters:

md – an fmd_t
mode – the new mode of configuration saving

Changes the mode of configuration saving. See fmd_SaveConfigMode_t for a description of the available modes.

fmd_io_setSaveDirectory()

void fmd_io_setSaveDirectory(fmd_t *md, fmd_string_t directory)

Parameters:

md – an fmd_t
directory – the path of the directory

Sets the path of the directory in which FMD saves all output files. The string directory must either be empty or end with the path separator character of the operating system (e.g. slash (“/”) in Unix-like operating systems). If the directory does not exist, it is NOT created by FMD.

fmd_matt_addVelocity()

void fmd_matt_addVelocity(fmd_t *md, int GroupID, fmd_real_t vx, fmd_real_t vy, fmd_real_t vz)

Parameters:

md – an fmd_t
GroupID – specifies the group on which the function acts
vx – the velocity change in x direction
vy – the velocity change in y direction
vz – the velocity change in z direction

Adds the same amount to the velocities of all atoms in group GroupID. Groups are explained in General notes.

fmd_matt_changeGroupID()

void fmd_matt_changeGroupID(fmd_t *md, int old, int new)

Parameters:

md – an fmd_t
old – the old group-ID
new – the new group-ID

Changes the group-ID of atoms with group-ID old to new. The parameter old can take FMD_GROUP_ALL as a special value. In that case, the group-ID of any atom in the simulation box is changed. new must be a non-negative integer. Groups are explained in General notes.

fmd_matt_findLimits()

void fmd_matt_findLimits(fmd_t *md, int GroupID, fmd_rtriple_t LowerLimit, fmd_rtriple_t UpperLimit)

Parameters:

md – an fmd_t
GroupID – specifies the group on which the function acts
LowerLimit – the output for lower limits
UpperLimit – the output for upper limits

Writes in LowerLimit[i] the smallest i-th coordinate of all atoms from the specified group, and writes in UpperLimit[i] the largest i-th coordinate of all atoms from that group. Here i (\(=0,1,2\)) denotes any of the three directions. Groups are explained in General notes.

fmd_matt_getKineticEnergy()

fmd_real_t fmd_matt_getKineticEnergy(fmd_t *md)

Parameters:

md – an fmd_t

Returns:

the sum of the kinetic energies of all atoms of the active group

The concept of active group is explained in General notes.

fmd_matt_getMomentum()

void fmd_matt_getMomentum(fmd_t *md, fmd_rtriple_t out)

Parameters:

md – an fmd_t
out – the output of the function

Writes the three components of the momentum vector of the active group in out[0], out[1] and out[2]. The concept of active group is explained in General notes.

fmd_matt_getTemperature()

fmd_real_t fmd_matt_getTemperature(fmd_t *md)

Parameters:

md – an fmd_t

Returns:

the instantaneous temperature of the active group, assuming that it is in thermodynamic equilibrium and its center-of-mass velocity is zero

The concept of active group is explained in General notes.

fmd_matt_getTotalEnergy()

fmd_real_t fmd_matt_getTotalEnergy(fmd_t *md)

Parameters:

md – an fmd_t

Returns:

the sum of kinetic energies and potential energies of all atoms in the active group

The concept of active group is explained in General notes.

Warning

In the current version of the library, this function can be used in an event-handler when a timer has ticked. It can also be used in an event-handler when a turi-field update has occurred, but only if there is no TTM turi in the simulation. If called in other circumstances, whether inside or outside an event-handler, the returned value is unreliable. This can be regarded as a known bug.

fmd_matt_giveMaxwellDistribution()

void fmd_matt_giveMaxwellDistribution(fmd_t *md, int GroupID, fmd_real_t temp)

Parameters:

md – an fmd_t
GroupID – specifies the group on which the function acts
temp – the desired temperature

Gives the atoms of the group specified by GroupID velocities that have a Maxwell-Boltzmann distribution corresponding to the temperature temp. The atoms may need to be equilibrated with fmd_dync_equilibrate() to reach the desired temperature. Groups are explained in General notes.

fmd_matt_makeCuboidBCC()

void fmd_matt_makeCuboidBCC(fmd_t *md, fmd_real_t x, fmd_real_t y, fmd_real_t z, int dimx, int dimy, int dimz, fmd_real_t lp, unsigned atomkind, int GroupID, fmd_real_t temp)

Parameters:

md – an fmd_t
x – the starting position (x component)
y – the starting position (y component)
z – the starting position (z component)
dimx – the dimension of the lattice in x direction
dimy – the dimension of the lattice in y direction
dimz – the dimension of the lattice in z direction
lp – the lattice parameter
atomkind – the index of the atom-kind in the array of atom-kinds
GroupID – the group-ID of the created atoms
temp – the desired temperature

The same as fmd_matt_makeCuboidBCC_mix(), except that all created atoms are of the same atom-kind.

fmd_matt_makeCuboidBCC_mix()

void fmd_matt_makeCuboidBCC_mix(fmd_t *md, fmd_real_t x, fmd_real_t y, fmd_real_t z, int dimx, int dimy, int dimz, fmd_real_t lp, fmd_real_t *ratio, int GroupID, fmd_real_t temp)

Parameters:

md – an fmd_t
x – the starting position (x component)
y – the starting position (y component)
z – the starting position (z component)
dimx – the dimension of the lattice in x direction
dimy – the dimension of the lattice in y direction
dimz – the dimension of the lattice in z direction
lp – the lattice parameter
ratio – the ratio of the mixture
GroupID – the group-ID of the created atoms
temp – the desired temperature

Creates a structure of atoms with cuboid outline by adding a single atom of random atom-kind to any point of a finite body-centered cubic (BCC) lattice. A conventional cell indexed by \(i\), \(j\) and \(k\), where \(i=0,\dots,\mathrm{dimx}-1\) and \(j=0,\dots,\mathrm{dimy}-1\) and \(k=0,\dots,\mathrm{dimz}-1\), will have two atoms placed at

\[x_1=\mathrm{x}+\left(i+\frac{1}{4}\right)\times\mathrm{lp},\quad y_1=\mathrm{y}+\left(j+\frac{1}{4}\right)\times\mathrm{lp},\quad z_1=\mathrm{z}+\left(k+\frac{1}{4}\right)\times\mathrm{lp},\]

and

\[x_2=\mathrm{x}+\left(i+\frac{1}{2}+\frac{1}{4}\right)\times\mathrm{lp},\quad y_2=\mathrm{y}+\left(j+\frac{1}{2}+\frac{1}{4}\right)\times\mathrm{lp},\quad z_2=\mathrm{z}+\left(k+\frac{1}{2}+\frac{1}{4}\right)\times\mathrm{lp}.\]

A total of 2 \(\times\) dimx \(\times\) dimy \(\times\) dimz atoms are added to the simulation box. The probability that any single atom in the created structure is of p-th atom-kind is equal to

\[\frac{\text{ratio[p]}}{{\displaystyle\sum_{\text{q}=0}^{N-1} \text{ratio[q]}}},\]

where \(N\) is the number of atom-kinds set by fmd_matt_setAtomKinds(). GroupID must be a non-negative integer value. The atoms are given velocities that have a Maxwell-Boltzmann distribution corresponding to the temperature temp. The created structure must be equilibrated with fmd_dync_equilibrate() to reach the desired temperature. Groups are explained in General notes.

fmd_matt_makeCuboidFCC()

void fmd_matt_makeCuboidFCC(fmd_t *md, fmd_real_t x, fmd_real_t y, fmd_real_t z, int dimx, int dimy, int dimz, fmd_real_t lp, unsigned atomkind, int GroupID, fmd_real_t temp)

Parameters:

md – an fmd_t
x – the starting position (x component)
y – the starting position (y component)
z – the starting position (z component)
dimx – the dimension of the lattice in x direction
dimy – the dimension of the lattice in y direction
dimz – the dimension of the lattice in z direction
lp – the lattice parameter
atomkind – the index of the atom-kind in the array of atom-kinds
GroupID – the group-ID of the created atoms
temp – the desired temperature

The same as fmd_matt_makeCuboidFCC_mix(), except that all created atoms are of the same atom-kind.

fmd_matt_makeCuboidFCC_mix()

void fmd_matt_makeCuboidFCC_mix(fmd_t *md, fmd_real_t x, fmd_real_t y, fmd_real_t z, int dimx, int dimy, int dimz, fmd_real_t lp, fmd_real_t *ratio, int GroupID, fmd_real_t temp)

Parameters:

md – an fmd_t
x – the starting position (x component)
y – the starting position (y component)
z – the starting position (z component)
dimx – the dimension of the lattice in x direction
dimy – the dimension of the lattice in y direction
dimz – the dimension of the lattice in z direction
lp – the lattice parameter
ratio – the ratio of the mixture
GroupID – the group-ID of the created atoms
temp – the desired temperature

Creates a structure of atoms with cuboid outline by adding a single atom of random atom-kind to any point of a finite face-centered cubic (FCC) lattice. A conventional cell indexed by \(i\), \(j\) and \(k\), where \(i=0,\dots,\mathrm{dimx}-1\) and \(j=0,\dots,\mathrm{dimy}-1\) and \(k=0,\dots,\mathrm{dimz}-1\), will have four atoms placed at

\[x_1=\mathrm{x}+\left(i+\frac{1}{4}\right)\times\mathrm{lp},\quad y_1=\mathrm{y}+\left(j+\frac{1}{4}\right)\times\mathrm{lp},\quad z_1=\mathrm{z}+\left(k+\frac{1}{4}\right)\times\mathrm{lp},\]

and

\[x_2=\mathrm{x}+\left(i+\frac{1}{4}\right)\times\mathrm{lp},\quad y_2=\mathrm{y}+\left(j+\frac{1}{2}+\frac{1}{4}\right)\times\mathrm{lp},\quad z_2=\mathrm{z}+\left(k+\frac{1}{2}+\frac{1}{4}\right)\times\mathrm{lp},\]

and

\[x_3=\mathrm{x}+\left(i+\frac{1}{2}+\frac{1}{4}\right)\times\mathrm{lp},\quad y_3=\mathrm{y}+\left(j+\frac{1}{4}\right)\times\mathrm{lp},\quad z_3=\mathrm{z}+\left(k+\frac{1}{2}+\frac{1}{4}\right)\times\mathrm{lp},\]

and

\[x_4=\mathrm{x}+\left(i+\frac{1}{2}+\frac{1}{4}\right)\times\mathrm{lp},\quad y_4=\mathrm{y}+\left(j+\frac{1}{2}+\frac{1}{4}\right)\times\mathrm{lp},\quad z_4=\mathrm{z}+\left(k+\frac{1}{4}\right)\times\mathrm{lp}.\]

A total of 4 \(\times\) dimx \(\times\) dimy \(\times\) dimz atoms are added to the simulation box. The probability that any single atom in the created structure is of p-th atom-kind is equal to

\[\frac{\text{ratio[p]}}{{\displaystyle\sum_{\text{q}=0}^{N-1} \text{ratio[q]}}},\]

where \(N\) is the number of atom-kinds set by fmd_matt_setAtomKinds(). GroupID must be a non-negative integer value. The atoms are given velocities that have a Maxwell-Boltzmann distribution corresponding to the temperature temp. The created structure must be equilibrated with fmd_dync_equilibrate() to reach the desired temperature. Groups are explained in General notes.

fmd_matt_makeCuboidSC()

void fmd_matt_makeCuboidSC(fmd_t *md, fmd_real_t x, fmd_real_t y, fmd_real_t z, int dimx, int dimy, int dimz, fmd_real_t lp, unsigned atomkind, int GroupID, fmd_real_t temp)

Parameters:

md – an fmd_t
x – the starting position (x component)
y – the starting position (y component)
z – the starting position (z component)
dimx – the dimension of the lattice in x direction
dimy – the dimension of the lattice in y direction
dimz – the dimension of the lattice in z direction
lp – the lattice parameter
atomkind – the index of the atom-kind in the array of atom-kinds
GroupID – the group-ID of the created atoms
temp – the desired temperature

The same as fmd_matt_makeCuboidSC_mix(), except that all created atoms are of the same atom-kind.

fmd_matt_makeCuboidSC_mix()

void fmd_matt_makeCuboidSC_mix(fmd_t *md, fmd_real_t x, fmd_real_t y, fmd_real_t z, int dimx, int dimy, int dimz, fmd_real_t lp, fmd_real_t *ratio, int GroupID, fmd_real_t temp)

Parameters:

md – an fmd_t
x – the starting position (x component)
y – the starting position (y component)
z – the starting position (z component)
dimx – the dimension of the lattice in x direction
dimy – the dimension of the lattice in y direction
dimz – the dimension of the lattice in z direction
lp – the lattice parameter
ratio – the ratio of the mixture
GroupID – the group-ID of the created atoms
temp – the desired temperature

Creates a structure of atoms with cuboid outline by adding a single atom of random atom-kind to any point of a finite simple cubic (SC) lattice. A conventional cell indexed by \(i\), \(j\) and \(k\), where \(i=0,\dots,\mathrm{dimx}-1\) and \(j=0,\dots,\mathrm{dimy}-1\) and \(k=0,\dots,\mathrm{dimz}-1\), will have one atom placed at

\[x_1=\mathrm{x}+\left(i+\frac{1}{4}\right)\times\mathrm{lp},\quad y_1=\mathrm{y}+\left(j+\frac{1}{4}\right)\times\mathrm{lp},\quad z_1=\mathrm{z}+\left(k+\frac{1}{4}\right)\times\mathrm{lp}.\]

A total of dimx \(\times\) dimy \(\times\) dimz atoms are added to the simulation box. The probability that any single atom in the created structure is of p-th atom-kind is equal to

\[\frac{\text{ratio[p]}}{{\displaystyle\sum_{\text{q}=0}^{N-1} \text{ratio[q]}}},\]

where \(N\) is the number of atom-kinds set by fmd_matt_setAtomKinds(). GroupID must be a non-negative integer value. The atoms are given velocities that have a Maxwell-Boltzmann distribution corresponding to the temperature temp. The created structure must be equilibrated with fmd_dync_equilibrate() to reach the desired temperature. Groups are explained in General notes.

fmd_matt_saveConfiguration()

void fmd_matt_saveConfiguration(fmd_t *md)

Parameters:

md – an fmd_t

Saves the positions of all atoms to a configuration file on disk. File format and file naming depend on the mode of configuration saving, which can be changed with fmd_io_setSaveConfigMode(). The default mode is FMD_SCM_XYZ_ATOMSNUM. The path to the directory where the file is saved can be changed with fmd_io_setSaveDirectory().

fmd_matt_setAtomKinds()

void fmd_matt_setAtomKinds(fmd_t *md, unsigned number, const fmd_string_t names[], const fmd_real_t masses[])

Parameters:

md – an fmd_t
number – the number of atom-kinds
names – an array of strings, where each element is the name of an atom-kind
masses – the array of the masses of the atom-kinds

Sets the number of atom-kinds, their names and their masses. names[i] and masses[i] are respectively the name (e.g. “Ar”, “Cu”) and mass of the i-th atom-kind (\(\mathrm{i}=0,\dots,\mathrm{number}-1\)).

fmd_matt_translate()

void fmd_matt_translate(fmd_t *md, int GroupID, fmd_real_t dx, fmd_real_t dy, fmd_real_t dz)

Parameters:

md – an fmd_t
GroupID – specifies the group on which the function acts
dx – the x component of displacement vector
dy – the y component of displacement vector
dz – the z component of displacement vector

Translates all atoms in group GroupID by the given displacement vector. When periodic boundary conditions are not applied, if all or some of the atoms are translated to positions outside the boundaries of the simulation box, the departed atoms are removed from the simulation. Groups are explained in General notes.

fmd_pot_apply()

void fmd_pot_apply(fmd_t *md, unsigned atomkind1, unsigned atomkind2, fmd_pot_t *pot)

Parameters:

md – an fmd_t
atomkind1 – the index of an atom-kind in the array of atom-kinds
atomkind2 – the index of an atom-kind in the array of atom-kinds
pot – an fmd_pot_t, the interatomic potential to be applied

Applies pot for the computation of the interactions among atoms of atom-kinds specified with the parameters atomkind1 and atomkind2.

Important note concerning EAM potentials: A DYNAMO setfl file contain chemical symbols (e.g. Cu, Al) of elements for which it was created. When such a potential file is loaded by calling fmd_pot_eam_alloy_load(), those chemical symbols are loaded along with other data into memory. On the other hand, in FMD every atom-kind has a name, set by fmd_matt_setAtomKinds(). In case pot is an EAM potential, the call to fmd_pot_apply() is successful only if the names of the atom-kinds indexed by atomkind1 and atomkind2 are among the chemical symbols inside pot.

fmd_pot_eam_alloy_load()

fmd_pot_t *fmd_pot_eam_alloy_load(fmd_t *md, fmd_string_t path)

Parameters:

md – an fmd_t
path – the path to the file on disk

Returns:

a pointer to the loaded potential

Loads an EAM potential from a file with DYNAMO setfl format. One website that distributes such potential files for different materials is https://www.ctcms.nist.gov/potentials. Files with DYNAMO setfl format usually, if not always, have .eam.alloy extension on that website. Once a potential file is loaded into memory, it must be applied by using fmd_pot_apply().

fmd_pot_eam_getCutoffRadius()

fmd_real_t fmd_pot_eam_getCutoffRadius(fmd_t *md, fmd_pot_t *pot)

Parameters:

md – an fmd_t
pot – an fmd_pot_t, the loaded EAM potential

Returns:

the cut-off radius of the EAM potential

fmd_pot_eam_getLatticeParameter()

fmd_real_t fmd_pot_eam_getLatticeParameter(fmd_t *md, fmd_pot_t *pot, fmd_string_t element)

Parameters:

md – an fmd_t
pot – an fmd_pot_t, the loaded EAM potential
element – the chemical symbol of the element

Returns:

the lattice parameter for the specified element

If an element with chemical symbol specified with element exists in the EAM potential pot, this function returns its lattice parameter.

fmd_pot_lj_apply()

fmd_pot_t *fmd_pot_lj_apply(fmd_t *md, unsigned atomkind1, unsigned atomkind2, fmd_real_t sigma, fmd_real_t epsilon, fmd_real_t cutoff)

Parameters:

md – an fmd_t
atomkind1 – the index of an atom-kind in the array of atom-kinds
atomkind2 – the index of an atom-kind in the array of atom-kinds
sigma – the parameter \(\sigma\) of the Lennard-Jones potential
epsilon – the parameter \(\epsilon\) of the Lennard-Jones potential
cutoff – the cut-off radius of the potential function

Returns:

a pointer to the created Lennard-Jones potential

Creates a Lennard-Jones potential with the parameters sigma, epsilon and cutoff and applies it for the computation of the interactions among atoms of atom-kinds specified with the parameters atomkind1 and atomkind2. The mathematical relation for Lennard-Jones potential is

\[V_\text{LJ}(r) = 4 \epsilon \left[ \left(\frac{\sigma}{r}\right)^{12} - \left(\frac{\sigma}{r}\right)^{6} \right],\]

in which \(r\) is the distance between two interacting atoms.

fmd_pot_morse_apply()

fmd_pot_t *fmd_pot_morse_apply(fmd_t *md, unsigned atomkind1, unsigned atomkind2, fmd_real_t D0, fmd_real_t alpha, fmd_real_t r0, fmd_real_t cutoff)

Parameters:

md – an fmd_t
atomkind1 – the index of an atom-kind in the array of atom-kinds
atomkind2 – the index of an atom-kind in the array of atom-kinds
D0 – the parameter \(D_0\) of the Morse potential
alpha – the parameter \(\alpha\) of the Morse potential
r0 – the parameter \(r_0\) of the Morse potential
cutoff – the cut-off radius of the potential function

Returns:

a pointer to the created Morse potential

Creates a Morse potential with the parameters D0, alpha, r0 and cutoff and applies it for the computation of the interactions among atoms of atom-kinds specified with the parameters atomkind1 and atomkind2. The mathematical relation for Morse potential is

\[V_\text{Morse}(r) = D_0 \left[ \exp\left(-2\alpha (r-r_0)\right) - 2\exp\left(-\alpha(r-r_0)\right)\right],\]

in which \(r\) is the distance between two interacting atoms.

fmd_proc_getWallTime()

fmd_real_t fmd_proc_getWallTime(fmd_t *md)

Parameters:

md – an fmd_t

Returns:

the wall time in seconds elapsed since md was created and initialized by fmd_create()

fmd_proc_hasSubdomain()

bool fmd_proc_hasSubdomain(fmd_t *md)

Parameters:

md – an fmd_t

Returns:

true, if the current process is associated with a subdomain; false, otherwise.

This function is used to recognize if the current MPI process is associated with a subdomain of the simulation box. If called before fmd_box_setSubdomains(), the returned value is always false. When the number of subdomains set by fmd_box_setSubdomains() is smaller than the number of launched MPI processes, fmd_box_setSubdomains() returns false on any extra processes.

fmd_proc_isRoot()

bool fmd_proc_isRoot(fmd_t *md)

Parameters:

md – an fmd_t

Returns:

true, if called on the root process; false, otherwise.

This function is used to recognize if the current MPI process is the root process. Exactly one process is chosen to be the root by FMD.

fmd_proc_setNumThreads()

void fmd_proc_setNumThreads(fmd_t *md, int num)

Parameters:

md – an fmd_t
num – the desired number of threads

FMD can utilize OpenMP for parallel computation on systems with shared memory. This ability can be used instead of MPI-based parallel computation or in combination with it. By default, FMD requests one single thread any time it uses OpenMP for parallel computation. This means that, by default, OpenMP has no effect in practice. However, the requested number of OpenMP threads for the current process and the simulation instance specified by the parameter md can be changed using this function. There is no other way to alter the requested number of threads. For example, calling the OpenMP function omp_set_num_threads() in a program linked to FMD has no effect on the number of threads that FMD requests.

Note

If you set the requested number of threads to a value larger than 1, make sure that when launching your program with mpirun, it does not bind all threads to one single CPU core.

fmd_setEventHandler()

void fmd_setEventHandler(fmd_t *md, void *usp, fmd_EventHandler_t func)

Parameters:

md – an fmd_t
usp – an object passed to event-handler whenever any event occurs
func – the callback function to be used as event-handler

Sets an event handler for the simulation associated with md. See also fmd_EventHandler_t.

fmd_timer_makeSimple()

fmd_handle_t fmd_timer_makeSimple(fmd_t *md, fmd_real_t start, fmd_real_t interval, fmd_real_t stop)

Parameters:

md – an fmd_t
start – the simulation time when the timer starts to tick
interval – the time interval between two subsequent timer ticks
stop – the simulation time when the timer stops ticking

Returns:

the handle to the timer

Makes a simple timer and returns the handle to it. In a simple timer, the time interval between subsequent ticks is constant. To have a timer that never stops ticking, choose stop to be smaller than start.

fmd_ttm_setCellActivationFraction()

void fmd_ttm_setCellActivationFraction(fmd_t *md, fmd_handle_t turi, fmd_real_t value)

Parameters:

md – an fmd_t
turi – the handle to the TTM turi
value – the value of cell-activation fraction

Sets the cell-activation fraction for the specified TTM turi. Its value is 0.1 by default. See fmd_turi_add() for more information.

fmd_ttm_setCouplingFactor()

void fmd_ttm_setCouplingFactor(fmd_t *md, fmd_handle_t turi, g)

Parameters:

md – an fmd_t
turi – the handle to the TTM turi
g – the coupling factor

Sets the coupling factor for the specified TTM turi. The parameter g is a struct. Its type must match the category of the turi according to the following table.

turi category	data type of `g`
`FMD_TURI_TTM_TYPE1`	`fmd_real_t` or `fmd_ttm_coupling_factor_constant_t`

See fmd_turi_add() for more information.

fmd_ttm_setElectronTemperature()

void fmd_ttm_setElectronTemperature(fmd_t *md, fmd_handle_t turi, fmd_real_t Te)

Parameters:

md – an fmd_t
turi – the handle to the TTM turi
Te – the initial electron temperature

Sets the initial electron temperature of the specified TTM turi.

md_ttm_setHeatCapacity()

void fmd_ttm_setHeatCapacity(fmd_t *md, fmd_handle_t turi, c)

Parameters:

md – an fmd_t
turi – the handle to the TTM turi
c – the electron heat capacity

Sets the electron heat capacity for the specified TTM turi. The parameter c is a struct. Its type must match the category of the turi according to the following table.

turi category	data type of `c`
`FMD_TURI_TTM_TYPE1`	`fmd_ttm_heat_capacity_linear_t`

See fmd_turi_add() for more information.

fmd_ttm_setHeatConductivity()

void fmd_ttm_setHeatConductivity(fmd_t *md, fmd_handle_t turi, k)

Parameters:

md – an fmd_t
turi – the handle to the TTM turi
k – the electron heat conductivity

Sets the electron heat conductivity for the specified TTM turi. The parameter k is a struct. Its type must match the category of the turi according to the following table.

turi category	data type of `k`
`FMD_TURI_TTM_TYPE1`	`fmd_real_t` or `fmd_ttm_heat_conductivity_constant_t`

See fmd_turi_add() for more information.

fmd_ttm_setLaserSource()

void fmd_ttm_setLaserSource(fmd_t *md, fmd_handle_t turi, laser)

Parameters:

md – an fmd_t
turi – the handle to the TTM turi
laser – a struct defining the laser

Sets the laser source term of the TTM equation. The parameter laser is a struct. Its type must match the category of the turi according to the following table.

turi category	data type of `laser`
`FMD_TURI_TTM_TYPE1`	`fmd_ttm_laser_gaussian_t`

See fmd_turi_add() for more information.

fmd_ttm_setTimestepRatio()

void fmd_ttm_setTimestepRatio(fmd_t *md, fmd_handle_t turi, int ratio)

Parameters:

md – an fmd_t
turi – the handle to the TTM turi
ratio – the ratio of MD time step to FD time step

Sets the ratio of the time step used for MD time integration to the time step used for FD time integration. See also fmd_turi_add().

fmd_turi_add()

fmd_handle_t fmd_turi_add(fmd_t *md, fmd_turi_t cat, int dimx, int dimy, int dimz, fmd_real_t starttime, fmd_real_t stoptime)

Parameters:

md – an fmd_t
cat – the category of the turi
dimx – the dimension of the turi in x direction
dimy – the dimension of the turi in y direction
dimz – the dimension of the turi in z direction
starttime – the simulation time when the turi is activated
stoptime – the simulation time when the turi is deactivated

Returns:

the handle to the turi

Adds a new turi to the simulation. Turies are introduced in General notes. The parameter cat specifies the category of the turi. If it is equal to FMD_TURI_CUSTOM, no field is added and the library user can add fields later with fmd_field_add(). If it is equal to FMD_TURI_TTM_TYPE1, the library adds to the turi the fields of categories FMD_FIELD_NUMBER, FMD_FIELD_VCM, FMD_FIELD_TEMPERATURE, FMD_FIELD_TTM_TE and FMD_FIELD_TTM_XI. See fmd_field_t for information about these field categories. The handle to any added field, including the automatically added fields, can be found with fmd_field_find(). When a turi of FMD_TURI_TTM_TYPE1 category exists in a simulation, fmd_dync_integrate() integrates the Newton’s equations of motion coupled with the following generalized heat equation describing the evolution of electron temperature:

\[C_\mathrm{e}\frac{\partial T_\mathrm{e}}{\partial t}=\frac{\partial}{\partial z}\left(K_\mathrm{e}\frac{\partial T_\mathrm{e}}{\partial z}\right)-G\cdot(T_\mathrm{e}-T_\mathrm{l})+S(z,t),\]

where \(C_\mathrm{e}\), \(T_\mathrm{e}\) and \(K_\mathrm{e}\) are the heat capacity, temperature and heat conductivity of the electron subsystem at time \(t\) and position \(z\), respectively. The electron-phonon coupling factor, \(G\), determines how fast thermal energy is transferred between the electron and phonon subsystems, and \(T_\mathrm{l}\) is the lattice temperature. The laser source term \(S(z,t)\) is the laser energy absorbed by the electron subsystem per time unit per volume unit at a depth of \(z\) from the surface of the target. The heat equation above is solved numerically with finite difference (FD) method. The quantities \(C_\mathrm{e}\), \(K_\mathrm{e}\), \(G\) and \(S(z,t)\) must be set by fmd_ttm_setHeatCapacity(), fmd_ttm_setHeatConductivity(), fmd_ttm_setCouplingFactor() and fmd_ttm_setLaserSource(), respectively. The initial electron temperature is set by fmd_ttm_setElectronTemperature(). Usually, the time step for molecular dynamics (MD) time integration is many tens of times larger than the time step used for FD time integration. The ratio is an integer, set by the function fmd_ttm_setTimestepRatio(). When the number of atoms in a turi-cell becomes smaller than a certain fraction of the initial average number of atoms per non-empty turi-cell, that turi-cell is deactivated, which basically means the coupling between MD and FD is neglected for atoms inside it. The fraction by default is one-tenth (0.1) and can be changed by fmd_ttm_setCellActivationFraction(). More details about this so-called MD-TTM scheme can be found in [D.S. Ivanov and L. V. Zhigilei, Phys. Rev. B 68, 064114 (2003)].

Warning

Do not add more than one TTM turi to a simulation.

Each of the parameters dimx, dimy and dimz can be equal to or larger than 1. When the simulation time reaches starttime, the turi is activated, i.e. the fields on it start to get updated. And when the simulation time passes stoptime, the fields do not get updated any longer. If stoptime is less than starttime, the turi is never deactivated.`

fmd_version_getMajor()

int fmd_version_getMajor(): The version format is X.Y.Z.c, where X, Y, Z are non-negative integers and c is a character. This function returns X. See General notes for more information about the versioning scheme.

fmd_version_getMinor()

int fmd_version_getMinor(): The version format is X.Y.Z.c, where X, Y, Z are non-negative integers and c is a character. This function returns Y. See General notes for more information about the versioning scheme.

fmd_version_getRevision()

int fmd_version_getRevision(): The version format is X.Y.Z.c, where X, Y, Z are non-negative integers and c is a character. This function returns Z. See General notes for more information about the versioning scheme.

fmd_version_getString()

int fmd_version_getString(): The version format is X.Y.Z.c, where X, Y, Z are non-negative integers and c is a character. This function returns X.Y.Z as a string. See General notes for more information about the versioning scheme.

fmd_version_getType()

int fmd_version_getType(): The version format is X.Y.Z.c, where X, Y, Z are non-negative integers and c is a character. This function returns c, which can be either ‘r’ or ‘d’, standing for release and development, respectively. See General notes for more information about the versioning scheme.

value	file naming	format	No. of snapshots per file
`FMD_SCM_XYZ_ATOMSNUM`	No. of existing atoms + `.xyz`	XYZ	1 or more
`FMD_SCM_XYZ_SEPARATE`	`00000.xyz`, `00001.xyz`, …	XYZ	1
`FMD_SCM_CSV`	`00000.csv`, `00001.csv`, …	CSV	1
`FMD_SCM_VTF`	`00000.vtf`, `00001.vtf`, …	VTF	1