Running Simulations¶
The main program for running simulations is faunus
and should be available
from the command line after installation. For general usage, type:
faunus --help
Input is read either from stdin
or from a JSON formatted file. Some examples:
faunus < input.json # input from stdin
faunus -i in.json -o out.json -q # file input/output and be quiet
Via the script yason.py
, see below, YAML
formatted input can be passed:
yason.py in.yml | faunus # from yaml
Input and Output¶
Natively, input and output are JSON formatted:
{ "atomlist": [
{ "Na+": { "q": 1.0, "mw": 22.99 } }
]
}
However, via the helper script yason.py
, JSON can be converted to/from
YAML which is less verbose, more readable and therefore
used throughout the documentation:
atomlist:
- Na+: { q: 1.0, mw: 22.99 }
Generating several input files for a parameter scan, it can be helpful to use an input template file,
# template.yml
geometry: {type: cylinder, length: {{length}}, radius: {{radius}}}
which can be populated using python:
from jinja2 import Template
with open('template.yml') as f:
output = Template(f.read()).render(
length = 200,
radius = 50 )
print(output)
Post-Processing¶
JSON formatted output can conveniently be converted to syntax highlighted YAML for better readability:
yason.py --color out.json
For further processing of output or input, JSON (and YAML) can be read by most programming languages. For example in python:
import json
with open('out.json') as f:
d = json.load(f) # --> dict
print( d['atomlist'][0]["Na+"]["mw"] ) # --> 22.99
# ^ ^ ^ ^
# | | | |
# | | | get mol. weight value
# | | key is the atom name
# | fist object in array
# atomlist is an array of objects
Restarting¶
Restart files generated by the analysis function savestate
contains the last system state (positions, groups etc.).
To start from the previously saved state, use:
faunus --input in.json --state state.json
Diagnostics¶
Faunus writes various status and diagnostic messages to the standard error
output. The amount of messages can be control with the --verbosity
(-v
)
option ranging from completely suppressed messages to tracing all
operations. Only warnings and errors are shown by default. It may be useful
to increase the verbosity level when debugging to show status and debug
information.
faunus --verbosity 5 --input in.json
Note this is an experimental feature, covering only a fraction of actions so far.
-v |
verbosity level |
---|---|
0 | off |
1 | critical error |
2 | error |
3 | warning |
4 | information (default) |
5 | debug information |
6 | tracing information |
Tip: Redirect the standard error output to a log file.
faunus -v 5 -i in.json 2>> error.log
Parallelization¶
By default, Monte Carlo moves and energy evaluations run in serial and are not sped up by OpenMP/MPI as described below. Pragmas for non-bonded interactions can relatively easily be added, but this currently requires source modifications. We are working to make this user-controllable and in the meantime consider using an embarrassingly parallel scheme via different random seeds (provided that your system equilibrates quickly).
OpenMP¶
Some routines in Faunus can run in parallel using multiple threads. The only prerequisite is that Faunus was compiled with OpenMP support (which is default). The number of threads is controlled with an environment variable. The following example demonstrates how to run Faunus using 4 threads:
export OMP_NUM_THREADS=4
faunus -i in.json
Message Passing Interface (MPI)¶
Only few routines in Faunus are currently parallelisable using MPI, for example parallel tempering, and penalty function energies.
Running with MPI spawns nproc
processes that may or may not communicate
with each other. If nproc>1
, input and output files are prefixed with
mpi{rank}.
where {rank}
is the rank or process number, starting from zero.
The following starts two processes, reading input from mpi0.in.json
and
mpi1.in.json
. All output files, including those from any analysis are
prefixed with mpi0.
and mpi1.
.
mpirun -np 2 ./faunus -i in.json
If all processes take the same input:
mpirun -np 2 ./faunus --nopfx --input in.json
mpirun -np 2 --stdin all ./faunus < in.json
Python Interface¶
An increasing part of the C++ API is exposed to Python. For instance:
import pyfaunus
help(pyfaunus)
For more examples, see
pythontest.py
.
Note that the interface is under development and subject to change.