### Setup Ashbaugh-Hatch Potential

Source: https://faunus.readthedocs.io/en/latest/_docs/energy.html

Example configuration for the Ashbaugh-Hatch potential within the energy section of a Faunus input file.

```yaml
atomlist:
    - hydrophobic: {sigma: 5.0, eps: 1.0, lambda: 1.0}
    - hydrophilic: {sigma: 5.0, eps: 1.0, lambda: 0.0}
energy:
    - nonbonded:
        default:
            - ashbaugh-hatch: {mixing: LB}
```

--------------------------------

### Electric Potential Configuration Example

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/analysis.md.txt

Example configuration for the electricpotential analysis module using a random_walk policy to measure potential at target points.

```yaml
- electricpotential:
    nstep: 20
    ncalc: 10
    epsr: 80
    type: plain
    policy: random_walk
    stride: 10   # in angstrom
    structure:
      - [0,0,0]  # defines two target points...
      - [0,0,0]  # ...positions are randomly set
```

--------------------------------

### Open Faunus user manual in browser

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/docs.md.txt

Launches the Faunus user guide in a web browser.

```bash
faunus-manual
```

--------------------------------

### Faunus analysis configuration example

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/analysis.md.txt

Example YAML configuration for the `analysis` section, showing how to add multiple analysis functions with their parameters. All analysis methods support `nstep` (sampling interval) and `nskip` (initial steps excluded).

```yaml
analysis:
    - systemenergy: {file: energy.dat.gz, nstep: 500, nskip: 2000}
    - xtcfile: {file: traj.xtc, nstep: 1000}
    - widom:  {molecule: water, ninsert: 20, nstep: 50}
    - molrdf: {name1: water, name2: water, nstep: 100,
               dr: 0.1, dim: 3, file: rdf.dat}
    - ...
```

--------------------------------

### YAML input format example

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/running.md.txt

Shows the equivalent YAML structure for defining an atom list.

```yaml
atomlist:
    - Na+: { q: 1.0, mw: 22.99 }
```

--------------------------------

### Install Faunus with Conda

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/install.md.txt

Adds the conda-forge channel and installs the faunus package. This also installs examples in share/faunus and Python bindings.

```bash
conda config --add channels conda-forge
conda install faunus
```

--------------------------------

### Penalty Function YAML Setup

Source: https://faunus.readthedocs.io/en/latest/_docs/energy.html

Example configuration for the penalty energy term, penalizing the x and y positions of atom 0 to achieve uniform sampling. Options include f0 (penalty increment), scale (scaling factor), update (interval), file (saved/loaded penalty function), and coords (array of one or two coordinates).

```yaml
energy:
- penalty:
    f0: 0.5
    scale: 0.9
    update: 1000
    file: penalty.dat
    coords:
    - atom: {index: 0, property: "x", range: [-2.0,2.0], resolution: 0.1}
    - atom: {index: 0, property: "y", range: [-2.0,2.0], resolution: 0.1}

```

--------------------------------

### Install pre-commit hook for code formatting

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/install.md.txt

Installs a git pre-commit hook that automatically styles changes with clang-format, beneficial for contributors.

```bash
cd faunus
./scripts/git-pre-commit-format install
```

--------------------------------

### Build and run Faunus Docker image

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/install.md.txt

Downloads the Dockerfile from the repository, builds the image, and starts a JupyterLab session on port 8888.

```bash
curl -s https://raw.githubusercontent.com/mlund/faunus/master/scripts/Dockerfile | docker build -t faunuslab -
docker run -it -p 8888:8888 faunuslab # open generated url in a browser
```

--------------------------------

### Restart from state file

Source: https://faunus.readthedocs.io/en/latest/_docs/running.html

Starts a simulation from a previously saved state file using the --state option.

```bash
faunus --input in.json --state state.json

```

--------------------------------

### Install a local conda package

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/install.md.txt

Command to install the built package locally instead of uploading it to anaconda.org.

```bash
conda install -c USER faunus --use-local
```

--------------------------------

### Cluster move configuration example

Source: https://faunus.readthedocs.io/en/latest/_docs/moves.html

Example configuration for the 'cluster' move, specifying molecules, satellites, a distance threshold matrix, and translational/rotational displacements. The 'analysis' option saves shape properties to 'cluster_shape.dat.gz'.

```yaml
cluster:
   molecules: [protein, cations]
   satellites: [cations]
   threshold:
      protein protein: 25
      protein cations: 15
      cations cations: 0
   dp: 3
   dprot: 1
   analysis: {file: cluster_shape.dat.gz}

```

--------------------------------

### insertmolecules configuration example

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/topology.md.txt

Example of the insertmolecules section in a Faunus input file. It inserts salt to a molarity of 0.1 and 256 water molecules, with 2 water molecules set as inactive.

