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 }

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

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.