3. Configuration file

The HyMD configuration file specifies all aspects of the simulation, including temperature coupling, bond specifications and strengths, the hPF interaction energy potential, the integrator, and more. The keywords may be given in any order.

The configuration file is a toml format file with keywords (strings) and values (strings, numbers, arrays, etc.) which is serialised and parsed to configure simulation runs.

3.1. Configuration file keywords

The following constitutes every possible keyword specification in HyMD configuration files:

3.1.1. Metadata keywords

Configuration keywords specifying metadata for the H5MD output trajectory.

name:

string [optional, default: None]

Name for the simulation. Optional keyword specifying a name in the metadata for the H5MD output trajectory/energy file.

tags:

array [string] [optional, default: None]

Tags for the simulation. Optional keyword specifying metadata tags for the H5MD output trajectory/energy file.

3.1.2. Particle keywords

Configuration keywords specifying properties of particles and molecules in the system.

n_particles:

integer [optional, default: None]

Specifies the total number of particles in the input. Optional keyword for validation, ensuring the input HDF5 topology has the correct number of particles and molecules.

mass:

float [optional, default: 72.0] {units: \(\text{u}=\text{g}\,\text{mol}^{-1}\)}

Mass of the particles in the simulation. Unless masses are provided in the HDF5 topology/structure file, all masses are assumed equal.

max_molecule_size:

integer [optional, default: 201]

Maximum size of any single molecule in the system. Used to speed up distribution of particles onto MPI ranks in a parallel fashion. The code will crash if there are molecules larger than max_molecule_size in the topology/structure input file.

3.1.3. Simulation keywords

Configuration keywords specifying simulation parameters.

n_steps:

integer [required]

Total number of integration steps to perform for this simulation.

n_print:

integer or boolean [optional, default: False]

Frequency of trajectory/energy output to the H5MD trajectory/energy output file (in units of number of time steps).

n_flush:

integer [optional, default: None]

Frequency of HDF5 write buffer flush, forcing trajectory/energy to be written to disk (in units of number of n_print, i.e. n_print = 13, n_flush = 3 would result in the trajectory/energy being written to disk every 13 x 3 = 39 simulation steps)

time_step:

float [required] {units: \(\text{ps}=10^{-12}~\text{s}\)}

The time step per integration step. If the rRESPA multiple time step integrator is used (integrator = "respa"), this specifies the inner time step, i.e. the step size used for the intramolecular force integration. In that case, the step size for the field force impulses is respa_inner times the time_step , and the total simulation time is n_steps times time_step times respa_inner .

box_size:

array [float] [required] {units: \(\text{nm}=10^{-9}~\text{m}\)}

Size of the simulation box. Any particle outside the box is placed inside before the first time step is integrated, meaning no particles will be lost if the box size is specified too small, but the system may nevertheless be unstable.

integrator:

string [required] (options: velocity-verlet or respa)

Specifies the time integrator used in the simulation. If respa, the reversible reference system propagator algorithm (rRESPA) [Tuckerman et al., 1992] integrator is used, with respa_inner number of inner (intramolecular force) time steps. If velocity-verlet, a normal Velocity Verlet integrator is used. If respa and respa_inner = 1, the rRESPA integrator is equivalent to the Velocity Verlet.

respa_inner:

integer [optional, default: 1]

The number of inner time steps in the rRESPA integrator. This denotes the number of intramolecular force calculations (stretching, bending, torsional) are performed between each impulse applied from the field forces.

domain_decomposition:

integer or boolean [optional, default: False]

Specifies the interval (in time steps) of domain decomposition exchange, involving all MPI ranks sending and receiving particles according to the particles’ positions in the integration box and the MPI ranks’ assigned domain. Performing the decomposition is expensive in terms of MPI communication cost, but may reduce the communication of particle positions across MPI rank boundaries for some time during simulation. If True, the decomposition is performed once (before starting the simulation). If False, no decomposition is performed.

cancel_com_momentum:

integer or boolean [optional, default: False]

If True, the total linear momentum of the center of mass is removed before starting the simulation. If an integer is specifed, the total linear momentum of the center of mass is removed every remove_com_momentum time steps. If False, the linear momentum is never removed.

start_temperature:

float or boolean [optional, default: False] {units: \(\text{K}\)}

Generate starting temperature by assigning all particle velocities randomly according to the Maxwell-Boltzmann distribution at start_temperature Kelvin prior to starting the simulation. If False, the velocities are not changed before starting the simulation.

target_temperature:

float or boolean [optional, default: False] {units: \(\text{K}\)}

Couple the system to a heat bath at target_temperature Kelvin by applying a Canonical sampling through velocity rescaling [Bussi et al., 2007] thermostat with coupling strength tau. If False, no temperature control is applied.

tau:

float [optional, default: 0.7] {units: \(\text{ps}=10^{-12}~\text{s}\)}

The time scale of the CSVR thermostat coupling. In the limit of tau → ∞, the Hamiltonian dynamics are preserved and no temperature coupling takes place.

thermostat_coupling_groups:

array [array [string]] [optional, default: []]

Specifies individual groups coupling independently to the CSVR thermostat. E.g. in a system containing "A", "B", and "C" type particles, thermostat_coupling_groups = [["A", "B"], ["C"],] would thermalise types "A" and "B" together and couple "C" type particles to a different thermostat (all individual thermostats are at the same temperature, i.e. target_temperature Kelvin).

hamiltonian:

string [optional, default: "DefaultNohChi"] (options: SquaredPhi, DefaultNohChi, or DefaultWithChi)

Specifies the interaction energy functional \(W[\tilde\phi]\) for use with the particle-field interactions. See Interaction energy functionals for details.

3.1.4. Field keywords

Configuration keywords specifying field parameters.