```yaml
insertmolecules:
  - salt:  { molarity: 0.1 }
  - water: { N: 256, inactive: 2 }

```

--------------------------------

### JSON input format example

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/running.md.txt

Shows the native JSON structure for defining an atom list.

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

--------------------------------

### moleculelist YAML example with salt, water, and carbon dioxide

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/topology.md.txt

Example of a moleculelist definition in YAML, showing salt, water, and carbon dioxide molecules with their properties. The carbon dioxide example includes a structure, harmonic bonds, a harmonic torsion, and an exclusionlist generated by excluded_neighbours.

```yaml
moleculelist:
  - salt: {atoms: [Na,Cl], atomic: true}
  - water:
      structure: water.xyz
      bondlist:
        - harmonic: {index: [0,1], k: 100, req: 1.5}
        - ...
  - carbon_dioxide:
      structure:
        - O: [-1.162,0,0]
        - C: [0,0,0]
        - O: [1.162,0,0]
      bondlist:
        - harmonic: {index: [1,0], k: 8443, req: 1.162}
        - harmonic: {index: [1,2], k: 8443, req: 1.162}
        - harmonic_torsion: {index: [0,1,2], k: 451.9, aeq: 180}
      excluded_neighbours: 2 # generates an exclusionlist as shown below
      exclusionlist: [ [0,1], [1,2], [0,2] ] # redundant in this topology
  - ...
```

--------------------------------

### Build and upload a conda package

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/install.md.txt

Commands to configure channels, install build tools, build the package from the scripts directory, and upload it to anaconda.org.

```bash
conda config --add channels conda-forge
conda install conda-build anaconda-client
cd scripts/
conda-build .
anaconda login
anaconda upload -u USER ... # see output from build step
```

--------------------------------

### Link against TBB with CMake

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/install.md.txt

Enables C++ parallel algorithms by linking TBB. Requires installing TBB via apt/brew/conda and providing TBB_DIR pointing to the installation's CMake config.

```bash
cmake -DENABLE_TBB=on -DTBB_DIR={tbb-root}/lib/cmake/TBB
```

--------------------------------

### Define a Yukawa potential using Custom

Source: https://faunus.readthedocs.io/en/latest/_docs/energy.html

Example configuration for a Yukawa potential using the custom potential module, defining the mathematical function and required constants.

```yaml
custom:
    function: lB * q1 * q2 / r * exp( -r/D ) # in kT
    constants:
        lB: 7.1  # Bjerrum length
        D: 30    # Debye length
```

--------------------------------

### Configure system energy terms

Source: https://faunus.readthedocs.io/en/latest/_docs/energy.html

Example of defining potential energy terms such as isobaric, sasa, confine, and nonbonded interactions within the energy input block.

```yaml
energy:
    - isobaric: {P/atm: 1}
    - sasa: {molarity: 0.2, radius: 1.4 }
    - confine: {type: sphere, radius: 10, molecules: [water]}
    - nonbonded:
        default: # applied to all atoms
        - lennardjones: {mixing: LB}
        - coulomb: {type: plain, epsr: 1}
        Na CH:   # overwrite specific atom pairs
        - wca: { mixing: LB }

    - maxenergy: 100
    - ...
```

--------------------------------

### Force ZLIB location with CMake

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/install.md.txt

Specifies the ZLIB installation directory when multiple ZLIB installations cause CMake conflicts; must be run in a clean build directory.

```bash
cmake -DZLIB_ROOT=...
```

--------------------------------

### Configure custom external potential for spherical confinement

Source: https://faunus.readthedocs.io/en/latest/_docs/energy.html

This example demonstrates how to confine molecules within a spherical shell by defining a custom potential function using ExprTk syntax.

```yaml
customexternal:
    molecules: [water]
    com: true
    constants: {radius: 15, dr: 3}
    function: >
        var r2 := x^2 + y^2 + z^2;
        if ( r2 < radius^2 )
           1000 * ( radius-sqrt(r2) )^2;
        else if ( r2 > (radius+dr)^2 )
           1000 * ( radius+dr-sqrt(r2) )^2;
        else
           0;
```

--------------------------------

### Example moves section with random seed

Source: https://faunus.readthedocs.io/en/latest/_docs/moves.html

Shows the top-level 'moves' section with a 'moltransrot' move for water, a 'volume' move, and a 'random' section with a hardware seed. The 'repeat: N' is a placeholder for the number of repeats per MC sweep.

```yaml
moves:
    - moltransrot: { molecule: water, dp: 2.0, repeat: N,
                    dprot: 1.0, dir: [1,1,0] }
    - volume: { dV: 0.01 }
    - ...

random: { seed: hardware }

```

--------------------------------

### Run MPI parallelized free energy sampling

