Faunus runs Metropolis Monte Carlo simulations of atomic and molecular systems: electrolytes, proteins, polymers and their mixtures. Instead of integrating forces over time, it proposes random moves (translate, rotate, change volume, swap, react) and accepts each with probability set by the energy change. The sampled states follow the Boltzmann distribution, so averages are equilibrium averages.
Input is one JSON file with the atom and molecule definitions, the energy terms (here Lennard-Jones plus Coulomb), the moves, the geometry, the temperature and the analyses to run. Output is out.json with run statistics and the analysis files you asked for.
The key assumption is that you only need equilibrium properties. Monte Carlo has no dynamics, so it cannot give diffusion rates or timescales. The example treats the solvent as a continuum with relative permittivity 80.
When to use it
Electrolytes, proteins and polymers at equilibrium, such as ion pairing and salt effects.
Systems that need volume moves, the Gibbs ensemble or equilibrium reactions, which the Faunus docs list among its moves and topology options.
Alternatives on biosimhub: LAMMPS, GROMACS and OpenMM give time-resolved trajectories and explicit solvent. Use them for kinetics or when water structure matters.
Install it yourself
Faunus 2.16.3 from conda-forge. The dry run resolved faunus 2.16.3 (Python 3.13 build, 162 MB in total):
conda install -c conda-forge faunus=2.16.3
The Faunus docs say the package installs the faunus executable, a set of examples in share/faunus, and Python bindings. Minimal run:
faunus -i in.json -o out.json -q
-q runs quietly, and --verbosity (0 to 6) sets the message level on stderr. Input can also come from stdin (faunus < input.json). yason.py converts between JSON and YAML input.
Run the tested example
This recipe builds Faunus in a container and runs the example below. It needs Docker and nothing else. It last ran on 2026-10-12 in 2.2 s.
Inputs are read from in/ and results land in out/. Change the values after each option to run your own case; the parameter table lists them.
Expected output
File
Size
confout.pqr
2.8 KB
energy.dat
10.2 KB
out.json
2.7 KB
state.json
5.1 KB
First lines of confout.pqr
REMARK Generated by Faunus - https://github.com/mlund/faunus
CRYST1 50.000 50.000 50.000 90.00 90.00 90.00 P 1 1
ATOM 1 Na sal 1 11.240 49.129 36.426 1.000 2.000
ATOM 2 Cl sal 1 6.626 45.578 1.028 -1.000 2.000
ATOM 3 Na sal 1 11.569 14.176 3.027 1.000 2.000
ATOM 4 Cl sal 1 5.662 20.786 45.715 -1.000 2.000
ATOM 5 Na sal 1 10.461 8.661 5.901 1.000 2.000
ATOM 6 Cl sal 1 37.002 14.511 35.483 -1.000 2.000
ATOM 7 Na sal 1 30.617 44.236 37.093 1.000 2.000
ATOM 8 Cl sal 1 3.719 22.785 43.276 -1.000 2.000
ATOM 9 Na sal 1 36.133 39.860 48.772 1.000 2.000
ATOM 10 Cl sal 1 44.142 30.340 30.837 -1.000 2.000
The example salt.json puts 20 Na+ and 20 Cl- ions (charges +1 and -1, sigma 4 A) in a cubic box of side 50 A, which is about 0.27 M of salt. Energy terms are Lennard-Jones with Lorentz-Berthelot mixing and plain Coulomb with relative permittivity 80 at 300 K. The only move is transrot on the salt molecule. The random seed is fixed, which is deterministic.
The loop is 10 macro steps of 2000 micro steps, so 20000 sweeps. out.json (2722 bytes) reports:
800000 moves in total (20000 sweeps x 40 particles) with an acceptance of 0.652.
A Bjerrum length of 6.96 A (the Coulomb term's lB).
The systemenergy analysis: mean energy -15.995 kT over 200 samples, a heat capacity Cv/kB of 4.822, and an initial energy of 706.02 kT.
An average potential energy of -15.987 kT from the Monte Carlo loop itself.
Other files:
energy.dat (10458 bytes) has one row per 100 sweeps. The first row (step 100) reads -16.33 kT and the last (step 20000) -14.11 kT. The initial 706 kT is a random starting configuration, and the energy relaxes within 100 sweeps.
confout.pqr (2916 bytes) is the final configuration in PQR format: coordinates in angstroms, then charge and radius (for example 1.000 2.000 for Na).
state.json (5180 bytes) is a restart file. Resume with faunus --input in.json --state state.json.
Weaker screening: change "epsr": 80 to 20. The Bjerrum length rose to 27.8 A, the mean energy dropped to -112.45 kT, Cv/kB rose to 47.7 and acceptance fell to 0.206. Ions form tight pairs.
A dilute solution: set "length": 100. The salt falls to about 0.033 M. The mean energy was -7.46 kT, Cv/kB 2.97 and acceptance 0.822.
A warmer solution: set "temperature": 400. The Bjerrum length fell to 5.22 A. The mean energy was -10.68 kT.
A new seed: change "seed": "fixed" to "hardware". The mean energy moved from -15.995 to -15.697 kT and Cv/kB from 4.82 to 4.93. That spread of 0.3 kT is the statistical noise of a 20000-sweep run.
Pitfalls
The 400 K run keeps epsr at 80, so it changes only the temperature. Set epsr yourself when you change solvent or temperature.
"type": "plain" Coulomb reports a cutoff of 1.3e154 in out.json, which is no cutoff. Use a box large enough for the question.
Energies are in kT and lengths in angstroms. Convert before you compare with kJ/mol results.
fixed seed gives the same run every time. Use hardware for independent repeats and compare their spread.
The initial energy (706 kT here) is large because the start is random. Discard early samples from averages.
Short runs have error bars. Run repeats before you read small differences.