Ångström-scale chemically powered sphere-dimer motor https://colberg.org/angstrom-dimer
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Peter Colberg c5183630a8 Fix spelling of “Ångström” 3 years ago
..
CHANGES.html Fix spelling of “Ångström” 3 years ago
CHANGES.mdwn Add release notes 3 years ago
INSTALL.html Fix spelling of “Ångström” 3 years ago
INSTALL.mdwn Fix spelling of “Ångström” 3 years ago
Makefile Add release notes 3 years ago
README.html Fix spelling of “Ångström” 3 years ago
README.mdwn Write user's guide 3 years ago
angstrom-dimer.bib Cite Nanoconfined catalytic Ångström-size motors 3 years ago
center_of_mass_velocity.svg Write user's guide 3 years ago
contents.mdwn Fix spelling of “Ångström” 3 years ago
index.html Fix spelling of “Ångström” 3 years ago
index.mdwn Cite Nanoconfined catalytic Ångström-size motors 3 years ago
pandoc.css Summarise project 3 years ago
pandoc.html.in Summarise project 3 years ago
species.svg Write user's guide 3 years ago
total_energy.svg Write user's guide 3 years ago

README.mdwn

---
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.

[H5MD]: http://nongnu.org/h5md/

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
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 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.

[h5py]: http://www.h5py.org/
[numpy]: http://www.numpy.org/
[matplotlib]: http://www.h5py.org/
[ipython]: http://ipython.org/

The average total energy per particle may be plotted with

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

![](total_energy.svg)


The center of mass velocity may be plotted with

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

![](center_of_mass_velocity.svg)

The mole fractions of the solvent species may be plotted with

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

![](species.svg)


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., the snapshot is guaranteed to
contain a consistent state of the simulation.