title: 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 in the examples, 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] file 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
OpenCL 1.1 CUDA 4.2.1
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_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 current step, total energy and remaining run-time are output periodically
to indicate the progress of the simulation.
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 an interactive
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
When the simulation is rerun, it picks up exactly where the snapshot was taken:
#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., the snapshot is guaranteed to
contain a consistent state of the simulation.