Source: https://faunus.readthedocs.io/en/latest/_docs/energy.html

Starts multiple MPI processes using the same input file, with the MPI prefix automatically appended to input and output files.

```bash
yason.py input.yml | mpirun --np 6 --stdin all faunus -s state.json
```

--------------------------------

### Configure Group Matrix Analysis in YAML

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/analysis.md.txt

Example configuration for analyzing nonbonded energy between active colloid molecules, filtering for values smaller than -1.0 kT and saving to a compressed Matrix Market file.

```yaml
analysis:
  - groupmatrix:
      nstep: 20
      molecules: [colloid]
      property: energy
      filter: "value < -1.0"
      file: energies.mtx.gz
```

--------------------------------

### Read JSON output in Python

Source: https://faunus.readthedocs.io/en/latest/_docs/running.html

Example of reading JSON output in Python, accessing the molecular weight of the first atom.

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

```

--------------------------------

### Harmonic constraint example

Source: https://faunus.readthedocs.io/en/latest/_docs/energy.html

Constrains a system property (Lx) using a harmonic potential with req=100.0 and k=500.0. The range is ignored when harmonic is given.

```yaml
energy:
    - constrain: {type: system, property: Lx, harmonic: {req: 100.0, k: 500.0}}

```

--------------------------------

### Configure nonbonded interactions

Source: https://faunus.readthedocs.io/en/latest/_docs/energy.html

Defines a general nonbonded interaction setup with default potentials and custom potentials for specific atom type combinations.

```yaml
- nonbonded:
    default: # default pair potential
        - lennardjones: {mixing: LB}
        - coulomb: {type: fanourgakis, epsr: 1.0, cutoff: 12}
    Ow Ca: # custom potential for atom type "Ow" and atom type "Ca"
        - wca: {mixing: LB}
```

--------------------------------

### YAML: Precipitation of Calcium Hydroxide using implicit molecules

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/topology.md.txt

Defines a system with an implicit Ca(OH)2 solid phase and explicit Ca++ and OH- ions. The reaction list includes the solubility product (pK: 5.19) to model dissolution. Starts with an empty simulation box and 200 implicit molecules that convert to explicit upon forward reaction.

```yaml
moleculelist:
    - Ca(OH)2: {implicit: true} # this molecule is implicit
    - Ca++: {atoms: [ca++], atomic: true}
    - OH-: {atoms: [oh-], atomic: true}
insertmolecules:
    - Ca++: {N: 200, inactive: true}
    - OH-: {N: 400, inactive: true}
    - Ca(OH)2: {N: 200} # not actually inserted!
reactionlist:
    - "Ca(OH)2 = Ca++ + OH- + OH-": {pK: 5.19}

```

--------------------------------

### Regional Monte Carlo with ellipsoid policy

Source: https://faunus.readthedocs.io/en/latest/_docs/moves.html

Example configuration for the 'moltransrot' move with a 'region' block using the 'ellipsoid' policy. The region is defined by two reference particles and radii, with 'p' controlling the sampling preference.

```yaml
- moltransrot:
    ...
    ...
    region:
      policy: ellipsoid
      parallel_radius: 5.0
      perpendicular_radius: 4.0
      index1: 10
      index2: 12
      p: 0.2

```

--------------------------------

### Range constraint example

Source: https://faunus.readthedocs.io/en/latest/_docs/energy.html

Constrains a reaction coordinate (end2end of molecule index 0) to a range [0,200]. Stepping outside results in infinite energy and rejection.

```yaml
energy:
    - constrain: {type: molecule, index: 0, property: end2end, range: [0,200]}

```

--------------------------------

### Grand canonical salt particles with rcmc move

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/topology.md.txt

Maintains constant chemical potential of salt ions using a grand canonical salt bath. Atom names must differ from molecule names, and the reaction uses molecules (Na+ and Cl+) not atoms. The rcmc move activates the speciation move, and the same setup works for molecular molecules (atomic: false).

```yaml
atomlist:
  - na: {q: 1.0, ...}  # note that atom names must differ
  - cl: {q: -1.0, ...} # from molecule names
moleculelist:
  - Na+: {atoms: [na], atomic: true, activity: 0.1}
  - Cl-: {atoms: [cl], atomic: true, activity: 0.1}
reactionlist:
  - "= Na+ + Cl+": {} # note: molecules, not atoms
moves:
  - rcmc: {} # activate speciation move
```

--------------------------------

### Build HTML manual with make manual_html

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/install.md.txt

Builds the HTML manual using Pandoc.

```bash
make manual_html
```

--------------------------------

### faunus input from stdin and file I/O

Source: https://faunus.readthedocs.io/en/latest/_docs/running.html

Shows how to run faunus with input from stdin or from a JSON file, with options for file input/output and quiet mode.

```bash
faunus < input.json              # input from stdin
faunus -i in.json -o out.json -q # file input/output and be quiet

