User's Guide

The directory examples contains a set of projects for studying a single or many sphere-dimers in solvent.

Before trying any of the examples, set the environment with

cd angstrom-dimer && . examples/env.sh

which extends LUA_PATH with the modules in the directory nanomotor.

Note that the number of steps is intentionally kept small to permit quick testing during development. Every example also provides a batch job script that may be used to run statistically significant simulations.

Running a simulation

Each project consists of three simulation phases, a thermostat, an equilibration and a production phase. In the thermostat phase, the nanomotors are placed randomly without overlap, the free space is filled with solvent particles that are placed on a lattice of the given density, and the system is thermalised to the given temperature. In the equilibration phase, the system is equilibrated until the concentrations of solvent species reach a steady state. In the production phase, structural and dynamical properties of the system are observed using steady-state averages and time correlation functions.

A simulation phase consists of a simulation script and a configuration file containing parameters for the simulation model and the observables. The results of a simulation are written to a single HDF5 output file in the H5MD format, which organises particle and observable data in a hierarchical structure of groups and datasets.

Thermalise a system of a single sphere-dimer in solvent with

cd examples/single_dimer/thermostat && ./single_dimer.lua config.lua

The current step, total energy and remaining run-time are output periodically to indicate the progress.

OpenCL 1.1 CUDA 4.2.1
NVIDIA CUDA
NVIDIA Corporation
cl_khr_byte_addressable_store cl_khr_icd cl_khr_gl_sharing cl_nv_compiler_options cl_nv_device_attribute_query cl_nv_pragma_unroll 
Tesla C2050
NVIDIA Corporation
cl_khr_byte_addressable_store cl_khr_icd cl_khr_gl_sharing cl_nv_compiler_options cl_nv_device_attribute_query cl_nv_pragma_unroll  cl_khr_global_int32_base_atomics cl_khr_global_int32_extended_atomics cl_khr_local_int32_base_atomics cl_khr_local_int32_extended_atomics cl_khr_fp64 
#0 1.4999772683554 2.0s
#1000 1.4999590904441 2.9m
#2000 2.0443534495855 2.9m
#3000 2.2334617739199 2.9m
#4000 2.2995373838134 2.9m
#5000 2.321627116407 2.9m
…

The equilibration phase may be run with

cd ../equilibration && ./single_dimer.lua config.lua

which reads the system state from the output file of the thermostat phase.

The results are written to the file single_dimer.h5, which may be analysed and plotted with Python scripts using h5py, NumPy, and Matplotlib. For interactive analysis, IPython provides a shell and a graphical notebook.

The average total energy per particle may be plotted with

../../../tools/total_energy.py total_energy.pdf single_dimer.h5

The center of mass velocity may be plotted with

../../../tools/center_of_mass_velocity.py center_of_mass_velocity.pdf single_dimer.h5

The mole fractions of the solvent species may be plotted with

../../../tools/species.py species.pdf single_dimer.h5

The production phase may be run with

cd ../production && ./single_dimer.lua config.lua

which reads the system state from the output file of the equilibration phase.

The production phase periodically snapshots the simulation state. Try interrupting the simulation with Ctrl + c:

#0 2.3348551220848 4.7s
#10000 2.3348557078885 2.9m
#20000 2.3348557719259 2.6m
^C

When the simulation is rerun, it picks up exactly where the snapshot was taken:

./single_dimer.lua config.lua

#20000 2.3348557719259 5.9s
#30000 2.3348569806129 2.3m
#40000 2.3348563725576 2.0m
#50000 2.3348558040583 1.6m
…

A snapshot file is written atomically, i.e., it is guaranteed to contain a consistent state of the simulation.