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 nano-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 two simulation phases, an equilibration and a production phase. In the equilibration phase, the nanomotors are placed randomly without overlap, the free space is filled with solvent particles of the given density and temperature, and 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.

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

cd examples/single_dimer/equilibration && ./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 0.2500008792 4.0s
#1000 0.25000087452767 1.3m
#2000 0.25000087466829 1.4m
#3000 0.25000087047698 1.4m
#4000 0.25000086889896 1.3m
#5000 0.25000087682256 1.4m
…

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 total energy 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 0.25000091676174 21.7s
#10000 0.25000091853318 1.6m
#20000 0.25000091383999 1.5m
^C

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

./single_dimer.lua config.lua

#20000 0.25000091383999 15.3s
#30000 0.25000091963694 1.3m
#40000 0.25000092646063 1.1m
#50000 0.25000091554534 55.3s
…

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