```

--------------------------------

### faunus --help

Source: https://faunus.readthedocs.io/en/latest/_docs/running.html

Displays general usage information for the faunus command-line program.

```bash
faunus --help

```

--------------------------------

### Use CMake presets for debugging and building

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/install.md.txt

Configures the project into 'build/debug/' and builds it with the 'faunus-debug' preset.

```bash
cmake --preset debug # populates build/debug/
cmake --build --preset faunus-debug
```

--------------------------------

### Build PDF manual with make manual

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/install.md.txt

Builds the PDF manual. Requires Pandoc, XeLaTeX, and specific fonts (EB Garamond, Garamond Math, Fira Code).

```bash
make manual
```

--------------------------------

### Configure Custom Parameters and Mixing Rules

Source: https://faunus.readthedocs.io/en/latest/_docs/energy.html

Demonstrates how to specify mixing rules, alias parameter names, and override values for specific atom pairs like Na-Cl.

```yaml
- lennardjones:
    mixing: LB
    custom:
      - Na Cl: {eps: 0.2, sigma: 2}
      - K Cl: { ... }
- hertz:
    mixing: LB
    eps: eps_hz
    custom:
      - Na Cl: {eps_hz: 0.2, sigma: 2}
- hardsphere:
    mixing: arithmetic
    sigma: sigma_hs
    custom:
      - Na Cl: {sigma_hs: 2}
```

--------------------------------

### Python interface help

Source: https://faunus.readthedocs.io/en/latest/_docs/running.html

Imports the pyfaunus module and displays its help.

```python
import pyfaunus
help(pyfaunus)

```

--------------------------------

### Compile Faunus from source with CMake

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/install.md.txt

Builds the faunus executable and usage tips. Requires CMake 3.24+, a C++20 compiler, and Python 3.7+ with jinja2 and ruamel.yaml or yaml.

```bash
cd faunus
cmake . [OPTIONS]
make faunus -j
make usagetips # requires `pandoc`, `pypandoc`, `BeautifulSoup4`
```

--------------------------------

### Populate template with Python

Source: https://faunus.readthedocs.io/en/latest/_docs/running.html

Python script using Jinja2 to render the template with specific values for length and radius.

```python
from jinja2 import Template
with open('template.yml') as f:
    output = Template(f.read()).render(
            length = 200,
            radius = 50 )
    print(output)

```

--------------------------------

### Run Gibbs Ensemble with Identical Input

Source: https://faunus.readthedocs.io/en/latest/_docs/moves.html

Executes a Faunus simulation in Gibbs ensemble mode using two MPI processes with a single shared input file.

```bash
mpirun -np 2 faunus --nopfx --input input.json
```

--------------------------------

### Populate YAML template with Python

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/running.md.txt

Uses a YAML template file and Jinja2 to generate input files for parameter scans.

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

```python
from jinja2 import Template
with open('template.yml') as f:
    output = Template(f.read()).render(
            length = 200,
            radius = 50 )
    print(output)
```

--------------------------------

### Configure Langevin dynamics move

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/langevin.md.txt

Add the langevin_dynamics move to the moves section of your configuration file. Specify the number of steps and the integrator settings including time_step and friction.

```yaml
moves:
    - langevin_dynamics:
        nsteps: 25
        integrator: {time_step: 0.005, friction: 5}
    - ...
```

--------------------------------

### Configure Ashbaugh-Hatch with Parameter Aliasing

Source: https://faunus.readthedocs.io/en/latest/_docs/energy.html

Shows how to alias the lambda parameter and define custom pair values for the Ashbaugh-Hatch potential.

```yaml
- ashbaugh-hatch:
    mixing: LB
    lambda: hydrophobicity  # use 'hydrophobicity' from atomlist instead of 'lambda'
    custom:
      - Na Cl: {eps: 0.5, sigma: 3.0, lambda: 0.8}
```

--------------------------------

### Calculate Cluster Size Distribution from Market File

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/analysis.md.txt

Uses gzip to open a distance matrix file, performs hierarchical clustering with single linkage, and prints the sorted distribution of cluster sizes.

```python
with gzip.open('distances.mtx.gz', 'rt') as f:
    for matrix in iterateMarketFile(f):
        Z = linkage(squareform(matrix), 'single')
        cluster = fcluster(Z, 10.0, criterion='distance') # threshold = 10 Å
        _, counts = np.unique(cluster, return_counts=True)
        print(np.sort(counts)) # cluster size distribution
