# Running Simulations

The main program for running simulations is `faunus` and should be available
from the command line after installation. For general usage, type:

~~~ bash
faunus --help
~~~

Input is read either from `stdin` or from a JSON formatted file. Some examples:

~~~ bash
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](http://www.yaml.org)
formatted input can be passed:

~~~ bash
yason.py in.yml | faunus # from yaml
~~~

## Input and Output

Natively, input and output are [JSON formatted](http://json.org/example.html):

~~~ json
{ "atomlist": [
        { "Na+": { "q": 1.0, "mw": 22.99 } }
    ]
}
~~~

However, via the helper script `yason.py`, JSON can be converted to/from
[YAML](http://www.yaml.org) which is less verbose, more readable and therefore
used throughout the documentation:

~~~ yaml
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_,

~~~ yaml
# template.yml
geometry: {type: cylinder, length: {{length}}, radius: {{radius}}}
~~~

which can be populated using python:

~~~ 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:

~~~ bash
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:

~~~ 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:

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

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

~~~ bash
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](https://en.wikipedia.org/wiki/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, see installation instructions.
The number of threads is controlled with an environment variable.
The following example demonstrates how to run Faunus using 4 threads:  

~~~ bash
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.`.

~~~ bash
mpirun -np 2 ./faunus -i in.json
~~~

If all processes take the same input:

~~~ bash
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:

~~~ python
import pyfaunus
help(pyfaunus)
~~~

For more examples, see
[`pythontest.py`](https://github.com/mlund/faunus/blob/master/examples/pythontest.py).
Note that the interface is under development and subject to change.