mesh_size:

array [integer] or integer [required]

Either an integer or an array of three integers specifying the mesh grid size to use in each of the three spatial directions for the FFT operations. The grid spacing is box_size / mesh_size.

kappa:

float [required] {units: \(\text{kJ}^{-1}\text{mol}\)}

Compressibility parameter used in the relaxed incompressibility term in the interaction energy functional \(W[\tilde\phi]\). See Interaction energy functionals for more details.

sigma:

float [required] {units: \(\text{nm}=10^{-9}~\text{m}\)}

Filter width, representing the effective coarse-graining level of the particles in the simulation. If a Gaussian filter is used (by default), this specifies the standard deviation. See Filtering for more details.

chi:

array [array [string, float]] [optional, default: []] {units: \(\text{kJ}\,\text{mol}^{-1}\)}

Array of \(\tilde\chi_\text{AB}\)-parameters indicating the strength of the repulsive or attractive interaction between particles of type "A" and the number density due to particles of type "B", and vice versa. Example: chi = [ ["A", "B", 7.28], ["C", "D", -1.32] ] would specify a repulsive "A"–"B" type interaction, and a weakly attractive "C"–"D" interaction. Self-interaction \(\tilde\chi\)-terms are always zero. See Interaction energy functionals for more details.

3.1.5. Bond keywords

Configuration keywords specifying bonds and bonds parameters.

bonds:

array [array [2 string, 2 float]] [optional, default: []] {units: \(\text{nm}=10^{-9}~\text{m}\) and \(\text{kJ}\,\text{mol}^{-1}\)}

Specifies harmonic stretching potentials between particles in the same molecule. Each entry in the array specifies one bond between two types of particles, followed by the equilibrium distance and the bond stiffness. Example: bonds = [ ["A", "A", 0.47, 980.0], ["A", "B", 0.31, 1250.0] ] indicates a "A"–"A" bond of equilibrium length 0.47 \(\text{nm}\) with a bond strength of 980.0 \(\text{kJ}\,\text{mol}^{-1}\) and a corresponding bond between "A" and "B" type particles with equilibrium length 0.31 \(\text{nm}\) and a strength of 1250.0 \(\text{kJ}\,\text{mol}^{-1}\). See Intramolecular bonds for details about how to specify stretching bonds.

angle_bonds:

array [array [3 string, 2 float]] [optional, default: []] {units: \({}^\circ\) and \(\text{kJ}\,\text{mol}^{-1}\)}

Specifies harmonic angular bending potentials between particles in the same molecule. Each entry in the array specifies one bond between three types of particles, followed by the equilibrium angle (in degrees) and the angle bond stiffness. Example: bonds = [ ["A", "A", "A", 180.0, 55.0], ["A", "B", "B", 120.0, 25.0] ] indicates a "A"–"A"–"A" angular bond that tries to keep the bond linear at 180 degrees with a bending strength of 55.0 \(\text{kJ}\,\text{mol}^{-1}\) and a corresponding angle bond between "A"–"B"–"B" prefering the angle at 120 degrees and a strength of 25.0 \(\text{kJ}\,\text{mol}^{-1}\). See Intramolecular bonds for details about how to specify angular bonds.

dihedrals:

array [array [4 string, integer, COSINE SERIES ]] [optional, default: []] {units: \(\text{kJ}\,\text{mol}^{-1}\text{rad}^{-2}\)}

Specifies four-particle torsional potentials by cosine series. See Intramolecular bonds for details about how to specify dihedrals.

3.1.6. Electrostatic keywords

Configuration keywords specifying electrostatics and electrostatic parameters.

coulombtype:

string [optional, default: None] (options: PIC_Spectral)

Specifies the type of electrostatic Coulomb interactions in the system. The strength of the electrostatic forces is modulated by the relative dielectric constant of the simulation medium, specified with the dielectric_const keyword. Charges for individual particles are specified in the structure/topology HDF5 input file, not in the configuration file. If no charges (or peptide backbone dipoles) are present, the electrostatic forces will not be calculated even if this keyword is set to PIC_Spectral.

dielectric_const:

float [optional, default: None]

Specifies the relative dielectric constant of the simulation medium which regulates the strength of the electrostatic interactions. When using helical propensity dihedrals, this keyword must be specified—even if electrostatics are not included with the coulombtype keyword.

3.1.7. Pressure keywords

Configuration keywords specifying pressure and barostat parameters.

3.1.7.1. Simulation keywords

pressure:

boolean [optional, default: False]

Specifies whether or not to calculate total internal pressure vector.

barostat:

string [optional, default: None](options: isotropic or semiisotropic)

Specifies whether to apply pressure constraints equally in all 3 Cartesian directions (isotropic) or equally in xy and different in z (semiisotropic).

barostat_type:

string [optional, default: berendsen](options: berendsen or scr)

Specifies the type of barostat to use. berendsen is more suitable for equilibration and scr for equilibrium data collection.

n_b:

integer [optional, default: 1]

Frequency of barostat call in number of outer rRESPA steps.

tau_p:

float [optional, default: 10 tau if tau < 0.1 else 1.0] {units: \(\text{ps}=10^{-12}~\text{s}\)}

The time scale of the barostat coupling.

target_pressure:

array [float] [optional, default: :code:1] {units: bar}

Couples the system to an external pressure set to target_pressure.

3.1.7.2. Field keywords

rho0:

float [optional, default: :code:average density] {units: \(\text{nm}^{-3}\)}

Intrinsic parameter corresponding to the specific volume of a coarse-grained particle. Typically: 8.66

a:

float [required] {units: \(\text{nm}^{-3}\)}

Calibrated parameter to obtain the correct average density at the target temperature and pressure. Typically: 9.21