```

--------------------------------

### Select compilers and Python for CMake

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/install.md.txt

Sets CC and CXX environment variables and specifies the Python executable for CMake.

```bash
export CC=/opt/bin/clang
export CXX=/opt/bin/clang++
cmake -DPython_EXECUTABLE=/opt/bin/python3 .
```

--------------------------------

### Load VMD with Charge-Radius Trajectory Script

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/analysis.md.txt

Use this command to launch VMD with the charge-radius trajectory helper script. The script should be sourced after loading the trajectory or invoked at launch.

```bash
vmd confout.pqr traj.xtc -e scripts/vmd-qrtraj.tcl
```

--------------------------------

### Configure angular_scan analysis with zrange and angular_resolution

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/topology.md.txt

Configures the angular_scan analysis in the preface section. Requires exactly two molecules (indices [0,1]) and a zrange with min, max, and step in Å. The angular_resolution is in radians, max_energy is optional in kJ/mol, and the poses file can be large so gz compression is recommended. The initial reference structures are saved as two .xyz files, and OpenMP compilation is recommended for performance.

```yaml
preface:
    - angular_scan:
        indices: [0, 1]           # select exactly two molecules
        zrange: [40.0, 60.0, 4.0] # mass center z separation as [min, max), step (Å)
        angular_resolution: 0.5   # radians
        max_energy: 50.0          # kJ/mol (optional)
        file: poses.dat.gz        # Can be large; gz compression recommended
        traj: poses.xtc           # save poses as trajectory (optional)
```

--------------------------------

### Run Faunus with YAML input via yason.py

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/running.md.txt

Uses the yason.py script to pipe YAML formatted input into faunus.

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

--------------------------------

### Open Faunus root in Visual Studio Code for Dev Containers

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/install.md.txt

Opens the Faunus repository in Visual Studio Code to set up a Docker-based development environment; you will be prompted to open in a devcontainer.

```bash
cd faunus
code .
```

--------------------------------

### Run Faunus simulation with yason.py and faunus

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/docs.md.txt

Converts a YAML input file to JSON and runs the Faunus simulation, producing an output file `out.json` with move statistics and system properties.

```bash
yason.py minimal.yml | faunus
```

--------------------------------

### Read JSON output in Python

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/running.md.txt

Demonstrates reading and accessing data from a JSON output file using 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
```

--------------------------------

### Run Faunus with MPI

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/running.md.txt

Spawns multiple processes using MPI for parallel tasks.

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

--------------------------------

### Python Script to Load and Cluster Sparse Matrices

Source: https://faunus.readthedocs.io/en/latest/_docs/analysis.html

Python script that reads a gzipped Matrix Market file, iterates over frames, performs hierarchical clustering using scipy, and prints cluster size distribution.

```python
from itertools import groupby
import gzip, numpy as np
from scipy.io import mmread
from io import StringIO
from scipy.cluster.hierarchy import linkage, fcluster
from scipy.spatial.distance import squareform

def iterateMarketFile(file_like):
    ''' generator expression for iterating over Matrix Market file '''
    return (mmread(StringIO(''.join(lines))).todense() for frame, lines in
            groupby(file_like, lambda line: line != '\n') if frame)

with gzip.open('distances.mtx.gz', 'rt') as f:
    for matrix in iterateMarketFile(f):
        Z = linkage(squareform(matrix), 'single')
        cluster = fcluster(Z, 10.0, criterion='distance') # threshold = 10 Å
        _, counts = np.unique(cluster, return_counts=True)
        print(np.sort(counts)) # cluster size distribution

```

--------------------------------

### Configure insertmolecules

Source: https://faunus.readthedocs.io/en/latest/_docs/topology.html

Defines the initial composition of the simulation cell, specifying molecule types, quantities, and activity status.

```yaml
insertmolecules:
  - salt:  { molarity: 0.1 }
  - water: { N: 256, inactive: 2 }
```

--------------------------------

### MPI with same input for all processes

Source: https://faunus.readthedocs.io/en/latest/_docs/running.html

Runs faunus with two MPI processes using the same input file, either with --nopfx or via stdin.

```bash
mpirun -np 2 ./faunus --nopfx --input in.json
mpirun -np 2 --stdin all ./faunus < in.json

```

--------------------------------

### Configure mass center cutoffs

Source: https://faunus.readthedocs.io/en/latest/_docs/energy.html

Sets up mass center cutoffs between molecular groups to improve efficiency by skipping pair-interactions.

```yaml
- nonbonded:
    cutoff_g2g:
      default: 40.0
      protein polymer: 20.0
```

--------------------------------

### Join Reaction Coordinate Files with Python

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/analysis.md.txt

Calculates the average angle as a function of the mass center coordinate z by joining two data files.

