2. Usage overview for HylleraasMD

HyMD is a Python package that allows large scale parallel hybrid particle-field molecular dynamics (hPF-MD) simulations. The main simulation driver takes as input a toml format configuration file, along with a topology and structure file specifying the input system in HDF5 format.

Configuration file

The configuration file specifies the type and length of simulation to run. A simple example of a configuration file which performs a short simulation of a system contained in a [5, 5, 5] nm simulation box at 300 K may look like the following:

config_simple_1.toml

[simulation]
integrator = "velocity-verlet"
n_steps = 100                      # total simulation steps
n_print = 10                       # output trajectory data every n_print steps
time_step = 0.01                   # time step in ps
box_size = [5.0, 5.0, 5.0]         # simulation box size in nm
target_temperature = 300           # thermostat temperature in Kelvin
tau = 0.1                          # thermostat coupling strength in ps
hamiltonian = "SquaredPhi"         # interaction energy functional
kappa = 0.05                       # compressibility in mol/kJ

[field]
mesh_size = [30, 30, 30]           # FFT grid size
sigma = 0.5                        # filtering length scale in nm

Note that for the version 1.0 release of HyMD, the [particles], [simulation], and [field] groups are optional specifiers for structuring the configuration file.

For a full specification of every recognised configuration keyword in HyMD, please refer to Configuration file.

Topology and structure file

The topology and structure file specifies the positions, momenta, types, and molecular structure of the particles in the system. In order to allow highly parallel file read during program initialisation, the structure file format is a simple flat HDF5 structure. An example structure file for a system containing N particles may look like the following:

example_structure.HDF5

group   /
   # root group

dataset /coordinates
   # float32, shape (T, N, D,)
   # Time steps of N rows of D dimensional coordinate data
   # The last frame is used by default if multiple time steps are provided
   # T is the number of time steps, D is the spatial dimension

dataset /velocities
   # float32, shape (T, N, D,) OPTIONAL
   # Time steps of N rows of D dimensional velocity data
   # The last frame is used by default if multiple time steps are provided
   # T is the number of time steps, D is the spatial dimension

dataset /bonds
   # int32,   shape (N, B,)    OPTIONAL
   # Each row i contains indices of the particles bonds from/to i
   # B denotes the maximum bonds per particle

dataset /indices
   # int32,   shape (N,)
   # Index of each particle, 0--(N-1)

dataset /molecules
   # int32,   shape (N,)
   # Index of molecule each particle belongs to
   # Used to construct bond network locally on MPI ranks

dataset /names
   # str10,   shape (N,)
   # Fixed size string array containing particle type names

dataset /types
   # int32,   shape (N,)       OPTIONAL
   # Mapping of particle names to type indices

For a full specification of the topology and structure input file, see Topology and structure file.

Command line arguments

A select few settings for HyMD are specified on the command line, most notably output files, output directories, output specifications, and random seeds. In addition, the configuration and structure files are provided as the first and second required positional arguments. An example for running the simulation specified by the config_simple_1.toml and example_structure.HDF5 files may look like the following:

mpirun -n ${MPI_NUM_RANKS} python3 -m hymd         \  # HyMD executable
                           config_simple_1.toml    \  # configuration file
                           example_structure.HDF5  \  # structure file
                           --logfile=log_out.txt   \  # set logfile path
                           --seed 123456           \  # set random seed
                           --verbose 2             \  # set logging verbosity
                           --velocity-output          # enable velocity in trajectory output

For a full specification of all command line arguments, see Command line arguments.

More examples

For more thorough rundown and concrete usage examples, see Examples.

2.1. Running parallel simulations

Executing the HyMD code in parallel is fundamentally no different from running it in serial, with the only difference being how the python3 interpreter is invoked. Prepending mpirun -n ${NPROCS} to the usual python3 -m hymd runs the simulation with ${NPROCS} MPI ranks.

Inputting

mpirun -n 6 python3 -m ideal_gas.toml ideal_gas.HDF5 --disable-field

sets up an example simulation of the HyMD-tutorial/ideal_gas system. For more details about this system in particular, or other example simulations, see the HyMD-tutorial repository.

2.2. Running tests

Run serial code tests by

git clone https://github.com/Cascella-Group-UiO/HyMD.git hymd
cd hymd/
python3 -m pip install pytest pytest-mpi
python3 -m pytest

There is a small convenience script in hymd/ for running the MPI-enabled tests,

chmod +x pytest-mpi
./pytest-mpi --nprocs 5 --order-output --no-summary --capture=no