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