```python
import numpy as np
from scipy.stats import binned_statistic

def joinRC(filename1, filename2, bins):
    x = np.loadtxt(filename1, usecols=[1])
    y = np.loadtxt(filename2, usecols=[1])
    means, edges, bins = binned_statistic(x, y, 'mean', bins)
    return (edges[:-1] + edges[1:]) / 2, means

cmz, angle = joinRC('cmz.dat.gz', 'angle.dat.gz', 100)
np.diff(cmz) # --> cmz resolution; control w. `bins`
```

--------------------------------

### Define Bonded Interactions in Topology and Energy

Source: https://faunus.readthedocs.io/en/latest/_docs/energy.html

Shows how to add intra-molecular bonds within a molecule definition and inter-molecular bonds in the energy section.

```yaml
moleculelist:
    - water: # TIP3P
        structure: "water.xyz"
        bondlist: # index relative to molecule
            - harmonic: { index: [0,1], k: 5024, req: 0.9572 }
            - harmonic: { index: [0,2], k: 5024, req: 0.9572 }
            - harmonic_torsion: { index: [1,0,2], k: 628, aeq: 104.52 }
energy:
    - bonded:
        bondlist: # absolute index; can be between molecules
           - harmonic: { index: [56,921], k: 10, req: 15 }
```

--------------------------------

### Load and Iterate Matrix Market Files in Python

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/analysis.md.txt

A generator function to iterate over a Matrix Market file, useful for processing streamed sparse matrices for clustering analysis.

```python
from itertools import groupby
import gzip, numpy as np
from scipy.io import mmread
from io import StringIO
from scipy.cluster.hierarchy import linkage, fcluster
from scipy.spatial.distance import squareform

def iterateMarketFile(file_like):
    ''' generator expression for iterating over Matrix Market file '''
    return (mmread(StringIO(''.join(lines))).todense() for frame, lines in
            groupby(file_like, lambda line: line != '\n') if frame)
```

--------------------------------

### yason.py --color out.json

Source: https://faunus.readthedocs.io/en/latest/_docs/running.html

Converts JSON output to syntax highlighted YAML for better readability.

```bash
yason.py --color out.json

```

--------------------------------

### Jinja2 template for parameter scan

Source: https://faunus.readthedocs.io/en/latest/_docs/running.html

Template file for generating multiple input files with variable length and radius, populated using Python.

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

```

--------------------------------

### Update Faunus with Conda

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/install.md.txt

Shows how to check the current version, search for new revisions, and upgrade the faunus package.

```bash
faunus --version      # show version string
conda search faunus   # show (new) revisions
conda upgrade faunus
```

--------------------------------

### Reset build system

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/install.md.txt

Cleans the build artifacts and cached CMake files to reset the build configuration. Useful when changing compilers or troubleshooting CMake configuration issues.

```bash
make clean
rm -fR CMakeCache.txt CMakeFiles _deps
```

--------------------------------

### OpenMP parallel run

Source: https://faunus.readthedocs.io/en/latest/_docs/running.html

Sets the number of OpenMP threads to 4 and runs faunus with input from in.json.

```bash
export OMP_NUM_THREADS=4
faunus -i in.json

```

--------------------------------

### Generate compile_commands.json with CMake preset

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/install.md.txt

Generates the 'build/debug' build directory that clangd uses to find 'compile_commands.json'.

```bash
cmake . --preset debug
```

--------------------------------

### yason.py YAML input

Source: https://faunus.readthedocs.io/en/latest/_docs/running.html

Passes YAML formatted input to faunus via the yason.py helper script.

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

```

--------------------------------

### YAML input format

Source: https://faunus.readthedocs.io/en/latest/_docs/running.html

YAML equivalent of the JSON input, converted via yason.py, which is less verbose and used throughout the documentation.

```yaml
atomlist:
    - Na+: { q: 1.0, mw: 22.99 }

```

--------------------------------

### Alias Docker-side faunus command

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/install.md.txt

Creates an alias to run faunus inside the Docker container from the host, and pipes input to it.

```bash
alias faunus='docker exec --interactive -u 1000 faunuslab faunus'
faunus < input.json # piping input to docker
```

--------------------------------

### Atomlist: inline atom definitions and external JSON

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/topology.md.txt

Defines atoms in the atomlist. Each entry can be an inline atom definition or a filename (`.json`) to load an external atom list; atoms are loaded in order and the latest entry for a repeated name is used.

```yaml
atomlist:
  - Na: {q:  1.0, sigma: 4, eps: 0.05, dp: 0.4}
  - Ow: {q: -0.8476, eps: 0.65, sigma: 3.165, mw: 16}
  - my-external-atomlist.json
  - ...
```

--------------------------------

### Redirect stderr to log file

Source: https://faunus.readthedocs.io/en/latest/_docs/running.html

Runs faunus with verbosity 5 and appends standard error output to error.log.

```bash
faunus -v 5 -i in.json 2>> error.log

```

--------------------------------

### Global properties: temperature, geometry, mcloop, random

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/topology.md.txt

Global properties block that must be placed outermost in the input file. Sets temperature, cuboid geometry with length 40 in each dimension, macro/micro MC loop counts (total steps = macro × micro), and a fixed random seed (default) or hardware-based non-deterministic seed.

```yaml
temperature: 298.15  # system temperature (K)
geometry:
  type: cuboid       # Cuboidal simulation container
  length: [40,40,40] # cuboid dimensions (array or number)
mcloop:              # number of MC steps (macro × micro)
  macro: 5           # Number of outer MC steps
  micro: 100         # Number of inner MC steps; total = 5 × 100 = 500
random:              # seed for pseudo random number generator
  seed: fixed        # "fixed" (default) or "hardware" (non-deterministic)
```

--------------------------------

### Run Faunus with OpenMP threads

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/running.md.txt

Configures the number of OpenMP threads for parallel execution.

```bash
export OMP_NUM_THREADS=4
faunus -i in.json
```

--------------------------------

### Configure Gibbs Ensemble Moves

Source: https://faunus.readthedocs.io/en/latest/_docs/moves.html

Defines the molecule exchange and volume exchange moves for a Gibbs ensemble simulation. Requires reserving inactive particles to accommodate all system particles.

```yaml
insertmolecule:
  - A: 100, inactive: 50} # note inactive species
  - B: 100, inactive: 50}
moves:
  - gibbs_volume: { dV: 1.0, molecules: ["A", "B"] } # exchange volume
  - gibbs_matter: { molecule: "A" } # exchange A molecules
  - gibbs_matter: { molecule: "B" } # exchange B molecules
```

--------------------------------

### YAML: Swapping between molecular conformations

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/topology.md.txt

Defines two molecular conformations (A and B) and a reaction to swap between them with a given equilibrium constant (lnK: 0.69, K=2). When swapping, the mass center position and orientation are randomly generated.

```yaml
moleculelist:
  - A: {structure: "conformationA.xyz", ...}
  - B: {structure: "conformationB.xyz", ...}
reactionlist:
  - "A = B": {lnK: 0.69} # K=2, "B" twice as likely as "A"

```

--------------------------------

### Convert JSON output to YAML

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/running.md.txt

Converts JSON output to syntax-highlighted YAML for better readability.

```bash
yason.py --color out.json
```

--------------------------------

### JSON input format

Source: https://faunus.readthedocs.io/en/latest/_docs/running.html

Native JSON input format for faunus, showing an atomlist with a sodium ion definition.

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

```

--------------------------------

### Fix Python library linking on macOS with otool and install_name_tool

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/install.md.txt

Probes the linked Python library in pyfaunus.so and changes its path to the conda one.

```bash
otool -L pyfaunus.so
install_name_tool -change libpython3.8.dylib \
  $HOME/miniconda/lib/libpython3.8.dylib pyfaunus.so
```

--------------------------------

### Visualize Patchy Sphero-Cylinder Trajectory

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/analysis.md.txt

Convert the trajectory data using the provided Python 2 script and then visualize the output in VMD.

```bash
python2 psc2vmd.py -i tracjectory.dat -o movie.pdb --psf movie.psf
vmd -e vmd.script
```

--------------------------------

### Redirect diagnostic output to log file

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/running.md.txt

Runs faunus with high verbosity and redirects standard error to a log file.

```bash
faunus -v 5 -i in.json 2>> error.log
```

--------------------------------

### MPI parallel run with two processes

Source: https://faunus.readthedocs.io/en/latest/_docs/running.html

Runs faunus with two MPI processes, reading input from mpi0.in.json and mpi1.in.json.

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

```

--------------------------------

### Acid-base titration coupled with grand canonical salt

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/topology.md.txt

Couples acid-base titration with a grand canonical salt bath to respect electroneutrality. The reactions include explicit salt ions (Cl- and Na+) to maintain charge balance, and the final reaction provides the grand canonical salt reservoir. The pK values are set to 4.8.

```yaml
atomlist:
  - H+: {implicit: true, activity: 0.00001} # pH 5
  - COO-: {q: -1.0, ...}
  - COOH: {q: 0.0, ...}
  - na: {q: 1.0, ...}
  - cl: {q: -1.0, ...}
moleculelist:
  - Na+: {atoms: [na], atomic: true, activity: 0.1}
  - Cl-: {atoms: [cl], atomic: true, activity: 0.1}
reactionlist:
  - "COOH + Cl- = COO- + H+": {pK: 4.8} # electroneutral!
  - "COOH = Na+ + COO- + H+": {pK: 4.8} # electroneutral!
  - "= Na+ + Cl-": {} # grand canonical salt
```

--------------------------------

### Run Faunus with increased verbosity

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/running.md.txt

Sets the verbosity level for debugging diagnostic messages.

```bash
faunus --verbosity 5 --input in.json
```

--------------------------------

### Specify Debye screening length and molarity

Source: https://faunus.readthedocs.io/en/latest/_docs/energy.html

Define background electrolyte screening using debyelength or molarity. The system automatically deduces salt stoichiometry based on provided valencies.

```yaml
    debyelength: 30.0, epsr: 79.8       # assuming 1:1 salt, e.g. NaCl
    molarity: 0.02                      # 0.02 M 1:1 salt, e.g. NaCl
    molarity: 0.01, valencies: [2,3,-2] # 0.01 M Ca₂Al₂(SO₄)₅
```

--------------------------------

### Activate parallel nonbonded summation

Source: https://faunus.readthedocs.io/en/latest/_docs/energy.html

Configure the nonbonded summation policy to use parallel processing. The policy can be set to 'parallel', 'openmp', or 'serial'.

```yaml
- nonbonded:
    summation_policy: parallel
    ...
```

--------------------------------

### Constrain system box side length with a harmonic potential

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/energy.md.txt

Constrains a system property using a harmonic potential defined by a required value (req) and a force constant (k). This configuration ignores the range parameter.

```yaml
energy:
    - constrain: {type: system, property: Lx, harmonic: {req: 100.0, k: 500.0}}
```

--------------------------------

### Acid-base titration with implicit protons (pK 4.8)

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/topology.md.txt

Models acid-base titration with implicit protons. The H+ atom is implicit with activity 10^-pH (here pH 5). The pK is set to the pKa, and the reaction violates electroneutrality, so it should only be used with Hamiltonians that allow this, such as salt-screened Yukawa interactions.

```yaml
atomlist:
  - H+: {implicit: true, activity: 0.00001} # pH 5
  - COO-: {q: -1.0, ...}
  - COOH: {q: 0.0, ...}
reactionlist:
  - "COOH = COO- + H+": {pK: 4.8} # not electroneutral!
```

--------------------------------

### Reaction Coordinate Configuration for Center of Mass

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/analysis.md.txt

Configures the reaction coordinate to track the center of mass z-coordinate of a molecule.

```yaml
- reactioncoordinate:
    {nstep: 100, file: cmz.dat.gz, type: molecule, index: 0, property: com_z}
```

--------------------------------

### Reaction Coordinate Configuration for Molecular Angle

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/analysis.md.txt

Configures the reaction coordinate to track the angle between the principal molecular axis and the xy-plane.

```yaml
- reactioncoordinate:
    {nstep: 100, file: angle.dat.gz, type: molecule, index: 0, property: angle, dir: [0,0,1]}
```

--------------------------------

### Set verbosity level

Source: https://faunus.readthedocs.io/en/latest/_docs/running.html

Increases verbosity to level 5 to show debug information when debugging.

```bash
faunus --verbosity 5 --input in.json

```

--------------------------------

### Patchy sphero-cylinders: psc atom and coswca-psc energy

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/topology.md.txt

Activates patchy sphero-cylinders via the `psc` keyword. Uses a cosine attraction for patch-patch interactions mixed with Weeks-Chandler-Andersen for excluded volume; the `coswca-psc` pair potential is configured with LB mixing for both patch and cylinder interactions.

```yaml
atomlist:
  - mycigar:
      psc: {type: capped, length: 40, patch_angle: 80}
      eps: 2.4  # used for both wca and the cosine attraction
      sigma: 10 # cylinder and cap radius
      rc: 11.2  # cosine attraction switch distance
      wc: 6.0   # cosine attraction switch width

energy:
  - nonbonded:
      default:
        - coswca-psc:          # cosine attraction + WCA pair potential
            cos2: {mixing: LB} # used for interactions with patch
            wca: {mixing: LB}  # used for interactions with cylinder
```

--------------------------------

### Define custom-groupgroup potential

Source: https://faunus.readthedocs.io/en/latest/_docs/energy.html

Configures a custom interaction between two molecule types using the ExprTk library. The function subtracts a Yukawa potential, which can be used for simulation biasing.

```yaml
custom-groupgroup:
    name1: charged_colloid
    name2: charged_colloid
    constants: { bjerrum_length: 7.1, debye_length: 50 }
    function: >
        -bjerrum_length * Z1 * Z2 / R * exp(-R / debye_length)
```

--------------------------------

### Constrain molecule end-to-end distance with a range

Source: https://faunus.readthedocs.io/en/latest/_sources/_docs/energy.md.txt

Constrains a molecule's end-to-end distance within a specified range. Stepping outside this range results in infinite energy and rejection.

```yaml
energy:
    - constrain: {type: molecule, index: 0, property: end2end, range: [0,200]}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.