CAMPARI Keywords

---

Full Keywords Index:

1. Parameter File:
2. Random Number Generator:
3. Simulation Setup:
4. Box Settings:
5. Integrator Controls (MD/BD/LD/Minimization):
6. Move Set Controls (MC):
7. Files and Directories:
8. Structure Input and Manipulation:
9. Energy Terms:
10. Cutoff Settings:
11. Parallel Settings (MPI and OpenMP):
12. Output and Analysis:
13. NetCDF Data Mining:

Preamble

---

The overall setup of simulations becomes more and more involved and complicated with increasing numbers of options offered by simulation software, and CAMPARI is no exception here. Not all settings are relevant in all circumstances (in fact, often very few are), and a complete understanding of all keywords is clearly not required to use subsets of CAMPARI's functionality. Since version 4, CAMPARI ships with an interactive tool to create key-file templates. This tool, written in Ruby, is not complete but will be able to create a solid starting point for an actual key-file for a simulation or analysis task. Importantly, it automatically embeds comments into the key-file, which serve a twofold purpose: first, as a miniature documentation for active keywords and, second, as a list of associated keywords which are left at default values (are commented out).
Users should keep the following points in mind when writing or editing key-files:

• Most keywords have default choices. In case of doubt, check parsekey.f90 to locate the variable associated with the selection, and then initial.f90, allocate.f90, and sometimes other files for default assignments.
• Not all keywords can be connected and arranged such that they group nicely. The documentation here groups keywords into a small number of sections, some of which end up being very large. This has both advantages and disadvantages.
• For navigation, it is highly recommended to a) search for terms within the page with the help of the browser (all keywords are described within a single html-page), b) follow the links that are provided everywhere.
• If an option is unclear, but easily testable, it is probably fastest to just try it out. If it is difficult to test, post a question on the SF forums. Every successful execution of CAMPARI prints a summary of the attempted calculation to log-output once the initialization and setup phase is complete.
• The understanding of many implemented, standard methodologies requires the corresponding literature. This is why a bibliography is provided.
• The fastest way to learn how to run basic simulations or perform trajectory analyses is to consult the various tutorials. Tutorials offer the chance to group information in a more natural workflow compared to the documentation here. They cannot explain all options in detail, though, and it is crucial to follow the links within the tutorial pages that point back to this and the other documentation pages.

A lot of very important and fundamental keywords are grouped in the section on simulation setup. A few other keywords in other sections, which can be very important and serve as hubs for finding associated keywords, but which are not necessarily quick to find are CARTINT (choice of degrees of freedom), SEQFILE (definition of system), RANDOMIZE (initial structure generation), INTERMODEL, LREL_MC, LREL_MD (all related to energetics), or REMC (replica exchange).

Notes on Nomenclature and File Parsing:

All keywords used by CAMPARI are named FMCSC_* where the different possible strings for "*" are explained below. This means that in your key-file the correct keyword to use to specify the simulation temperature is FMCSC_TEMP and not just "TEMP". There are only two exceptions to this, viz. keywords PARAMETERS and RANDOMSEED. This has purely historical reasons (as does the ad libitum acronym "FMCSC").
The beginning of log output will print some information regarding the parsing of information in the key-file. Superfluous lines should be masked as comments using the hash character ("#"). Lines that are neither empty nor comments will be pointed out unless they correspond to the two exceptional keywords just mentioned or unless they begin with the canonical prefix "FMCSC_". The keyword parser operates hierarchically meaning that some legitimate keywords will not be processed because the required base functionality has not been enabled (e.g., thermostat settings are not processed unless a gradient-based method is in use). This is done mostly to avoid needless warnings from popping up. All apparent keywords that have not been processed will be reported by the parser. However, the hierarchical dependence is not enforced stringently, which means that a keyword not reported in this list but appearing in the key-file does not automatically control a setting relevant to the attempted calculation. It is important to realize that the list of unprocessed keywords can also include misspelled ones. To make the detection of typos easier, it is recommended to comment or remove unused keywords from the key-file.
Finally, most read operations of simulation settings are prone to data type mismatch errors. Supplying a character value to a numerical setting will trigger a Fortran I/O error. The error message is usually informative yet the relevant position in the key-file is not reported. I/O in general (also for input files) may be made less error-sensitive in the future, but for now we apologize for this limitation.

Parameter File Keywords:

---

PARAMETERS

This keyword allows the user to provide the location and name of the parameter file to be used for the simulation. The different files offered by default (shipped with CAMPARI) are listed below:

Custom Parameter Sets:  

The parameter sets fmsmc*.prm are outdated and should be used with utmost caution. They contain no bonded parameters except dummy declarations and are therefore only suitable for torsional space calculations.
In general, the Lennard-Jones parameters for ions in the files starting with abs3.1 and abs3.2 require a cautionary note as they simply are those from Aqvist's work. They have not been specifically parameterized to work together with the ABSINTH continuum solvation model in case a full Hamiltonian is used (they merely have been shown to reside on the "safe" side). This is a matter of ongoing development. It may be be more appropriate to use parameters for ions that feature harder cores and better congruence between σ_ii parameters and actual contact distances such as those in the files starting with abs3.3, abs3.4, or abs4. Similarly, the original offsets on the free energies of solvation for charge moieties on polymers as found in the files starting with 3.2 are very large (-30kcal/mol) and generally disallow salt bridge formation. The parameter revisions in the later models (abs3.4, abs4.2) have alleviated this somewhat by reducing the offsets to -15kcal/mol.

fmsmc.prm:

fmsmc_exp.prm:

fmsmc_exp3.prm:

fmsmc_exp2.prm:

abs3.2_opls.prm:

abs3.1_opls.prm:

abs4.2_opls.prm:

abs4.1_opls.prm:

abs3.2_charmm.prm:

abs3.1_charmm.prm:

abs3.2_charmm36.prm:

abs3.1_charmm36.prm:

abs4.2_charmm36.prm:

abs4.1_charmm36.prm:

abs3.3_charmm36.prm:

abs3.4_charmm36.prm:

abs3.2_a94.prm:

abs3.1_a94.prm:

abs3.2_a99.prm, abs3.1_a99.prm, abs3.2_a03.prm, abs3.1_a03.prm:

abs3.2_GR53a6.prm:

abs3.1_GR53a6.prm:

abs3.2_GR53a5.prm and abs3.1_GR53a5.prm:

In order to employ these parameters files in a small molecule screen, it is necessary to have a map from the atom types in the files to the Sybyl atom types used in standard mol2-files. This map can be determined automatically, but the guessing procedure crude. A better approach is to provide this map manually using keyword SYBYLLJMAP. The input file documentation explains this in detail, but, for convenience, at map suitable for 4.2 parameters is provided with CAMPARI (as abs4.2.ljmap in the "params" folder).
Some recommended settings controlling energy terms and the interaction model suitable for using any of these custom parameter files are listed below. Note that these are also the settings required to achieve an exact match with the original ABSINTH reference. Note as well that this implies several defaults that are not listed explicitly.

FMCSC_UAMODEL 0
FMCSC_INTERMODEL 1
FMCSC_ELECMODEL 2
FMCSC_MODE_14 1
FMCSC_FUDGE_EL_14 1.0
FMCSC_FUDGE_ST_14 1.0
FMCSC_EPSRULE 2
FMCSC_SIGRULE 1
FMCSC_SC_BONDED_B 0.0
FMCSC_SC_BONDED_A 0.0
FMCSC_SC_BONDED_T 0.0
FMCSC_SC_BONDED_I 0.0
FMCSC_SC_EXTRA 1.0

We do, however, strongly recommend replacing FMCSC_SC_EXTRA being unity with FMCSC_SC_BONDED_T set to unity since the above files will typically contain (unless otherwise noted) the required and "native" bonded potentials for each parent force field. This ensures better parameter coherence (the ones used for SC_EXTRA are taken from OPLSAA/L) and - more importantly - control over all torsional potentials (and bonded potentials in general) through the parameter file. If the system to be sampled contains proline residues, other flexible rings, or chemical crosslinks, it will also be necessary to set FMCSC_SC_BONDED_A, FMCSC_SC_BONDED_B, and FMCSC_SC_BONDED_I to 1.0 to avoid obtaining nonsensical results. Depending on the force field, even a simple extension like allowing the C-N dihedral angle in primary amides to be sampled (see OTHERFREQ and TMD_UNKMODE) might require improper dihedral angle potentials. Thus, it is recommended practice to always enable all bonded terms except CMAP corrections even if the enabled potentials end up being largely redundant. An updated set of choices compatible with the above parameter files is:

FMCSC_UAMODEL 0
FMCSC_INTERMODEL 1
FMCSC_ELECMODEL 3
FMCSC_MODE_14 1
FMCSC_FUDGE_EL_14 1.0
FMCSC_FUDGE_ST_14 1.0
FMCSC_EPSRULE 2
FMCSC_SIGRULE 1
FMCSC_SC_BONDED_B 1.0
FMCSC_SC_BONDED_A 1.0
FMCSC_SC_BONDED_T 1.0
FMCSC_SC_BONDED_I 1.0
FMCSC_IMPROPER_CONV 2
FMCSC_SC_EXTRA 0.0

Note that the parameters specific to the solvation model are discussed elsewhere.



Reference Parameter Sets:  

The parameter sets below attempt to be as complete as possible for the biopolymer types supported by CAMPARI. In general, support for small molecules (which often use derived parameters) will often be limited (but can easily be added by the user). In addition, rare and generally poorly parameterized biopolymer constructs (such as zwitterionic amino acids or free nucleosides) may have incomplete parameter portings in particular of bonded parameters. If a perfect match of a certain parameter set paradigm cannot be achieved (against the reference implementation), this is stated explicitly.

oplsaal.prm (reference implementation: GROMACS 4.5.2)
GROM53a6.prm, GROM53a5.prm (reference implementation: GROMACS 4.0.5)
amber94.prm, amber99.prm, amber03.prm (reference implementation: AMBER port in GROMACS 4.5.2)
charmm.prm (reference implementations: CHARMM35b2 and CHARMM38b1)
charmm36.prm (reference implementations: CHARMM38b1 and CHARMM39b1)
In order to create a new parameter file, it is advisable to start with "template.prm". For details on the paradigms underlying the construction of a parameter file consult the detailed documentation on this topic.

Random Number Generator Keywords:

---

(back to top)

RANDOMSEED

This keyword allows the user to provide a specific seed for the PRNG. This is usually relevant in two contexts:

1. Reproducibility:
   Eliminate mismatches between different versions of the program (for example) by doing the stringent test that the results must be exactly the same if the PRNG is seeded with the same seed. Such tests may occasionally be hampered by a lack of precision in any input files and in particular by different compiler/architecture optimization levels.
   
2. Timing:
   Eliminate identical calculations if jobs are submitted simultaneously. Normally the PRNG uses a seed derived from from system time, which can be identical if jobs are submitted exactly in parallel. Avoiding this behavior by specifying different values for RANDOMSEED is only adequate if the jobs are indeed submitted as individual, serial jobs. Conversely, in intrinsically parallel applications (MPI), CAMPARI uses the node number to vary the seed across different nodes unless RANDOMSEED is specified. This means that a provided value for RANDOMSEED will homogenize the PRNG across all replicas which is almost always undesirable.

(references)

Simulation Setup:

---

(back to top)

UAMODEL

This keyword is a simple but very important switch. It allows the user to control whether non-polar hydrogens are going to be part of the system's topology or not. In particular in earlier simulation work, it was a common and convenient trick to improve simulation efficiency by uniting all atoms of a methyl or methylene group into a single, coarse-grained "united atom". Different force fields used or use different varieties of this trick. In the GROMOS line of force fields, for instance, all aliphatic hydrogen atoms are merged into the carbon atoms they are bonded to. Conversely, the CHARMM19 protein force field in addition eliminates non-polar hydrogens bound to sp²-hybridized carbon atoms in aromatic rings.
Unlike other simulation software, CAMPARI maintains a complete internal "knowledge" of biomolecular topology of those systems it allows the user to build from scratch. Therefore, choosing between all- or united-atom models is not simply a matter of parameter files (although it is possible to create inefficient united-atom variants of force fields by disabling all interaction parameters pertaining to the required hydrogens). Instead, the software itself requires knowledge of this choice.
Choices are:

0. Use an all-atom model for those molecules represented explicitly.
1. Use a united-atom model according to GROMOS convention, i.e., all aliphatic hydrogen atoms are merged into the carbon atoms they are linked to (this does include terminal aldehyde hydrogen atoms).
2. Use a united-atom model according to CHARMM19 convention, i.e., all aliphatic and all aromatic hydrogens bound to carbon atoms are merged into the latter.

Currently, the only natively supported united-atom force field in CAMPARI is GROMOS53a5/6 (see above). One technical caveat is that using the latter two options may require setting UNSAFE to 1. This is because the atom type parsing reads in atom valences which are altered and - more importantly - may vary between atoms that for simplicity were assigned the same type.
Outside of simulations using the GROMOS force field, this keyword is most useful when using CAMPARI to analyze trajectory data generated by other software using such a united-atom force field. Such a run would not tolerate atom number mismatches between the internal representation of the system and what is found in the binary trajectory files (mismatches are acceptable only if the input format is pdb → see below). Note that this keyword has no impact on systems involving residues not supported natively by CAMPARI (→ sequence input and PDB input).

PDBANALYZE

This keyword is a simple but very important logical. It specifies whether the proposed simulation is a trajectory analysis run: in these, a pdb- (or xtc-, dcd-, NetCDF)-trajectory is read from file and analyzed with CAMPARI's internal analysis routines. The desired format is chosen with keyword PDB_FORMAT. All outputs and parameters are completely analogous to normal calculations. Essentially, the snapshot read-in replaces the sampling step. This means that low analysis frequencies will be desirable, since usually the number of snapshots will be relatively small compared to the number of simulation steps in a typical simulation. Note that - in particular for large systems (> 10⁴ atoms) - the analysis run may be slowed down by:

1. Certain time-consuming analyses scale poorly with the number of atoms (solution structure analyses, see for example PCCALC or CLUSTERCALC).
2. At each step, the global system energy is calculated using - depending on the setting for DYNAMICS - either CAMPARI's energy (MC) or force (MD/LD) routines and making little to no simplifying assumptions. To ensure decent speed, this may require setting the system Hamiltonian to zero (see below) and/or using an efficient cutoff / neighbor-list routine (see CUTOFFMODE).
3. Very large files in particular in pdb-format may cause memory shortages which slow down the machine entirely. In general binary trajectory files in conjunction with an optional template file are the preferred and much faster way of performing analysis runs.

Note that it is important in analysis runs to set NRSTEPS and EQUIL to the required values (the number of steps generally becomes the number of snapshots in the trajectory file) and that a fair amount of CAMPARI's simulation options are (naturally) not supported in such a run. Some sanity checks specific to pdb trajectories can be disabled with the help of keyword UNSAFE. The analysis can also be restricted to a subset of simulation snapshots by using a frames file, which can carry analysis weights per snapshot. This is commonly necessary when trying to reweight simulation data to different conditions or Hamiltonians. Frames files can also be used to extract, reorder, or duplicate parts of trajectories. Both weighted analyses and analyses performed on arbitrary subsets of the input data carry some intricacies with the built-in analysis routines, which are described elsewhere.
When using an MPI executable of CAMPARI in parallel, it is also possible to perform trajectory analysis across many processors. This uses the replica exchange setup and is described in detail elsewhere. The four primary applications are simultaneous analyses of several trajectories, the unscrambling of replica exchange trajectories that are normally output continuously for a given condition, the post facto computation of energetic overlap distributions, and the evaluation of the PIGS heuristic for analysis purposes. Specific analysis routines (such as DSSP analysis may be restricted to specific types of residues, and this may limit the utility of these routines for entities that are not natively supported by CAMPARI (see sequence input). In general, analysis runs on systems featuring unsupported residues should be relatively straightforward. This is true at least as long no energetic analyses are required (which naturally entails the complex issue of parameterization).
Analysis runs can also utilize the shared memory (OpenMP) parallelization of CAMPARI. As is described elsewhere, this decomposes the workload for many time-intensive tasks that CAMPARI can perform. For analysis functionalities, the load per step for an individual analysis is often so low that is not effective to let multiple threads operate on it. This is why most simple analysis functions are not parallelized per se but simply performed simultaneously. This is obviously ineffective if only a single such analysis is needed. Currently, the only exceptions are certain analyses related to structural clustering and the calculation of spatial density maps. Important analyses that can be time-consuming but are not parallelized per se are those controlled by CONTACTCALC, DSSPCALC, RHCALC, SAVCALC, and DIFFRCALC. As a general comment, tt should be noted that CAMPARI will always spend some of its execution time dealing with coordinate operations. Depending on the chosen settings, there may also be a large contribution from evaluating energies at every step. While the former is never parallel in analysis runs and constitutes a hidden performance bottleneck (just as file I/O does), the latter takes full advantage of the parallelization offered in regular simulations. These considerations should be kept in mind when deciding whether to use the OpenMP code in an analysis setting. Generally, it will of course be more efficient to parallelize in snapshot space by letting the MPI version operate on separate pieces of a longer trajectory. As is generally the case, the MPI and OpenMP frameworks can also be used simultaneously in analysis runs with the standard hierarchy (each MPI process maintains a separate copy of the system, and the processing of each copy can be sped up by using more than one OpenMP thread per MPI process).

MOL2SCREEN

This simple logical keyword instructs CAMPARI to serialize a given calculation across a changing set of systems. These systems are composed of a fixed part (which can be nil) and an exchangeable part (which must be present). This exchangeable part has to be a single molecule consisting of exactly one residue, which is defined as a placeholder molecule at the end of sequence input (e.g., LIG_N_C). The various molecules substituted for the placeholder molecule are defined in a single input file in Sybyl mol2 format. The data structures are allocated only once, and the maximum number of atoms for any single molecule in the library should be specified by keyword MOL2MAXSIZE. The number of individual calculations performed will be (roughly, see below) equivalent to the number of molecules in the mol2 file.
At the level of an individual calculation, there is little difference to a normal CAMPARI run, and the majority of keywords are understood and processed in exactly the same way. This means that it is possible to run any type of CAMPARI-supported calculation (except trajectory analysis) in an automatic throughput fashion. The differences to normal execution are as follows:

• The placeholder molecule per se is irrelevant, but any feature desired for the molecules in the mol2 file must also be enabled, at least formally, for the placeholder molecule. In some cases, CAMPARI will explicitly recognize that the fact that parameters are missing can be ignored, in other cases it may be necessary to supply a suitable patch to circumvent this issue. A pdb file (or at least template) must be present and specified even when there is no fixed part (receptor). This is despite the fact that absolutely no information regarding the placeholder is extracted from this file (this is a current technical limitation).
• The parameterization of the molecules in the mol2 file happens in different ways, all of which are automatic. For the Coulomb potential and the ABSINTH DMFI, the mol2 file itself is the source of information (currently not documented). For bonded potentials (e.g., bond angle potentials), CAMPARI relies on the input geometry and a chemistry parser that will apply dihedral angle potentials in the spirit of the ABSINTH force field paradigm. The amount of guessing and assigning is controlled by keyword MOL2BONDMODE. Lennard-Jones parameters are guessed based on Sybyl atom types provided on input and the atom types in the parameter file. It is therefore important to use correct values for the nucleus number in the fifth column in the atom type section. The way the CAMPARI atom types are matched to Sybyl types is explained further in the context of keyword SYBYLLJMAP, which provides a facility to override the automatic mapping. Other required parameters for the ABSINTH model and exclusion rules are determined automatically in agreement with keyword settings (e.g., INTERMODEL).
• A general complication is introduced by system subset-specific adjustments, e.g., constraints. The problem is that different molecules in the mol2 file will have different numbers of degrees of freedom, different numbers of atoms, etc, which is why it is not generally feasible to control these things globally. Consequently, the majority of customization apply to the fixed part of the system only, whereas the exchangeable part requires special keywords. Currently, these keywords are MOL2FRZMODE, MOL2BONDMODE, MOL2POLMODE, MOL2CLUMODE, MOL2DRESTMODE, and MOL2EMMODE. Keyword MOL2FOCUS is special in that it controls constraints for the fixed part in response to the reference molecule, which is the first screened molecule and either found in the main input file (as the first molecule) or in a separate input file.
• The reference molecule also allows the definition of a reference substructure to perform a more targeted search for the screened molecules. This means that chemical information can be used to align matching parts of the screened molecules with the reference substructure to enable a anchor- or tether-driven search procedure (see elsewhere and keyword MOL2ASSIMILAR). The alignment happens prior to the actual calculation. Keyword MOL2DRESTMODE is also responsive to this information and usually essential for maintaining the anchoring.
• Many output files will continue to be appended with information from different molecules (step numbers are reset), e.g. ENERGY.dat. The main output file of the screen is a mol2 file itself that has relevant conformers for the variable part of the system possibly in addition to a selected subset of atoms from the fixed part. What types of conformers are written to the output file is controlled by keyword MOL2OUTMODE. They can include the minimum energy and final conformers for each screened molecule, for example. Other conformers can be obtained by enabling structural clustering, which is adjustable for the small molecule screen using keywords MOL2CLUMODE and MOL2THRESH. This option can require a lot of memory if NRSTEPS is large, the set in MOL2AUXINDEX is large, and/or CCOLLECT is small. Note that the base name of the calculation is the user-defined one for this file only. For other output, e.g., trajectory output, individual files may be generated per screened molecule, which is usually undesirable. In particular, keyword MOL2PDBMODE will create PDB output of the final conformations of the entire system for each molecule.
• While resembling a simulation with an unsupported residue in many ways, the setup routines in the small molecule screen will try harder to deal with the input. This implies that atoms are reordered to be able to construct a hierarchical Z matrix and guess dihedral angle degrees of freedom correctly. In addition, the mol2 file provides connectivity information, which is used.
• Most analyses are not supported, a modified version of structural clustering being the exception.

Users should be aware that the total file size written both to log output and to output files can easily become very large in a small molecule screen. The former (log output) can be regulated by keyword MOL2VERBOSE. It is in any case recommended to perform a test run on a small fraction of the intended calculation to obtain an estimate first.
When using the shared memory parallelization of CAMPARI, the enhancements are restricted entirely to the sampling part that is part of CAMPARI's general engine. Conversely, the specific setup routines for the small molecules do not benefit from the shared memory parallelization at all (and this includes calculations of initial energies and forces). Since it is almost always the case that a small molecule screen tests many small molecules, it is consequently recommended to use a single thread per process and to parallelize manually (split the input files) or via the MPI code. A special execution mode for a small molecule screen is a scoring calculation. Here, many setup steps are skipped, there is no sampling, and the threads parallelization never plays a role (in this mode, the number of threads can only be 1).
If CAMPARI was compiled with MPI support (see installation instructions), a small molecule screen has access to two different execution modes. First, each molecule can be operated on redundantly by the chosen number of MPI processes in parallel (keyword MPIAVG is 1). This is useful when the sampling needs to be exhaustive, and it implies that data are pooled for structural clustering. Second, the input file is read by a master process, and the molecules are distributed dynamically to different MPI processes. In this mode (REMC is 1 and MOL2ISSPLIT is 0), the master process is often idle, and it may prove worthwhile to specify a number of replicas as N+1 where N is the formally available number of computing cores to run on. Here, every molecule is worked on by exactly one MPI process, and the results are completely independent. Third, each replica reads separate input files (REMC is 1 and MOL2ISSPLIT is 1). No pooling of results occurs, and no load balancing can be guaranteed. This mode is particularly useful for parallel scoring runs following a parallel screening run of the second type (which produces separate output files). Note that the two main approaches (pooling vs. no pooling) seldom yield equivalent results. If multiple processes operate on the same molecule, there is a putative benefit of different randomized starting positions that is never available in the second approach.

MOL2ISSPLIT

If a small molecule screen was requested, and CAMPARI was compiled with MPI support (see installation instructions), this simple logical keyword (1 means "on") specifies that the name supplied as the main input file is to be interpreted as a base name. CAMPARI will systematically construct names for distinct input files from this base name by separating any possible file system path component and prepending the standard prefix "N_xxx_" where "xxx" is the number of individual replicas (starting with 0 and using left-padding with zeros). Note that this keyword is only relevant in MPI runs where REMC is 1.

MOL2VERBOSE

If a small molecule screen was requested, this keyword controls the amount of information written to log output. A value of 0 suppresses all log information except important warnings. Permissible values range from 0 to 4, and the default is 1. Note that the log output can grow very quickly in such a calculation. This keyword has no impact at all on the dedicated output control keywords MOL2OUTMODE and MOL2PDBMODE.

MOL2FILE

This keyword provides location and name of the main input file for a small molecule screen. CAMPARI expects a Sybyl mol2 file in standard format such as those obtained from public repositories. A file containing 1500 molecules will cause CAMPARI to perform the same calculation on a fixed system plus each of the molecules in this file for a total of 1500 runs. The only exceptions to this are possible in parallel execution modes. If keyword MPIAVG is turned on, the same calculation will be run 1500 times but each run is a parallel run pooling data from multiple replicas. Conversely, if keyword REMC is turned on and keyword MOL2ISSPLIT is false, the 1500 individual calculations will be distributed across multiple replicas. Lastly, if both REMC and MOL2ISSPLIT are turned on, CAMPARI expects separate input files for the different replicas (as it does, e.g., for keyword PDB_MPIMANY).
Additional information encoded and used in the mol2 file are partial charges (if the Coulomb potential is in use) and group assignments for the ABSINTH DMFI, which works in conjunction with a library input file. The group assignments are integer assignments in the substructure column with the integer referring to a specific solvation group in the library file. To be able to distinguish two identical solvation groups within the same molecule, the column with the substructure name should have running integers per molecule for each individual group. See elsewhere for further details.
CAMPARI supports some options in a small molecule screen that derive information on restraints, constraints, and/or alignment from a reference molecule. This reference molecule either has to be the first molecule in this input file, or it can be supplied as a separate file with the help of keyword MOL2_REFMOL. The latter is generally more convenient. Prominent keywords that stand in relation to the information extraction for the reference molecule are MOL2FOCUS, MOL2DRESTMODE, and MOL2ASSIMILAR.

MOL2_REFMOL

This keyword provides location and name of an auxiliary input file in Sybyl mol2 format. It is supposed to contain a single molecule that serves as a reference molecule. If there is a fixed part of the system (receptor), the coordinates of this molecule should correspond to a desired relative orientation (binding pose). Details are provided elsewhere. Prominent keywords that stand in relation to the information extraction for the reference molecule are MOL2FOCUS, MOL2DRESTMODE, and MOL2ASSIMILAR.

MOL2SCOREONLY

If a small molecule screen was requested, this keyword allows selecting a special mode of operation that disables all sampling activities (i.e., dynamics and Monte Carlo propagators). As such, it is somewhat analogous to trajectory analysis mode, which is not independently supported for small molecule screens. In scoring mode, the energy of the system (separated by terms) is evaluated and reported (nonzero terms only). This happens in 3 ways: i) for the actual combination of the fixed part of the system (if any) and each small molecule in exactly the (absolute) conformation it is is found in in the mol2 input file; ii) for the fixed part of the system alone; iii) for the small molecule alone. This corresponds to a simple energy scoring analysis of a binding process of perfectly rigid molecules, and the corresponding difference (complex - fixed part - small molecule) is reported as well. It is generally not useful to enable this option in the absence of a fixed part or for meaningless coordinates of the small molecules. By default, the fixed part will have the same conformation throughout. This behavior can be altered by keyword MOL2_PDB_RELAXED, which allows the specification of a file with an additional conformation of the fixed part assumed to be the correct ligand-free state.
If the mol2 input file contains additional coordinates belonging to the fixed part of the system (see keyword MOL2AUXINPUT), the interpretation is slightly more complicated for more than one molecule. This is because, without specifying an input file for MOL2_PDB_RELAXED, the implied reference state of the receptor changes, which is not generally justifiable (because, physicochemically speaking, the ligand-free state cannot differ for different ligands). Having to recalculate the ligand-free receptor energies also increases the cost of the calculation somewhat.
Because sampling activities are disabled, this mode of operation can speed up the calculation by disabling parts of the initial setup (useful when working with large receptors) and by combining what are essentially 3 separate calculations into (ideally) a single one. It should reproduce the same values as a manual execution of these 3 calculations. Because some terms explicitly couple different molecules (e.g., the DSSP potential), not all energy terms are supported in this mode, and corresponding warnings and errors are produced. The resultant energies imply a complete neglect of entropy except for what may be captured by "effective" energies (e.g., from implicit solvent models). Compared to the physical process of interest, this generally includes conformational entropy differences of both receptor and small molecule as well as entropy differences due to solvent (including other solution species such as ions). The reported energy values also imply that the complex structure is unique, which is often a poor approximation (i.e., the single point value should really be an integral over a small but finite domain). Lastly, the aforementioned assumption of complete rigidity implies that the unbound and bound states of the ligand differ in their intrinsic state (strain), and this energetic contribution cannot be captured either.

MOL2MAXSIZE

If a small molecule screen was requested, this keyword lets the user specify the maximum size (in number of atoms, including dummy particles) for an individual molecule to expect in the screened library. This is required because some arrays are allocated only once at the beginning.

MOL2RESPECTBOND

If a small molecule screen was requested, this keyword controls whether the input file(s) (the screened library and/or the reference molecule) is used to derive a list of permissible bonds per molecule. In the default choice (0), the 3D geometry is used exclusively to derive molecular topology, and this keyword offers a way to change this behavior. The primary application is for cases where the 3D conformers in the input file(s) are not free of steric clashes due to the presence of rotatable bonds / conformational flexibility. Setting this keyword to 1 will prevent CAMPARI from inferring a bond on account of a very short interatomic distance caused by a clash. This naturally assumes that the @<TRIPOS>BOND section in the input file(s) is curated perfectly. Any error (missing bond, index mismatching, etc.) will lead to an unfixable problem from CAMPARI's point of view, i.e., it will result in the molecule being skipped. Note that this keyword cannot fix problems with the covalent geometry (bond lengths, bond angles, impropers, chirality) itself.

MOL2ASSIMILAR

If a small molecule screen was requested, and the reference molecule contains substructure information (see elsewhere for details on how to define and manually match substructures), CAMPARI can match this substructure in other, unannotated molecules using a heuristic procedure. The other molecules are defined by the screened library.
The heuristic procedure relies on a best-match algorithm that provides a quantitative measure of similarity/difference. Briefly, molecules are scanned, and substructures with identical base topologies are identified. This means that there has to be a set of atoms in the screened molecule that has (at least) the same interatomic connectivity, which implies that substructures larger than a screened molecule can never be matched. This is a rigorous requirement, and no tolerance exists for comparing just matching parts of substructures. To avoid such cases, the reference substructure simply has to be made smaller. For every unique set of atoms matching the target topology, a penalty score is calculated. Unique refers to the set of labeled atoms. This has consequences for substructures containing atoms that are not unique: such sets will be proposed several times by the algorithm but with different permutations. Since the growth is exponential, and the number of considered sets is (currently) restricted to 20, it is strongly recommended to not include more than a few of such atoms. Occasionally this apparent redundancy will be explicitly desired, for example when using a substructure that has a symmetry axis but this symmetry is broken by parts of the screened molecules outside of the matched substructure.
For every atom in a candidate set, the penalty score is an enumeration with contributions from different sources: elements are compared with a limited hierarchy (meaning that, for example, an O-S replacement is better than a O-N replacement, which in turn is better than an O-C or O-P replacement). Next, there is a penalty for the geometry an atom forms with its substituents, and a penalty is applied if the center is planar in one but not the other (a stiffer penalty is applied if it is linear in one but not the other). Finally, the identities of the substituents are compared: there are penalties for differences in valencies, atom identities, and numbers of substituents that are not terminal atoms. The maximum total penalty for a typical atom is roughly 10-15, the minimum is 0, and a good but inexact match should carry a penalty of around 1-5. Note that the penalties of neighboring atoms are linked to each other due to the contributions from substituents. As explained elsewhere, substructures can (necessarily) be defined to not include all atoms connected to selected atoms. This is particularly relevant for hydrogen atoms. If hydrogen atoms are included, the average penalty will generally decrease if a matching subgroup (like -CH₃ is found). This is because two paired hydrogen atoms have almost no capacity for creating a nonzero penalty.
For a given set, the final difference score is computed as the average across all atoms in the substructures. Up to the aforementioned limit of 20, all matches with a difference score that is below the value of MOL2ASSIMILAR are at least initially processed. Once the matched substructure has been used to align the molecule, CAMPARI will calculate the RMSD value across the substructure to which an additional threshold is applied (specified by keyword MOL2RMSDTHRESH). What are good strategies in choosing and matching a substructure? Generally speaking, there are probably five main strategies:

• Use a small, rigid, and restricted substructure (only heavy atoms) with a stringent value for MOL2ASSIMILAR (up to 1.0). This can give exact chemical matches in a highly focused manner (like a carboxylate group).
• Use an exhaustive but rigid substructure (including hydrogen atoms) with a stringent value for MOL2ASSIMILAR and a very stringent value for MOL2RMSDTHRESH (like 0.5Å). The latter is needed to avoid redundancy in the calculations since RMSD can be used to pick out one the best of several matching but permuted sets.
• Use a larger and possibly flexible substructure (only heavy atoms) with an intermediate value for MOL2ASSIMILAR (like 1 to 2.5) and a very lenient value for MOL2RMSDTHRESH. This will reproduce comparable chemotypes but ignore the starting geometry. Note that there is usually no reason to try to produce exact matches using larger substructures although it is possible (smaller ones will generally suffice). One danger of including more and more atoms, even if they are heavy atoms, is the appearance of additional symmetry-related duplications or variants. Depending on the problem at hand, this might be both a feature and a caveat.
• Use a larger and possibly flexible substructure (only heavy atoms) with a lenient value for MOL2ASSIMILAR (like 2.5 to 5) and a stringent value for MOL2RMSDTHRESH (like 1.0Å) This will prioritize shape matching over chemical similarity. The biggest risk in this approach is that there are too many initial matches, which preclude relevant ones from even being evaluated (the best matches according to the chemical similarity are prioritized, however). This is where bigger substructures can be useful since they might be able to limit the space of available matches upfront.
• Use a small but maximally characteristic substructure with an intermediate or lenient value for MOL2ASSIMILAR and a lenient criterion for MOL2RMSDTHRESH. The goal of this would be to find weak but potentially interesting matches.

In the binding pocket of a receptor, it is common that a substructure can be extended in only few directions but not at all in others. The matching algorithm cannot and does not take this into account. To align to a "terminal" substructure with only terminal substructures from the screened molecules, it is probably best to employ strategies 2 or 3 above. With 2, the terminal nature is defined explicitly while with 3 the chance for matches that overlap a nonterminal unit with a terminal one is reduced because the substructure is larger. If the screened molecules are significantly larger than the reference one, however, strategy 3 might not be as feasible. The specific alignment of screened molecules with the reference molecule is known as "tethered" or "anchored" docking. After this, the calculation proceeds as in a normal small molecule screen (the tethering thus serves to create an initial conformation and, as such, conflicts with RANDOMIZE settings other than 0).
Because the tethering will frequently place parts of molecules such that they overlap with receptor atoms, it is not recommended to perform the actual search without, at least in the beginning, a Monte Carlo sampler. MC methods have the advantage that they are highly tolerant to the extreme energies resulting from nuclear overlap. A second caveat is that the tethering most likely makes sense only if the movement of the tether is restricted. This can, in rare cases, be achieved by keyword MOL2FRZMODE, but a much more general and useful solution is the use of automatic position restraints. In both scenarios, some molecules will inevitably end in a highly frustrated conformation that is unsuitable for gradient-based methods (extreme forces). Here, a "safe" termination will be desirable, and this can be controlled by keyword THRESHOLD_INCR.
Lastly, in some applications, users may want to process molecules with unmatched substructures regardless. Since the requirements toward the sampler can differ dramatically, this is an intrinsically difficult proposition. Nevertheless, to achieve this behavior, a negative value for MOL2ASSIMILAR can be specified (the interpreted difference threshold is always taken as the absolute value).

MOL2RMSDTHRESH

If a small molecule screen was requested, and the reference molecule contains substructure information (see elsewhere for details on how to define and manually match substructures), CAMPARI can identify matches between similar substructures in the reference and the screened molecules. This keyword defines the tolerance for the geometric similarity of the atoms once they have been aligned according to this chemical matching algorithm, which is explained in detail for keyword MOL2ASSIMILAR. The value has to provided in Å.

NRSTEPS

This keyword sets the total number of simulation steps including equilibration. A step is either a single propagation event by the chosen propagator or the advancement to the next trajectory snapshot in a trajectory analysis run. Currently, the only keyword to manipulate the user choice for NRSTEPS is a file with selected input frames in an analysis run. This can have consequences as other keywords, for example DISABLE_ANALYSIS rely on correct values for NRSTEPS. The default is 100000, and this keyword should always be specified.

EQUIL

This keyword specifies the total number of equilibration steps. This implies that no analysis is performed as long as the current step number does not exceed this value. Note that this also means that no structural output (trajectory) is produced. Conversely, certain necessary diagnostics are provided irrespective of equilibration (see for example ENOUT or ACCOUT). The default differs: it is 10000 for a simulation run and 0 for an analysis run (see PDBANALYZE).

TEMP

This keyword sets the absolute (target) temperature in K (default of 298K).

ENSEMBLE

This crucial keyword determines which ensemble to simulate the system in. The options available are limited in that they depend strongly on the type of sampler (i.e., there is no NVE (microcanonical) ensemble if sampling is done via Monte Carlo → DYNAMICS).

The options are as follows:
   1) NVT (Constant Particle Number, Constant Volume, Constant Temperature):
   2) NVE (Constant Particle Number, Constant Volume, Constant Energy):
   5) μ_iVT (Constant Chemical Potential(s), Constant Volume, Constant Temperature):
   6) Δμ_iN_tVT (Constant Chemical Potential Difference(s), Constant Total Particle Number, Constant Volume, Constant Temperature):
 To be added in the future:
   3) NPT (Constant Particle Number, Constant Pressure, Constant Temperature):
   4) NPE (Constant Particle Number, Constant Pressure, Constant Enthalpy):
  
Note to developers: there is rudimentary support for NPT and NPE ensembles in CAMPARI right now but those branches are completely disabled.

GRANDREPORT

If an ensemble is chosen that allows particle number fluctuations, this keyword acts as a simple logical whether or not to write out a summary of the grand-canonical setup, i.e., which particle types are allowed to fluctuate in numbers, what the initial numbers (bulk concentrations) are, and what (excess) chemical potentials are associated with those.

GRANDMODE

If an ensemble is chosen that allows particle number fluctuations, this keyword acts to choose between two different implementation modes. In the first (choice 1), file input is used to provide CAMPARI with the initial numbers and absolute chemical potentials of fluctuating particle types. This is generally inconvenient for cases with realistic interaction potentials and/or multiple fluctuating particle types that require coupled chemical potentials (such as individual ionic species). The bulk concentrations are set implicitly by the chemical potentials. This formulation involves the "thermal volume" of particles meaning that a monoatomic ideal gas will require a mass-dependent chemical potential. In the second option (choice 2, which is the default), the same file input is used to set the bulk concentration explicitly (based on the initial particle number provided), and the chemical potentials listed are merely the excess terms. This formulation involves no mass-dependent terms, is numerically more stable (accuracy of exponentials), and provides an easy reference limit for dilute solutions (zero excess chemical potential).
To illustrate the difference in implementation, consider the additional contribution to the acceptance probability (term c_b in description of keyword MC_ACCEPT) of a particle insertion attempt:
Mode 1:
c_b = e^βμ_ideal · e^βμ_excess · V· (N+1)^-1· ζ^-1
Here, V is the system volume, N is the current number of particles of the type to be inserted, μ_ideal and μ_excess are the components of the chemical potential, and ζ is the aforementioned thermal volume.
Mode 2:
c_b = e^βμ_excess · <N> · (N+1)^-1
This equation contains the expected bulk concentration as <N>.
While numerically the two cases can be made equivalent, the latter contains a self-consistency check by being able to compare the measured <N> to the assumed <N> given the chosen μ_excess. In the former, the assumed <N> is unknown, because the partitioning between μ_ideal and μ_excess is not explicit. For a single-component system (or a system with multiple independent components), the measured <N> can be used to derive the μ_excess that the simulation essentially corresponded to. With dependent components, however, this becomes very difficult to adjust. For general calibration strategies of excess chemical potentials and background, see references.

DYNAMICS

This is one of the core keywords and specifies how to propagate (sample) the system, i.e., how to obtain a new conformation of the system given the current one. The system configuration usually involves both momenta and coordinates unless the sampler is momentum-free (e.g., Monte Carlo). Most propagation schemes are able to take advantage of the shared memory parallelization, but it is important to benchmark this routinely as the scalabilities differ. For example, the work load available for parallelization in an incremental energy evaluation in Monte Carlo is usually much smaller than that in a full force evaluation in dynamics. Options are as follows:
   1) Pure Monte Carlo sampling (see keyword MC_ACCEPT and section on Monte Carlo move sets).
   2) Molecular Dynamics:
          A simplified summary of the internal coordinate space variant is as follows:

1. Dynamics are performed on internal degrees of freedom which are assumed to be independent (rigid body translation, rotation around the Cardinal x, y, and z axes of the laboratory frame (static) centered at the center of mass of each molecule, torsional degrees of freedom).
2. Dynamics for polymers vary along the chain (faster at the termini) as they should, but this does not happen in any fashion proven to comply rigorously with a specific dynamics. By altering the chain alignment mode, more exotic dynamics can be produced. This is because the building directions of any polymer chains represent an arbitrary choice in the method.
3. By assuming a diagonal mass (inertia) matrix (viz., a block of the mass metric tensor), applicability of simple integrators is a given. In the absence of interaction-based forces, the goal is to preserve rotational kinetic energy (but not angular momentum) by considering the effective masses associated with various rotational degrees of freedom as time-dependent variables in a discrete integration scheme. This treatment is intrinsically consistent, and agreement with data obtained from Monte Carlo simulations has been shown (for select cases). CAMPARI provides a simple diagnostic of the impact of assuming a diagonal mass matrix by printing kinetic energies in both internal and Cartesian coordinates to log-output.
4. Because the algorithm does not produce dynamics that obey Gauss' principle of least constraint or conserve angular momentum, integrator stability can be inferior to that for a case of identical constraints realized as holonomic constraints in Cartesian molecular dynamics. This effect cannot always be quantified since the holonomic constraints implied by the internal coordinate space treatment often become too highly coupled for linear solvers to converge (→ SHAKEMETHOD). Select cases with quickly varying masses highlight the effect, and the most significant example are probably rigid-body simulations of water (water has tiny rotational inertia and is a prototypical test case for rigid-body integrators). Quantification of relative integrator stabilities for such a case can be performed. The stability can be increased by altering atomic masses (mass redistribution in methyl or hydroxyl groups is a common technique) or by using an automatic approach that takes advantage of the formal independencne of the degrees of freedom achieved by the diagonal inertia matrix.
5. Subtle equipartition artifacts (i.e., some individual or collective degrees of freedom heating up at the expense of others because they are either more susceptible to integration error or weakly coupled to the rest of the system) can always occur. Effects differ between internal coordinate and Cartesian treatments. This is because dihedral angles will generally have a rather different level of energetic coupling and integration stability than the positional coordinates of an atom embedded in a polyatomic molecule.

   3) Langevin Dynamics:
   5) Mixed Monte Carlo and Newtonian (Molecular) Dynamics:
   6) Minimization:  
   7) Mixed Monte Carlo and Langevin Dynamics:

  To be added in the future are:
   4) Brownian Dynamics

Note that in all of the above methods relying on forces (options 2-7), it is very likely that optimized loops will be used (depending on settings for the Hamiltonian). These currently have the property of using few stack-allocated array variables that may become large if cutoff settings are very generous or if no cutoffs are in use. This may lead to unannotated segmentation faults (depending on compiler, architecture, and local settings). There are several workarounds (on Unix-systems, the shell command "ulimit" can for example be used to increase stack size for the local environment) some of which will be compiler-specific (for example to force the compiler to always allocate local arrays from the heap). Stack access is faster and therefore generally desirable in the speed-critical portions of the code.

MC_ACCEPT

If the simulation uses (at least partially) Monte Carlo sampling, this very important keyword allows the user to choose between (currently) three different types of acceptance rules for MC moves that are as follows:

1. The Metropolis criterion is used. A random number sampled uniformly over the interval is compared to the term c_b·e^{-β ΔU}. Here, ΔU is the difference in (effective) energy of the new vs. the original conformation (U_new - U_old), β is the inverse temperature, and c_b is a bias correction factor that is specific to the move type. If the random number is less than the term above, the move is accepted. Note that c_b can encompass different types of bias. It is also important to keep in mind that some advanced move types may imply incorporating biasing terms during the picking of a new conformation (see TORCRMODE), and no longer show up in c_b. The Metropolis criterion has the advantage that it is rejection-free in the limit of no energetic or other biases. With a non-zero energy function in place, the distribution sampled from is the Boltzmann distribution.
2. A Fermi criterion is used. A random number sampled uniformly over the interval is compared to the term (1 + c_b^-1·e^{β ΔU})^-1. If the random number is less than the term above, the move is accepted. The Fermi criterion's only advantage over the Metropolis criterion is that it defines an actual probability on the interval [0,1]. The downside is that the limiting acceptance rate is only 50%. However, the impact is much weaker if ΔU is relatively large on average (in absolute magnitude). The sampled distribution is again the Boltzmann distribution.
3. A Wang-Landau / Metropolis criterion is used. A random number sampled uniformly over the interval is compared to the term c_b·e^{β Δln T} or to the term c_b·e^{-β ΔU - Δln T} (see keyword WL_MODE). Here, Δln T is the difference in the logarithms of the current and proposed estimates of the target distribution (e.g., the density of states), i.e., Δln T = ln T_new - ln T_old. The Wang-Landau algorithm is explained in detail elsewhere, but it should be pointed out that the sampled distribution is no longer the Boltzmann distribution (instead it is ill-defined, and the simulation results require snapshot-based reweighting), the simulation does not satisfy detailed balance (the estimate of the density of states changes continuously), and convergence/errors are much more difficult to assess (since the method is essentially an iteration and not an equilibrium sampling scheme). It is crucial to keep in mind that the standard Metropolis criterion is used while the simulation has not exceeded the number of equilibration steps. This is mostly to avoid range problems when starting from random initial configurations.

Note that replica-exchange swap moves are currently not affected by this choice (they always utilize the Metropolis (default) choice to determine move acceptance).

TMD_RELAX

If the attempted calculation is a gradient-based run in internal coordinate space, this keyword provides the option to use highly specialized Monte Carlo sampling to relax features of the starting geometry that could cause the integrator to become unstable. The keyword is interpreted as a threshold setting (a.u.) for the absolute, normalized force acting on internal degrees of freedom, and values from 10-100 are probably appropriate. If no forces exceed the threshold, no relaxation steps are performed.
The relaxation works hierarchically in three stages: First, dihedral angles experiencing large forces are identified. Those with rotation lists including only atoms that are all from the same residue are deemed eligible, and the residue is added to a temporary list for Monte Carlo sidechain sampling. CAMPARI then performs TMD_NRRELAX steps of sidechain moves per eligible sidechain in accordance with move parameters such as CHIRDFREQ and CHISTEPSZ. If the shared memory parallelization is in use, the actual Monte Carlo cycles utilize more than a single thread, but the global force calculations do not. This relaxation methodology is useful for dealing with systems with incomplete structural input (from the PDB, for example), where sidechains have been rebuilt blindly. Second, single-residue molecules experiencing strong rigid-body forces are identified, and a temporary list for rigid-body sampling using only rigid rotation moves is populated. CAMPARI then performs TMD_NRRELAX steps of these rigid rotation moves per molecule. This is useful for dealing with dense systems that were only incompletely equilibrated or (partially) randomized. In a last step, a temporary list for rigid-body sampling is again populated this time using a looser threshold that is calculated as 10 times TMD_RELAX. CAMPARI then performs TMD_NRRELAX of joint rotation/translation moves per molecule on these molecules. This can lead to a complete displacement of molecules (see RIGIDRDFREQ). The resultant "relaxed" starting structure is written to a dedicated output file.
Naturally, there is a point at which the starting geometry should simply be deemed inappropriate for starting a gradient-based calculation. Importantly, these custom MC steps observe the complete Hamiltonian in use as well as relevant cutoff settings. They do not, however, count toward the final output or any analysis tools irrespective of the type of parent calculations. Related keywords are RANDOMTHRESH, RANDOMATTS, and CYCLE_MC_FIRST. Unlike those keywords, TMD_RELAX is particularly useful for large systems with few defects as it relies on the measured force explicitly. Of course, this functionality still overlaps with the approach of using two separate calculations where the Monte Carlo run is heavily customized using the preferential sampling utility. Lastly, note that this option is not available in Cartesian dynamics.
In a small molecule screen, the relaxation cycle is repeated before every molecule is screened. This can be a significant contribution to the cost of the calculation although normally few degrees of freedom should become eligible again.

TMD_NRRELAX

If the attempted calculation is a gradient-based run in internal coordinate space, and an initial relaxation has been requested (→ TMD_RELAX), this keyword sets the number of Monte Carlo steps to be performed per stage and per eligible entity (residue or molecule). As described, there are three independent stages. The default value for TMD_NRRELAX is 20.

FRICTION

This keyword allows the user to specify the uniform damping coefficient acting on all degrees of freedom. The value is interpreted to be in ps^-1. Currently, this is only relevant if DYNAMICS is set to either 3 or 7. In Langevin dynamics, the velocity damping through friction is given by e^-γ·δt. Here, γ is the damping coefficient, and δt is the integration time step (see TIMESTEP). Note that in Cartesian dynamics (see CARTINT) each degree of freedom is an orthogonal direction of the Cartesian movement of each atom. Typically, Langevin dynamics integrators may make the friction on those degrees of freedom dependent on atom mass but CAMPARI does not support this at the moment since the hydrodynamic properties of individual atoms are poorly described in any case. Conversely, in torsional dynamics, the rigid-body and torsional degrees of freedom of each molecule are integrated and the friction is applied uniformly to all of those. This means that hydrodynamic properties are - again - ill-represented. Bias torques on account of variable effective masses for most dihedral angle degrees of freedom will continue to be in effect (see elsewhere).
When applying Stokes' law (which should be inapplicable when the diffusion object is strongly aspherical and/or of similar size compared to the molecules comprising the surrounding fluid) to the self-diffusion of water, the measured diffusion constant of around 2.3·10^-9 m²s^-1 is roughly consistent through the Einstein-Stokes equation with the measured viscosity of about 8.9·10^-4 kgm^-1s^-1 (both at 25°C). By dividing by the mass, a damping constant of about 90ps^-1 can be obtained from the Stokes approximation. When performing stochastic dynamics simulations of large, spherical rigid bodies, such a value may be appropriate. For molecular simulations, however, it is not. First, in conjunction with typical time steps, the value is so large that the impulse integrator in use (→ DYNAMICS) can no longer sample the correct ensemble (it becomes overdamped implying temperature artifacts). Second, in a Cartesian treatment, unless one samples a monoatomic fluid of inert particles, the correlations between particles are so high that a treatment as independently diffusing spheres is not just inaccurate, but nonsensical in the absence of hydrodynamic interactions. Third, in internal coordinate spaces, the individual degrees of freedom hardly ever fit the Stokes approximation. Torsional and rigid-body rotational degrees of freedom would require a completely different model of friction. Furthermore, unlike in a Cartesian treatment, the degrees of freedom are not all similar to one another. The above means that the damping constant should be understood as an empirical parameter. Better control over values for individual degrees of freedom will be implemented in the future. It defaults to a value of 1.0 ps^-1 on par with the coupling times of thermostats in molecular dynamics (→ TSTAT_TAU).

CYCLE_MC_FIRST

If a hybrid MC/M(B,L)D method is used (see DYNAMICS), this keyword controls the length of the first segment (in number of steps) which is always a MC segment. This is to ensure that hybrid runs can safely be started from poorly equilibrated (random) structures where forces are large and integrators quickly become unstable.

CYCLE_MC_MIN

If a hybrid MC/M(B,L)D method is used (see DYNAMICS), this keyword controls the minimum length of MC segments (in number of steps) with the exception of the first segment.

CYCLE_MC_MAX

If a hybrid MC/M(B,L)D method is used (see DYNAMICS), this keyword controls the maximum length of MC segments (in number of steps) with the exception of the first segment.

CYCLE_DYN_MIN

If a hybrid MC/M(B,L)D method is used (see DYNAMICS), this keyword controls the minimum length of dynamics-based segments (in number of steps). This should probably be significantly larger than the velocity autocorrelation time of the system.

CYCLE_DYN_MAX

If a hybrid MC/M(B,L)D method is used (see DYNAMICS), this keyword controls the maximum length of dynamics-based segments (in number of steps).

PH

This keyword sets the assumed simulation pH which currently possesses significance for titration moves only → PHFREQ. This keyword may later be extended to represent the assumed (bath) pH in constant-pH simulations.

IONICSTR

This keyword sets the assumed simulation ionic strength for simplified pK_a computations. The units are molar (M). Ionic strength is used in a grossly simplified Debye-Hückel approach to estimate cross-influences between multiple ionizable sidechains on a polypeptide ( see PHFREQ). Note that this keyword can not be used to set an assumed ionic strength for the generalized reaction-field method (see RFMODE).

RESTART

This keyword is a simple logical indicating whether to restart a previously discontinued run.
It tells the program to attempt to restart a simulation which was accidentally or intentionally terminated. The program writes out ASCII-files containing relevant information in comparatively high precision (see RSTOUT). This file (one for each node in MPI calculations) is called {basename}.rst (see elsewhere). If it is successfully read, the simulation is extended from the simulation step the file was last written for. Non-synchronous MPI runs are synchronized to the step number of the slowest node. Note that instantaneous output of the crashed run should be saved separately (i.e., moved to another directory) since with the exception of running trajectory pdb/xtc/dcd-output new files will replace the old ones. All non-instantaneous analysis of the crashed run is unfortunately lost. The simulation will then proceed starting effectively at that step, so the same key-file (with the exception of the RESTART-keyword itself of course) can be used. If it is past the equilibration step, on-the-fly analysis will begin immediately. Final output will reflect only the restarted portion of the run. The program will acknowledge in the log-file that it's restarting, and will post a warning message if the energies of the structures reported in the restart-file and re-computed by the program are inconsistent. Note that it is - rigorously speaking - only safe to restart the exact same calculation, since the information contained in the restart file will depend on the type of calculation performed. It will often be possible to start MC runs (see DYNAMICS) from a non-MC restart file, however. For the opposite and all other cases, consider using the auxiliary keyword RST_MC2MD.
It should be noted that these restarts are not fully deterministic meaning that they deviate from the original run if it had continued for more steps (this is typically unknown of course). The reasons for this are several. First, no information about the state of the random number generator is preserved. This affects Monte Carlo and Langevin dynamics sampling , stochastic thermostats, and so on. Second, the information in the restart files is not printed to full double precision (this has historical reasons). This means that even a conceptually deterministic simulation will start to deviate after some number of steps (depending on the system). Third, if the shared memory parallelization is used, the balancing of load is initialized and reoptimized as it would be at the beginning of the simulations. This leads to a different sequence and blocking of computations, which subtly affects sums, for example. Fourth, as a related point, the order and grouping of compute tasks are architecture- and compiler-dependent. This means that code using different optimization levels or simply a different compiler is not the same at the machine level, and consequently the results are not the same either. Much more dramatic deviations are obtained by enabling aggressive optimization settings, for example those that reduce the precision of built-in mathematical functions. While the first two points could be avoided easily, the latter two are essentially insurmountable with present-day computers. One way to state this deficiency is to redefine numerical reproducibility as the matching of a reference result with finite accuracy, i.e., for suitably rounded results to be the same. The required level of rounding depends on the "depth" of the calculations, i.e., on how often inaccurate results are reused. This technique was used extensively in debugging the OpenMP parallel code across different architectures and compilers.

RST_MC2MD

This is a rather specialized keyword meant for the specific case of (re)starting a dynamics run from a restart-file generated by an MC run. In this case, the restart file is shorter and only contains atomic positions, the Z-matrix, and whatever else is necessary. When set to 1, this keyword instructs the restart-file reader to assume the MC format even though the run is set to be a dynamics run (see DYNAMICS). Initial velocities are then generated from a Boltzmann distribution using the bath temperature (see TEMP). Ff this keyword is not set, an attempt to read mismatched restart files will crash the program (most likely in a segmentation fault). This is due to the assumed rigid formatting. The inverse procedure (reading a restart file generated by a dynamics run as the starting point for an MC run) is currently not supported. Note that the typical application for this is to use MC for equilibration of a system and to continue the run using a dynamics sampler. In single-CPU calculations, this simplifies the overall procedure and avoids using the generally low-precision pdb format as an intermediate step (although this can be adjusted with keyword PDB_OUTPUTSTRING). For some replica-exchange runs (see REMC), restart files are actually the only option which allows starting the individual nodes from individual, non-random conformations stored in an input file. The primary application for this keyword therefore probably lies in replica-exchange molecular dynamics runs which use Replica-Exchange Monte Carlo runs for equilibration purposes.

DYNREPORT

This minor keyword is a simple logical which ensures that in dynamics calculations with different temperature-coupling groups a summary is provided of the partitioning in that regard.

CHECKGRAD

This keyword is a simple logical which instructs CAMPARI to test the gradients for the current calculation given the Hamiltonian, system, and starting structure. It tests Cartesian gradients first, followed by the transformed gradients acting on the internal degrees of freedom (if settings allow that: see CARTINT).
It is mostly for developer's usage and creates at most two undocumented output files: NUM_GRAD_TEST_XYZ.dat and NUM_GRAD_TEST_INT.dat). The procedure works by numerically computing gradients using pure energy routines (finite differencing) and juxtaposing the analytical solution. It is slow and can sometimes be misleading or uninformative for the following reasons:

1. For just a single molecule, rigid-body gradients are always net zero (outside of boundary contributions).
2. The dynamics Hamiltonian must be identical to the MC Hamiltonian (in particular, a matched pair of settings for LREL_MC and LREL_MD like 3/4 should be set, keyword MCCUTMODE should be 2, and the two cutoffs (NBCUTOFF and ELCUTOFF) should be set to the same value. If any of these conditions are not met, the output might report errors that are (well) above the base level provided by the numerical approximation.
3. For Cartesian gradients to be accurate, no strictly torsional space Hamiltonian terms should be used (see for example SC_ZSEC and SC_TOR). For those, Cartesian gradients are circumvented unless CARTINT is 2.

Importantly, the test of numerical gradients does not make use of the shared memory parallelization of CAMPARI. The consequences are that the procedure cannot be sped up and that the actual routines used to propagate the system during parallel execution are not tested. The test of the actual routines is implemented in THREADS_TEST albeit against the serial force routines. Thus, a two-stage test is needed for comparing numerical gradients to those derived from the parallel force routines.

UNSAFE

This keyword is a simple logical (default off) which allows selected fatal errors to be transformed into warnings (for example the simulation of systems which are not net-neutral). It should be used with caution (obviously) and the log-output should always be studied meticulously. In addition, enabling unsafe execution may skip some costly sanity checks, e.g., when reading in trajectories in pdb format.

CRLK_MODE

CAMPARI currently provides limited support in dealing with chemical crosslinks which either create one (or multiple) intramolecular loops, or link multiple molecules together. For force-based sampling in Cartesian space only (see CARTINT and DYNAMICS), this functionality matters exclusively for the following reasons:

1. A chemical crosslink can be thought of as a branch in the main-chain. Such non-linear polymers violate CAMPARI's model of identifying topologically connected sequence neighbors purely based upon primary sequence. Therefore, non-bonded interactions have to be corrected if the two residues in question are crosslinked to each other (to comply with the settings provided via INTERMODEL and ELECMODEL). This is supported by CAMPARI independent of crosslink type (even though there currently are only disulfide linkages supported → sequence input).
2. A single intermolecular crosslink essentially merges two molecules into a single one. However, CAMPARI continues to treat both chains as if they were independent molecules. This has a variety of reasons most of which pertain to the consistency of internal data representation and to the support of internal analysis routines. One area where this is tricky is for simulations in periodic boundary conditions (→ BOUNDARY), as shift vectors are generally applied only to intermolecular contacts. For two crosslinked molecules, this continues to be the case thereby allowing - given a poor simulation system setup - the theoretical possibility of one of the two crosslinked molecules to interact with parts of different images of the other molecule. Trajectory output may also appear confusing for the same reason.
3. New bonded interactions are created which have to be correctly accounted for. In accordance with the previous point this implies that distance vectors have to be image-corrected in periodic boundary conditions even for those. For the crosslink to be actually established it is necessary that the parameter file offer support for the required bond length, angle, and dihedral terms. This is of course true for any topological interaction in a Cartesian treatment. Request a report to obtain more information at the beginning of the simulation.
4. For random initial structures it will be necessary for the crosslink to be satisfied to allow stable integration of the equations of motion. This is elaborated upon elsewhere.
5. If the ABSINTH implicit solvation model is used (→ SC_IMPSOLV), the crosslink usually modifies two solvation groups (one on each "side") to yield a single new unit. CAMPARI will typically split this group such that the solvation groups may remain associated with their "host residue".

This keyword becomes relevant only if sampling occurs in rigid body / torsional space either through Monte Carlo- or torsional dynamics-based sampling. There are two modes of operation to be supported:

1. The crosslink is treated as restraints and the sampler is unaware of its explicit existence.
2. The crosslink is treated as a set of (hard) constraints and the sampler is adjusted to preserve these constraints. This mode is currently under development and not yet supported.

This means that in order to use mode 1, bonded terms have to be defined in the parameter file which keep the crosslink intact. New internal degrees of freedom are implicitly defined: Usually, these will comprise of a single bond length, two bond angles, and three dihedral angles (using disulfide bonds as an example: the -S-S- bond, the two -C_β-S-S- bond angles, the two χ₂-torsions in both cysteine sidechains, and the dihedral angle defined by atoms -C_β-S-S-C_β-). The former are three non-canonical degrees of freedom in rigid body / torsional space and this mixing certainly is an approximation defensible for technical reasons only. Beyond that, the sampler is expected to continue to be able to explore conformational space for the new phase space. In detail, this means that sampling in torsional / rigid-body space using force-based algorithms (see CARTINT and DYNAMICS) will be vastly favored over MC sampling (although a hybrid setting may be advantageous). This is so because the MC move set is not adjusted to reflect the restraints and will suffer from very poor acceptance rates. For example, consider an intermolecular crosslink and rigid body moves trying to displace one of the two crosslinked moieties. Alternatively, consider the ineffectiveness of pivot-style moves for residues within the loop in the presence of an intramolecular crosslink.
The latter is the primary reason for supporting mode 2 in the future. Here, the move set will be explicitly adjusted to only allow moves which automatically satisfy the crosslink exactly. For torsional dynamics this option will be less useful as CAMPARI does not possess the capability to enforce high-level loop closure constraints in torsional space and consequently all residues within the loop region would have to be completely constrained for the crosslink to remain intact exactly.

BIOTYPEPATCHFILE

This simple keyword lets the user provide the location and name of an optional input file that can be used to (re)set the assigned biotypes for specific atoms or groups of related atoms in the system. The corresponding biotype number has to be available (listed) within the parameter file in use. Biotypes are the most fundamental assignment for atoms within in CAMPARI and can indirectly set many other properties such as charge, mass, etc. This is explained in detail elsewhere. However, there are parameters not affected by biotype assignment, specifically the default geometries and parameters derived from them. This means that it is generally impossible to, for example, mutate a molecule into a different molecule using such patches. Applications of this type may be more feasible for simulations in Cartesian space.
The main domains of application for biotype patches are twofold. First, they allow the fastest and most convenient route to include parameter support for atoms in residues not supported natively by CAMPARI (→ sequence input). Second, they allow to diversify a parameter file regarding natively supported residues, .e.g., by maintaining multiple parameterizations for a small molecule or by including extra distinctions for atoms in terminal polymer residues. Biotype patches are applied first and may be largely overridden by successive application of other patches, e.g., atom type patches, charge patches, etc.

MPATCHFILE

This simple keyword offers the user to provide the location and name of an optional input file that can be used to alter the masses of specific atoms in the system (in g/mol). Normally, masses are chosen for atoms based on the assigned atom types in the parameter file, and this behavior can be overridden by this keyword specifically for atomic mass. Note that this different from changing the atom type of the atom itself, for which a dedicated patch facility is in place. Some more details are given elsewhere.

RPATCHFILE

Similar to keyword MPATCHFILE, this simple keyword offers the user to provide the location and name of an optional input file that can be used to alter specifically the radii of individual atoms in the system (in Å). By default, these radii are inferred either from the assigned atom types, i.e., computed from the Lennard-Jones size parameters, or they are overridden at the level of the parameter file by the "radius" specifications. Because the latter still operate at the resolution of assigned atom types, this keyword offers an atom-specific override facility. Note that there is a distinct hierarchy to this. Specifically, changing the radius via a patch does not change the atom type for that atom. It does, however, alter the default values of parameters that depend on radius, such as maximum SAV fractions or atomic volume reduction factors, which are then again patchable themselves. Furthermore, a radius patch overrides a radius inferred by applying a patch to the Lennard-Jones parameters of a specific atom. Details on the input are given elsewhere.

WL_MODE

By specifying the Wang-Landau acceptance criterion for a (partial) Monte Carlo run, the WL method is enabled. This keyword defines the reaction coordinate of choice and the coupled pair to be iterated (see below). Suppose we have an augmented Hamiltonian as follows:

H = K + λE + X(Y)/β

Here, K and E are kinetic and potential energies, β is the inverse temperature, and X(Y) is an unknown function of a selected reaction coordinate. The factor λ can be either 0 or 1. Assuming that the Hamiltonian is separable, expected sampling weights from the Boltzmann distribution for the augmented Hamiltonian are:

w(Y₁)/w(Y₂) = (p_λ(Y₁)/ p_λ(Y₂)) exp[X(Y₂)−X(Y₁)]

Here, p_λ(Y) is the expected probability (usually treated numerically as the integral over a finite interval, i.e., by binning). If λ is 1, it corresponds to the equilibrium (Boltzmann) probability for the original Hamiltonian. Conversely, if it is 0, p_λ(Y) corresponds to the density of states (distribution as T→∞). If Y=E, p(E) can be written simply as p(E) = g(E) exp(-λE/β), with g(E) being the density of (energy) states. This simple form is not available for other reaction coordinates. The Wang-Landau method's key ingredient is choosing X(Y) such that w(Y_i)/w(Y_j) = 1 ∀ i,j over an interval of interest. This statement is equivalent with the definition of a flat walk in the space of Y. A flat walk eliminates all barriers in the projected space of Y and should therefore be efficient at exploring phase space (see associated keywords for details on this). The main use of the flatness is as a diagnostic, however, and the Wang-Landau algorithm uses X(Y) and the apparent distribution in Y as a coupled pair to iteratively build up X(Y). If the apparent distribution becomes flat, confidence rises that X(Y) corresponds to the target distribution of interest. The target distribution is set by this keyword:

1. The target distribution is ln g(E) (arbitrary offset). This is achieved by letting λ be zero and Y=E. This is also the implementation chosen in the original publication. Interest in the density of states comes from the fact that it (theoretically) enables reweighting of the flat-walk ensemble to any condition of interest. This is the default.
2. The target distribution is ln p(Z) or ln p(Z_a,Z_b) (arbitrary offset), where the Z are geometric reaction coordinates (→ WL_RC) restricted to specific molecules (→ WL_MOL). By letting λ be unity, the target distribution is actually the potential of mean force (PMF) for that (pair of) reaction coordinate(s). Unlike for umbrella sampling (see, e.g., Tutorial 9), it is obtained without further post-processing. This variant was introduced here. As stated, it is possible to estimate a two-dimensional target distribution.
3. The target distribution is ln p(E) or ln p(E,Z) (arbitrary offset). This is achieved by letting λ be unity and Y=E. In comparison to the first option, this will oversample low likelihood states rather than low degeneracy states. It can be combined with a geometric reaction coordinate (Z) in a two-dimensional approach.

The iteration proceeds by simply incrementing an estimate of X(Y) based on the apparent probability. The increment is lowered successively toward convergence. This corresponds to a hierarchical approach in which coarse features of the target distribution are established first before the fine details are added. The three main issues with the Wang-Landau method are as follows (and much literature has been dedicated to these, which is well beyond the scope of this documentation). First, all Wang-Landau results require snapshot-based reweighting techniques to recover quantities not identical with or trivially related to the target distribution. Reweighting techniques have different error properties than standard sampling techniques due to the appearance of exponential weights. Second, it is difficult and system-dependent to guide and assess the convergence of the method. This is partially a result of fundamental problems (degeneracy in Y) and method-specific issues (see keywords WL_HUFREQ, WL_FLATCHECK, WL_FREEZE, etc). Third, the method suffers from discretization errors in particular at steep boundaries of the target distribution. This often necessitates a rather arbitrary restriction of the interval to establish the flat walk on, and this limitation can easily corrode the confidence in the results (see keywords WL_BINSZ, WL_MAX, WL_EXTEND, etc).
A few technical comments are necessary. First, the Wang-Landau acceptance criterion can be combined with a hybrid sampling technique. In such a case, the dynamics segments will propagate the system as usual, but will contribute in no way to the Wang-Landau histograms. They merely serve to evolve the system to find new states that may be hard to access given the Monte Carlo sampler. The MC segments will utilize the Wang-Landau criterion and increment the histograms. As a result, it may be possible that a dynamics segment starts in a high energy state. This may make the integrator unstable initially, and cause unforeseen crashes. Second, Wang-Landau sampling is also supported in parallel runs. For pure Monte Carlo simulations, the MPI averaging technique implies a parallel Wang-Landau implementation, i.e., an implementation in which the histograms are updated globally. Wang-Landau sampling is also supported in conjunction with the replica-exchange method, but here each replica is confined to its own iterative Wang-Landau procedure (since the Hamiltonians are most likely different).

WL_MOL

If a Wang-Landau acceptance criterion is used for a (partial) Monte Carlo run, and if a molecular reaction coordinate was chosen as the histogram to consider (→ WL_MODE), this keyword allows the user to select the molecule that the reaction coordinate is computed on. The numbering of molecules follows the user-selected sequence in sequence input. Note that it is up to the user to ensure that the chosen reaction coordinate is defined and has a meaningful range for the chosen molecule (see WL_MAX, WL_EXTEND, and WL_BINSZ). If a two-dimensional variant with two geometric reaction coordinates is chosen, it is theoretically possible to supply two different molecules here. Note that the effective coupling is likely to be low in this scenario, which may lead to poor convergence properties in the 2D space. In conjunction with WL_MODE being 3, specification of a legal entry for WL_MOL will extend the WL estimation of ln p(E) to a two-dimensional case with an additional, geometric reaction coordinate (ln p(E,Z)). Note that this keyword is the only way to control the dimensionality for WL_MODE being either 2 or 3.

WL_RC

If a Wang-Landau acceptance criterion is used for a (partial) Monte Carlo run, and if a molecular reaction coordinate was chosen as the histogram (or as one or both axes of the 2D histogram) to consider (→ WL_MODE), this keyword allows the user to select amongst few geometric reaction coordinates as follows:

1. The molecule's radius of gyration is used (default). The range of this quantity is difficult to predict and depends on the constraints in the system. For example, in Cartesian space, it will be advisable to restrict the range of the histograms (→ WL_MAX and WL_EXTEND) to those values that do not coincide with steric overlap (low end) or stretching of bonds (high end).
2. The molecule's mean α-content is used as defined for the global seconday structure biasing potential. The quantity always has finite range, but for small systems and typical settings, it exhibits sharp spikes connected by low likelihood regions that may challenge the discretization of the WL scheme.
3. The molecule's mean β-content is used. See previous option for details and caveats.

Note that it is up to the user to ensure that the chosen reaction coordinate is defined and has a meaningful range for the chosen molecule (see WL_MAX and WL_BINSZ). For two-dimensional cases with two geometric reaction coordinates, the user is may specify up to two numbers. Note that the exploration space grows exponentially with dimensionality at the benefit of resolving degeneracies projected onto the same range of values when considering just one of the two axes at a given time. The total number of relevant bins is a key quantity to keep in mind when directing and assessing convergence. In conjunction with WL_MODE being 3, specification of a legal entry for WL_RC is not sufficient to extend the WL estimation of ln p(E) to a two-dimensional case with an additional, geometric reaction coordinate (ln p(E,Z)). Use keyword WL_MOL for this purpose.

WL_HUFREQ

This is one of the keywords that controls the convergence properties of a Wang-Landau run. The target distribution in question is accumulated as a histogram (always logarithmic), and this keyword sets the frequency (step interval) for updating it with the current value of the f parameter, i.e., the current increment size (equivalent to multiplication by f in the linear space). The accumulation of the target distribution begins only after the equilibration phase has passed. Naturally, a small setting here will quickly increment the histogram, which may accelerate convergence (in case the effective "mobility" of the system defined by system properties and sampling engine is good enough). However, a small setting may also interfere with convergence because it emphasizes the noise in initial estimates of the target distribution (in absolute magnitude), and this may make it harder to refine the guess upon reductions of the f parameter (see WL_HVMODE and WL_FREEZE). The default choice is 10 elementary steps. Note that if the parallel Wang-Landau implementation is used, the step number provided refers to the sampling amount for each individual node.

WL_HVMODE

This is one of the keywords that controls the convergence properties of a Wang-Landau run. It has been argued that the flatness of the accumulated histogram for the target distribution in question (usually tested via some maximum relative deviation criterion) is not generally useful as a criterion for considering a switch to the next stage of refinement (by lowering the f parameter), and can be replaced with a recurrence (minimum visitation) criterion (discussed for example in Zhou and Bhatt). This keyword selects two different options for such a recurrence criterion. Option 2 requires each (relevant) bin to be visited exactly once in every stage, whereas option 1 mandates that each bin be visited the nearest integer of 1/sqrt(f) times (at least once, though). In the parallel parallel Wang-Landau implementation, the condition will always be checked against the combined data. If the condition is fulfilled, and if the number of post-equilibration Wang-Landau steps exceeds the buffer setting, ln f will be reduced (initial value set by keyword WL_F0) by a factor of 2. Note that the f parameter is implied to operate on a logarithmic scale (same as target distribution) of counts to avoid numerical issues with large numbers. The rule used here is equivalent to the square root update rule suggested in the original publication. Belardinelli and Pereyra suggest that the exponential update becomes inappropriate for small f and CAMPARI implements their suggestion to switch over to f ∝ 1/N_steps, where N_steps is the current number of WL steps having being executed. In the parallel parallel Wang-Landau implementation, this implies the combined total of WL steps from all replicas. This modified update rule is implemented irrespective of the fulfillment of the criterion defined by WL_HVMODE.
It is useful to keep in mind that option 1 will initially lead to fewer reductions of the f parameter, which may be beneficial for establishing correctness, and at the same time may be harmful for the rate of convergence. An issue often affecting convergence adversely are very-low-likelihood bins. In this context, it should be emphasized that the relevance of a bin toward defining flatness is partially controlled by keyword WL_FREEZE, which consequently serves two purposes, and partially controlled by the general range settings (WL_MAX, WL_EXTEND, and WL_BINSZ).

WL_FLATCHECK

If a Wang-Landau acceptance criterion is used for a (partial) Monte Carlo run, this keyword can be used to control the step interval at which the evaluation of the visitation criterion for the temporary histogram is performed. If the parallel Wang-Landau implementation is used, this coincides with the requirement to (at least temporarily) combine the data from all replicas and therefore imposes a communication requirement. Should a check return a positive result, the temporary histogram is added to the overall estimate, the temporary histogram is reset to zero, and the f parameter is altered as described elsewhere. In the parallel version, additional operations are performed to broadcast the new total (combined) histogram identically to all replicas. In case the criterion is not fulfilled, the temporary histogram(s) is (are) left unchanged.
The technical use of this keyword is twofold: First, to reduce communication requirements for the parallel implementation; second, to artificially delay the progression of the iteration. The latter can sometimes be useful for complex systems with strong degeneracy in the chosen reaction coordinate (also see WL_RC). Note that for the parallel code the step number provided refers to the sampling amount for each individual node.

WL_F0

If a Wang-Landau acceptance criterion is used for a (partial) Monte Carlo run, this keyword defines the starting value for the f parameter (logarithmic). The f parameter is meant to decay from some positive number to 0, which corresponds to multiplicative factors larger than 1 reducing to 1 in the linear space. The default is 1.0. The number of reductions of the f parameter by the exponential rule (see elsewhere) is printed to log output. Depending on the properties of the system and the resultant convergence rate, the rule may change as described for WL_HVMODE.

WL_MAX

If a Wang-Landau acceptance criterion is used for a (partial) Monte Carlo run, this keyword sets the (initial) upper bound (given as the bin center of the last bin) of the energy or reaction coordinate histogram (→ WL_MODE and WL_RC). At the beginning, 100 bins of equivalent size are created. Depending on the choice for WL_EXTEND, the histogram and its upper limit may be extended throughout the simulation. It is safe to extend the histogram to values that are impossible to realize for the system in question, since bins that are strictly empty do not meaningfully contribute to the algorithm (see WL_FREEZE). CAMPARI accepts two separate entries for any 2D histogram. Note that the choice for this keyword may be overwritten if a dedicated input file is used to set an initial guess for the target histogram (→ WL_GINITFILE). The maximum value that will not trigger a range exception or an automatic histogram extension is of course the value given here plus half the relevant bin size.

WL_BINSZ

If a Wang-Landau acceptance criterion is used for a (partial) Monte Carlo run, this keyword sets the fixed bin size for the energy or reaction coordinate histogram (→ WL_MODE and WL_RC). At the beginning, 100 bins are created. Depending on the choice for WL_EXTEND, the histogram and its lower and upper limits may be extended throughout the simulation. However, the bin size will remain fixed. CAMPARI accepts two separate entries for any 2D histogram. Note that the histogram bin size and the initial number of bins may be overwritten if a dedicated input file is used to set an initial guess for the target histogram (→ WL_GINITFILE).

WL_EXTEND

If a Wang-Landau acceptance criterion is used for a (partial) Monte Carlo run, this keyword controls whether the energy or geometric reaction coordinate histogram (→ WL_MODE) is allowed to grow in range during the simulation. Choices are as follows:

1. The histogram is fixed. Note that any Wang-Landau simulation performed over a restricted interval bares the danger of generating incorrect results even after reweighting. For common interaction potentials and standard energy-based Wang-Landau sampling, this is particularly true for truncation of the energy histogram on the lower end.
2. The histogram is allowed to grow only towards lower (more negative) values. This can be useful for energy histograms, where the initial energy range is not known.
3. The histogram is allowed to grow in both directions. It is strongly recommended not to use this feature for energy histograms with a realistic interaction potential (since the energy is unbound on the positive side, and memory exceptions / segmentation faults are likely). This option is meant primarily for histograms defined purely on geometric reaction coordinates (→ WL_MODE).

Note that this keyword only controls changes to the physical dimensions of the histogram arrays in memory that are originally set either by keywords WL_BINSZ and WL_MAX (with 100 bins by default) or by file input (arbitrary number of bins). For issues pertaining to the discarding of unpopulated, terminal bins for convergence, see WL_FREEZE.

WL_GINITFILE

If a Wang-Landau acceptance criterion is used for a (partial) Monte Carlo run, this keyword allows the user to replace the default initial guess for the (logarithmic) target distribution with a user-supplied one. The default guess is flat. Supplying a nonflat guess can be useful in several scenarios: i) ongoing refinement of a WL run; ii) cases where a more useful "zero order guess" is available, e.g. an exponentially growing function for a condensed phase system with inverse power potentials; iii) convergence tests. The details regarding the format of this input file are provided elsewhere.

WL_FREEZE

If a Wang-Landau acceptance criterion is used for a (partial) Monte Carlo run, this keyword controls whether the range of bins in the energy or reaction coordinate histogram (→ WL_MODE) that is considered for proceeding to the next iteration stage (updating the value of the f-parameter) is fixed after the first such update or not. The update procedure is described for keywords WL_HUFREQ, WL_HVMODE, and WL_FLATCHECK.
Any positive integer specified here will prescribe a minimum number of preliminary simulation steps beyond equilibration that must be exceeded before an update of the f-parameter is considered. After such an update, the range of bins considered for the histograms is the continuous one (and it must be continuous on account of the update rule) currently populated. If during further simulation steps additional bins were to be visited, those moves are instead considered as range exceptions and are rejected (the summary statistics provided in log-output for range exceptions can therefore contain results from two different contributions → WL_EXTEND). Any negative number provided will specify by its absolute value the aforementioned minimum number of preliminary steps in identical fashion. However, in this case, CAMPARI is instructed to allow further bins to be added for consideration during later stages of the algorithm. Note that this violates the refinement idea behind the Wang-Landau scheme, and can lead to severe convergence problems due to the numerical mismatch created by the extra bin "missing out" on f-increments during early stages of the algorithm. It is therefore strongly recommended to choose a relatively large and positive number for this keyword (to ensure that appropriate coverage of the accessible range has been reached).
Note that if the parallel Wang-Landau implementation is used, the step number provided refers to sampling amount for each individual node.

WL_DEBUG

If a Wang-Landau acceptance criterion is used for a (partial) Monte Carlo run, this simple logical allows the user to request debugging information regarding the Wang-Landau iterative algorithm. If turned on, CAMPARI will report in log-output the progression through the various updating stages and may - depending on settings - also write temporary output files for the relevant histograms.

Box Settings:

---

(back to top)

BOUNDARY

Every simulation has to occur within an explicitly or implicitly defined, finite volume. CAMPARI presently supports different ways of achieving such a finite volume listed below. For constant volume ensembles (→ ENSEMBLE), the (formal) volume remains exactly constant throughout the simulation. This does not imply that volume remains a meaningful paramerter under all circumstances, e.g., if phase separation occurs. For the type of boundary condition, there are currently three supported options and one quasi-obsolete mode:

1. Periodic boundary conditions (PBC):
   This is the most commonly used boundary condition in molecular simulations. Here, the generally polyhedral simulation cell is assumed to be replicated as a - theoretically infinite - periodic system around the central one (which constitutes the actual, physical simulation container). Partial periodicity is also possible with other walls implemented as restraints. This is theoretically applicable to many different containers including polyhedra but only supported for periodic cylinders at the moment (SHAPE is 3 and BOUNDARY is 1). The implementation is such that all distance calculations along periodic dimensions are amended by determining the smallest distance amongst those between a particle and any of the replicated images of another particle. This so-called minimum image convention implies that for normal pairwise interaction potentials (for example SC_IPP) a particle only interacts with at most one "version" of another particle, never two or more. The idea of PBC is borrowed from crystals in which the assumption of periodicity is justified given that the simulation volume can be chosen such that it coincides with the crystal's unit cell (or exact multiples thereof).
   Conversely, in liquids there is no persistent long-range order (homogeneous density, no pair correlations), and the approximation of a system of thermodynamic size by infinite replication of a nanoscopic system is at least questionable. Given typical cutoff schemes, however, the contribution of longer-range interaction is often exactly zero unless explicit techniques are used enumerating the periodic sum (→ Ewald summation, which is the only feature for which CAMPARI currently calculates interactions beyond the minimum image convention). This means that the actual impact of PBC is often just to mimic a continuous environment for particles close to the edge of the physical simulation volume. Note that no real-space interaction cutoff should exceed half the shortest linear dimension realizable in the simulation volume since otherwise it becomes possible for multiple images of the same particle to be within interaction distance. In conjunction with the minimum image convention cited above, this invariably leads to artefactual results (reference). Note that in CAMPARI the convention of using the nearest image operates at the molecule level, i.e., the general rule is that intramolecular distances always refer to atoms in the same image of a molecule. CAMPARI will occasionally warn users about cases where an image interaction would be within the cutoff distance, but these warnings are not part of all routines (for efficiency reasons). Enabling box-consistent trajectory output may help in diagnosing such issues independently.
   
2. Hard-wall boundary condition (HWBC):
   This option is obsolete and cannot be selected. It may be reactivated in the future to enable simulations in containers with hard, particle momentum-conserving (i.e., reflective) walls.
3. Residue-based soft-wall boundary condition (RSWBC):
   In simulations employing a continuum description of solvent, the resultant density is almost always low, in particular in the limit of simulating just a single macromolecule. In those cases, it may neither be meaningful nor beneficial to introduce additional replicas of the simulation cell. CAMPARI offers to define a system-volume via a soft-wall for such a scenario. Here, the simulated particles are prevented from leaving a simulation container (most often a spherical droplet) by an applied boundary potential modeled as follows.
   Spherical case:
   
   E_BND^Sphere = Σ_i k_BND·H(r_i-r_D)·(r_i-r_D)²
   
   Here, r_i is the distance from a suitable reference point on residue i to the simulation sphere's origin, r_D is the sphere's radius, k_BND is the force constant and H(x) is the Heaviside step function.
   Rectangular box case:
   
   E_BND^Box = Σ_i Σ_j=1..3 k_BND·H(|d_i,j|-L_j/2)·(|d_i,j|-L_j/2)²
   
   Here, d_i,j is the j^th element of the distance vector of the reference point on residue i to the center point of the box (note that by convention the lower left corner serves as origin of the box), and the L_j are the side lengths.
   Nonperiodic cylinder case:
   
   E_BND^Cylinder = Σ_i k_BND·[H(|d_i,z|-h)·(|d_i,z|-h)² + H(r_i,xy-r_C)·(r_i,xy-r_C)²]
   
   Here, d_i,z is the z-element of the distance vector of the reference point on residue i to the middle of the cylinder (cylinder axis always aligns with z-axis), r_i,xy is the distance of the same point from the cylinder axis in the xy-plane, and h and r_C are height and radius of the cylinder, respectively.
   Partially periodic cylinder case:
   
   E_BND^{Periodic Cylinder} = Σ_i k_BND·[H(r_i,xy-r_C)·(r_i,xy-r_C)²]
   
   The nomenclature is the same as for the nonperiodic cylinder. The partially periodic cylinder has a periodic boundary in the z-direction, and the corresponding term is thus missing from the boundary potential.
   In general, hard-wall boundaries may be approximated by letting k_BND → ∞. This will deteriorate integrator stability in gradient-based simulations, however. Choosing a RSWBC means that the boundary penalty is imposed on the reference atom of each residue (for peptide residues this is always Cα). This can lead to potential boundary artifacts with parts of large residues sticking out of the sphere and hence being deprived of interactions with smaller residues. Additionally, it must be pointed out that soft-wall boundary conditions lead to somewhat ill-defined system volumes since the code assumes the fixed volume inside the boundary to be the system volume whereas realistically it should be slightly extended depending on temperature and stiffness. The latter is not easily computed, however, since 1) the purely kinetic (entropic) pressure may be altered by the presence of non-rigid molecules, and 2) the virial pressure is generally unaccounted for. Hence, an exact volume is only recovered in the limit of an infinitely stiff boundary (HWBC).
4. Atom-based soft-wall boundary condition (ASWBC):
   This option is analogous to the previous (RSWBC) option only that the boundary term is computed for each atom in the system rather than for the reference point on each residue in the system (formulas are not repeated). This will minimize artifacts of the aforementioned type, but it is also the most expensive droplet BC to compute. Because multiple atoms will contribute to the boundary penalty for each residue, it is generally recommended to use smaller force constants than for the RSWBC. This boundary condition is also underlying the compartmentalization potential, which is a set of additional inner, planar boundaries.

SHAPE

This keyword lets the user specify the shape of the simulation container the system is enclosed in. The available choices for SHAPE depend on the boundary condition selected (→ BOUNDARY). At the moment, choices are as follows:

1. Rectangular cuboid (= rectangular parallelepiped): This container is supported with both periodic boundary conditions (PBC) and soft walls.
2. Sphere: This container is only available with soft walls.
3. Cylinder: This container is available with soft walls or with partially PBC along the cylinder axis, which always aligns with the z-dimension, and atom-based soft walls elsewhere (BOUNDARY is 1).

All simulations in three-dimensional PBC have to use rectangular cuboids (extensions to general triclinic boxes may be considered in the future). Conversely, simulations in soft wall boundary conditions can use all available containers. Note that the geometry of a finite (nonperiodic) cuboid or cylinder is fundamentally mismatched with the radial (centrosymmetric) nature of most nonbonded interactions. Partial periodic boundary conditions are at the moment only supported for the cylinder as described above.

ORIGIN

This keyword lets the user set the origin of the simulation system as a vector of three elements (x, y, and z). The reference point depends on the container's shape and is its origin for a sphere, its lower left corner for a cuboid, and the center of its central circular cross section for a cylinder. Note that for simulations started from "scratch" (no structural input), this keyword is mostly irrelevant. There are two things to consider, though:

1. Structural output may be compromised if values are used that are far away from zero. This is because binary trajectory files and in particular the strictly formatted PDB-files have finite representation widths and fixed units (Å or nm) such that output may be severely compromised (for PDB files, format adjustments to nonstandard formats are available, see PDB_OUTPUTSTRING and PDB_INPUTSTRING). It is therefore recommended to adjust this keyword such that the minimum and maximum values for Cartesian coordinates (largest dimension) are symmetric around the origin of the coordinate system.
2. If structural input it used, it is strongly recommended to match the settings for ORIGIN to that implied in whatever structural input is provided. In droplet BC, it may otherwise occur that parts of the system overlap with the ill-placed droplet boundary and that their internal arrangement is destroyed or that the simulation explodes during the first few steps of simulation.

Note that the input vector is simply specified as three blank-separated floating point numbers.

SIZE

This keyword allows the user to define the size of the simulation container. Depending on its shape, SIZE takes on alternative meanings. If the system volume is a rectangular cuboid (SHAPE is 1), a vector of three floating-point numbers is read in that specifies the three side lengths of the cuboid in the x, y, and z-directions, respectively. If the system volume is spherical (SHAPE is 2), just one real number is needed that specifies the sphere's radius. Finally, if the system volume is cylindrical (SHAPE is 3), two floating point values are read and assumed to be the radius and height of the cylinder, respectively. Note that highly asymmetric boxes and very short, partially periodic cylinders can place very stringent settings on cutoffs since it is generally the shortest dimension that matters.

SOFTWALL

This keyword sets the harmonic force constant both for the residue-based and the atom-based SWBCs (see BOUNDARY). It is to be provided in units of kcal·mol^-1Å^-2 and corresponds to parameter k_BND in the equations above. It is currently not possible to disable the evaluation of this potential by setting SOFTWALL to zero. Both very small and very big values can be detrimental to a simulation by producing an ill-defined volume (small values) and creating large forces (big values), respectively.
SOFTWALL also serves as the (completely analogous) force constant for inner system boundaries added by means of the compartmentalization potential.

Integrator Controls (MD/BD/LD/Minimization):

---

(back to top)

TIMESTEP

If any dynamics-based (including hybrid methods of course) method is used, this keyword lets the user set the integration time step for the integrator in units of ps.

CARTINT

This keyword determines - at a very fundamental level - the choice of degrees of freedom that CAMPARI shall sample. The "native" CAMPARI degrees of freedom are the rigid-body coordinates of all molecules and a subset of internal coordinates (almost exclusively freely rotatable dihedral angles). This option is the default and specified by choosing 1 for this keyword. Alternatively, the Cartesian positions of all atoms in the system may serve as the underlying degrees of freedom as is commonly the case in molecular dynamics calculations (option 2). There are several very important limitations and considerations that are mentioned throughout the documentation and reiterated here.

1. CAMPARI does not support the direct sampling of Cartesian degrees of freedom in Monte Carlo simulations. This applies to the MC portion of hybrid simulations as well. While it is trivial to design and implement simple move sets doing precisely that, their efficiency is negligible due to the large amount of motional correlation present between an atom and its immediate molecular environment.
2. Internal space simulations do not require the full amount of bonded interaction parameters that are typically part of molecular mechanics force fields, specifically no bond length terms, and typically no or very few improper dihedral and bond angle terms (→ PARAMETERS).
3. For freely rotatable dihedral angles, there is a distinction between those deemed important vs. those deemed unimportant. Details are listed in the documentation for providing sequence input. These choices generally pertain to methyl groups and/or to bonds describing electronically hindered rotations with identical groups. The resultant sets of degrees of freedom are not always entirely consistent (.e.g., between polypeptide sidechains and their respective small molecule model compounds). Related keywords are OTHERFREQ (MC) and TMD_UNKMODE (dynamics).
4. While unsupported residues pose no problems in the setup of Cartesian coordinates, internal coordinate space simulations need to infer which dihedral angles are rotatable from the input topology. This happens automatically and is described elsewhere. For eligible dihedral angles not identified with standard polypeptide or polynucleotide backbone angles, relevant keywords are again OTHERFREQ (MC) and TMD_UNKMODE (dynamics).
5. The choice of degrees of freedom in internal coordinate space simulations can be customized rather flexibly by introducing additional constraints (see corresponding input file). For MC simulations, the preferential sampling utility offers an additional level of control.
6. Conversely, algorithms to enforce holonomic constraints in Cartesian space simulations are often limited to weakly coupled constraints (see SHAKEMETHOD for details). This means that it is not (yet) possible to mimic torsional space constraints in a Cartesian space run but that it is possible to follow a typical MD protocol by simulating a flexible macromolecule with some bond length constraints in a bath of rigid water molecules.
7. The existence of virtual sites (effectively atoms with no mass) poses stringent requirements to Cartesian dynamics, in that those sites have to be constrained exactly relative to real atoms. At each integration time step, the forces acting on these sites are transferred to the surrounding atoms, and their positions are rebuilt post facto (see elsewhere for more details). Virtual sites in internal coordinate space simulations can only cause issues if a degree of freedom's effective mass depends solely on such sites. Then, CAMPARI will automatically freeze the corresponding degree of freedom.

TSTAT

This keyword lets the user choose the thermostat to be used to generate an NVT (or NVT-like) ensemble in dynamics simulations using a Newtonian formalism (option 2 or 5 in DYNAMICS). Currently, three options are fully supported:

1. Berendsen weak-coupling scheme (reference):
   This is a deterministic and global velocity rescaling scheme which creates an exponential relaxation toward the target temperature. The velocity rescaling factor is computed for each coupling group (see TSTAT_FILE) according to:
   f_v,i² = 1.0 + (δ_t/τ_T)·[ (T_target/T_i) - 1.0 ]
   As is apparent, whenever the instantaneous group temperature (T_i) matches the ensemble target (T_target), velocities are not rescaled (f_v,i is unity). Any deviations from T_target will lead to a systematic rescaling for all velocities that are part of the coupling group toward the target with a relative decay rate of τ_T (→ TSTAT_TAU). If τ_T approaches the discrete time step (δ_t), the relaxation becomes instantaneous. Note that the coupling of subparts of the system to essentially different thermostats is a largely obsolete method used in early days of simulations to prevent obscure freezing events sometimes encountered when the system is effectively partitioned into subsystems with very different levels of integrator stability, noise, and inherent relaxation. Then such an approach may circumvent the most dramatic pitfalls resulting from the inherent incorrectness of the weak-coupling scheme (and masking said incorrectness in the process). It is crucially important to realize that the Berendsen thermostat does not generate a well-defined ensemble and that the method only relaxes "safely" to the microcanonical one for τ_T approaching infinity. The quenched fluctuations observed in the Berendsen scheme may severely distort results on fluctuation-sensitive computations such as free energy growth calculations (see GHOST). Since the Berendsen scheme is a global coupling scheme, it is compatible with holonomic constraints but prone to equipartition artifacts (see option 4 below) like the freezing of subparts of the system mentioned above. Global thermostats are generally good at preserving velocity cross-correlations, which is an important property for tightly coupled systems, e.g. dense, polar liquids. They are also good at absorbing integrator (discretization) error.
2. Andersen scheme (reference):
   The Andersen thermostat is a stochastic thermostat which introduces "collisions" re-randomizing the velocity associated with a given degree of freedom to one coming from the ensemble at that given temperature. This method is shown to sample the canonical ensemble and one of the recommended options for any calculation sensitive to the details of ensemble fluctuations. Implementation-wise, it works by re-assigning the velocity for each degree of freedom at each time step with a probability equivalent to δ_t/τ_T. This effectively gives rise to a "bath"-induced relaxation over a timescale τ_T. Note that implementations in other software packages may synchronize the application of these velocity resets. This is not the case in CAMPARI where each degree of freedom is treated independently. In Cartesian space, this means that each dimension for every atom is coupled individually, i.e., the velocity resets are uncoupled. As a consequence, the Andersen thermostat as implemented currently is incompatible with holonomic constraints (while the constraints are maintained, their imposition systematically bleeds kinetic energy from the resets leading to an artificial cooling). Without constraints and much like in Langevin dynamics, a remaining concern here can be the artificial loss of velocity correlations between multiple particles. Unlike in Langevin dynamics, however, the stochastic process is uncoupled and instantaneous, which has an additional downside. If there are noticeable discretization errors (there usually is), one cannot rely on the Andersen thermostat to absorb them in the same way that a globally coupled thermostat does. This is (most likely) because errors accumulating locally must also be dissipated locally where in a global scheme they are dissipated globally.
3. Extended ensemble methods:
   Methods such as those by Nosé-Hoover, Martyna-Tobias-Klein, or Stern are currently not supported, but may be in the future. They often show poor relaxation behavior due to coupled oscillations in particular in the NPT ensemble, which they are most useful for.
4. Bussi et al. scheme (reference):
   This thermostat can be thought of as a hybrid approach of the Nosé-Hoover and Berendsen thermostats. It preserves the exponential relaxation kinetics of the weak-coupling scheme if the ensemble target is far away but introduces fluctuations to the kinetic energy such that at equilibrium the global re-scaling does not quench fluctuations. This thermostat is currently the one offering the most general support for different classes of system and different types of degrees of freedom and thus the recommended option in most applications. The implementation is that of evolving the kinetic energy via an auxiliary stochastic dynamics much like the Langevin piston for pressure coupling does. Here:
   f_v,i² = e^-δ_t/τ_T + f_T,i(1 - e^-δ_t/τ_T) (R₁² + R_Γ,Nf,i-1) + 2e^{-0.5δ_t/τ_T}·R₁[ f_T,i(1 - e^-δ_t/τ_T) ]^0.5
   With:
   f_T,i = N_f,i^-1·(T_target/T_i)
   Here, N_f is the number of degrees of freedom in the respective coupling group, R₁ is a normal random number with mean of zero and unity variance, and R_Γ,Nf,i-1 is a random number drawn from the gamma distribution with outside scale factor of 2.0 and shape of (N_f,i-1)/2. Like any thermostat acting globally, there is a higher risk for equipartition artifacts than for thermostats/methods that couple degrees of freedom individually. Equipartition artifacts are generally more likely to occur in weakly coupled and inhomogeneous systems, e.g., a peptide in a bath of ions in an implicit solvent model.

The user is reminded again that this keyword is ignored for all simulations not relying on explicit thermostats (like Monte Carlo or stochastic dynamics runs → DYNAMICS).

TSTAT_TAU

If the simulations is performed in the NVT -ensemble and if Newtonian dynamics are used, this keyword allows the user to set the key parameter of the employed thermostat, i.e. its coupling (decay) time, τ_T, in units of ps (the default is 1.0ps). Note that it is really the ratio of the time step δ_t (see TIMESTEP) and this number that matters, hence TSTAT_TAU cannot be less than the integration time step.

TSTAT_FILE

If the simulations is performed in the NVT -ensemble and if Newtonian dynamics are used, this keyword sets name and location of an optional input file for defining thermostat coupling groups. These are meaningful only if the Berendsen weak-coupling or the Bussi et al. scheme is used (options 1 or 4 for TSTAT). For details, the user is referred to the description of the input file itself.

SYSFRZ

This keyword controls the removal of net drift artifacts in dynamics runs (which are primarily relevant for fully ballistic MD). Predominantly in periodic boundary conditions (see BOUNDARY), it can happen that all kinetic energy is transferred into global translations or rotations of the system. This collective "degree of freedom" is typically friction-free and therefore represents a stable trap for the system's kinetic energy to accumulate in. Such behavior will give rise to grossly misleading results (the effective ensemble sampled has a much lower temperature). This can be avoided by periodically removing such global motions. For translational displacements, this is easy, but for rotational motion problems arise if subensembles have access to modes that are quasi friction-free themselves. This is often the case in mixed rigid-body/torsional dynamics and at the moment not dealt with properly.
Choices are as follows:

1. No removal of global motions is performed (the safest setting for most applications).
2. CAMPARI will attempt to only remove translational motion of the system.
3. CAMPARI will attempt to remove both global translation and global rotation (this option should be used with caution and is also automatically disabled if certain types of constraints are in use).

Note that CAMPARI writes drift values (fractions of kinetic energy consumed by global motions) to the log output in dynamics calculations. This output can be used to diagnose whether drift removal is necessary and/or working. Importantly, these are the values before application of the instantaneous correction, i.e., they will not typically be completely negligible (this depends on the dynamics equation in use, temperature coupling, the directionality of forces, etc.). Note that drift corrections are more difficult to interpret in the presence of any external potentials, i.e., those that depend on absolute spatial coordinates (currently these are possible boundary potentials, spatial density restraints, and compartmentalization potentials.

TMD_INTEGRATOR

If a simulation is performed in mixed torsional/rigid-body space that contains a Newtonian dynamics portion, then this keyword allows the user to choose between (currently) two basic integrator variants. All integrators are derived from the following discrete scheme that relies on the aforementioned assumptions, i.e., a diagonal mass matrix (equations of motion formally decoupled) and the accuracy/correctness of the total kinetic energy expressed in terms of this diagonal mass matrix. Then, we can define pseudo-symplectic conditions as shown below for a (rotational) degree of freedom with index k:

I_k(t₂)ω_k(t₂)² - I_k(t₁)ω_k(t₁)² - δt [ω_k(t₁) + ω_k(t₂) ] F_k(t_1.5) = 0

Here, δt is the integration time step, I_k denotes the diagonal element of the mass matrix for the kth degree of freedom (function of time), ω_k is the associated angular velocity, and F_k denotes the deterministic force projected onto this degree of freedom (torque). The projection yielding the torques and the mass matrix elements are computed with recursive schemes, i.e., they operate in linear time with the number of atoms in the molecule (more or less irrespective of how many rotatable bonds there are). More information on this recursive scheme can be obtained indirectly with the help of keyword TMDREPORT. The above scheme defines a quadratic equation that has a maximum of two solutions for ω_k(t₂) (formula omitted). The correct one must be picked (which may be difficult), and an alternative must be defined if no solutions are possible. For both purposes, we use a well-defined approximation to the full solution that yields:

ω_k(t₂) ≈ [I_k(t₁)/I_k(t₂)]^1/2 ω_k(t₁) + δt F_k(t_1.5)/I_k(t₂)

This solution is always available and can be used to pick the correct solution amongst two alternatives for the full quadratic equation (simply as the closer one). The setting for TMD_INTEGRATOR determines whether the correct solution to the quadratic equation should be used whenever possible (option 1), or whether the approximation is used exclusively (option 2, which is the default for historical reasons). As written, the equations still contain the problem that they require knowledge of I_k(t₂), whereas only the half-step mass matrix elements (which are structural quantities) are available in a typical leapfrog scheme. If the I_k are slowly varying functions in time, a simple approximation solving this problem is to allow a lag of half a time step:

ω_k(t₂) ≈ [I_k(t_0.5)/I_k(t_1.5)]^1/2 ω_k(t₁) + δt F_k(t_1.5)/I_k(t_1.5)

This is again written for the approximative version (setting 2). The resultant leapfrog integrator is extremely simple and efficient, and it is obtained by setting the related keyword TMD_INT2UP to 0. However, at each integration time step, we can also take a half-step guess using a similar approximation to obtain a value for all the I_k(t₂). This is done by explicitly perturbing the coordinates and recomputing just the mass matrix elements (little additional cost for all but tiny or trivial systems). With the values obtained, we can integrate the second equation above as written (this is obtained by setting TMD_INT2UP to 1). While theoretically more accurate, this variant can be noisy due to the extrapolation of the masses. In practice, for systems with very small and quickly varying I_k (such as rigid water molecules), performance is similar for all four pairings (TMD_INTEGRATOR 1 or 2, TMD_INT2UP 0 or 1), and reveals that additional corrections are recommended if the rate of change of the I_k is high (see below). Conversely, if the rate of change is negligible, all possible settings obtainable by combinations of the two keywords mentioned here relax to the exact same integrator (standard leap-frog in rotational space). This covers the special case of linear (translational) degrees of freedom, which have constant mass.
Note that this keyword is currently irrelevant for stochastic dynamics (always uses a derivation analogous to the last equation above), but that it is relevant for the stochastic minimizer. Another crucial keyword relevant to TMD integrators in general is ALIGN. Specifically for the Newtonian case, coupling parameters become relevant as well (TSTAT and TSTAT_TAU in particular).

TMD_INT2UP

If a simulation is performed in mixed torsional/rigid-body space that contains a Newtonian dynamics portion, then this keyword allows the user to control the number of incremental velocity update steps used to improve integrator stability for cases with quickly varying elements of the mass matrix (see above). The cases of 0 and 1 have already been covered in the documentation on TMD_INTEGRATOR. The remaining options assume that values for the diagonal elements of the mass matrix at times t₁, t_1.5, and t₂ are available explicitly (as in: computed directly from coordinates) when trying to compute the updated angular velocity for a degree of freedom at time t₂. Rather than solving the velocity update step in one step, the interval from t₁ to t₂ is instead divided into TMD_INT2UP subintervals, and the velocity is updated incrementally for each subinterval. If TMD_INT2UP is larger than 2, additional values are obtained by linearly interpolating between explicit values at the three times. This is why it is recommended to set this keyword to multiples of 2, and this is also why the added benefit becomes successively smaller. A recommended value is 4. Note that this only matters for velocity updates, and that the torque is assumed constant over the entire interval (F_k(t_1.5) above). As a result, this option does not notably alter speed for a system of appreciable size and is not at all equivalent to a change in integration time step.

FUDGE_DYN

If a simulation is performed in mixed torsional/rigid-body space that contains a dynamics portion, this keyword, when set to "1", enables an automatic adjustment of inertial masses. Because the equations shown above do not involve an explicit coupling of inertial masses to each other (the mass matrix is assumed diagonal), they can be scaled independently. As long as the scale factor is constant, this effectively increases the rotating mass for an individual degree of freedom without altering that of others. This effect cannot be achieved by atomic mass patches because atoms contribute to the inertial mass of more than one degree of freedom, including rigid motion of the molecule in question.
If FUDGE_DYN is 1, CAMPARI will, based on the initial structure it has of the system, scan all rotational degrees of freedom and identify those with inertial masses of less than 6.0gŲ/mol and calculate and store a constant scale factor that brings the inertial mass up to 6.0gŲ/mol. This factor is never adjusted again and preserved on restarts, which is critical. For normal molecular systems, the correction affects terminal moieties involving just hydrogen atoms (e.g., torsions in methyl or hydroxyl groups) and rigid rotations of molecules composed of a single heavy atom plus hydrogen atoms (like methane and water). Dihedral angles across nearly colinear arrangements may also be picked up (like in alkynes) although they may also be frozen (based on a numerical threshold). Finally, molecules with tiny overall masses are excluded from this procedure as this signifies to CAMPARI that the parameters, units, and/or systems are meant to be nonstandard.

THRESHOLD_TEMP

If a simulation is performed that contains a dynamics portion, this keyword allows the user to implement an artificial safety net to protect against a numerically unstable simulation. It works by defining an upper threshold temperature. As soon as the net system temperature exceeds this threshold, CAMPARI will rescale all velocities such that the exact target temperature is set instantaneously. There are several caveats to be weary of:

1. Since the size of temperature fluctuations scales inversely with the number of degrees of freedom, the threshold should be system-specific.
2. For systems with many degrees of freedom, a local instability will lead to the undesired behavior of cooling down large parts of the system well below the target temperature.
3. If there is a settings-related reason for the instability (e.g., time step issues), it will reoccur and ultimately lead to an uninterpretable result or a crash.
4. An ensemble rescaled once or more times using this technique has no obvious thermodynamic interpretation. One should keep in mind, however, that all discrete integration schemes implemented here yield ensembles that are, rigorously speaking, not the correct thermodynamic ones (see this reference for further information).
5. Generally speaking, as the conformation is not altered, the use of this keyword offers no guarantees that an initially unstable simulation will survive - it simply increases the chances.

From the above, it should be clear that the first and foremost application for this type of thresholding is in high-throughput calculations where detailed supervision is costly (e.g., in a small molecule screen), in exploratory runs, and in relaxation attempts for poorly equilibrated starting structures. It should generally not be in use for any type of production simulation where (approximate) correctness of the thermodynamic ensemble is required. The default value is infinity.

THRESHOLD_INCR

If a simulation is performed that contains a dynamics portion, this keyword allows the user to define a criterion for when such a gradient-based propagation is deemed numerically unstable. The keyword is interpreted as a fractional (relative) step size. As soon as any propagation makes a step larger than the resultant effective maximum increment, a premature termination condition is triggered. For rotational motion (only relevant in internal coordinate spaces, the effective maximum increment is THRESHOLD_INCR·360.0° whereas for translational motion it is THRESHOLD_INCR·V^1/3 where V is the volume of the simulation container.
In production simulations, this keyword is useful primarily to avoid cryptic terminations due to integrator instability. The main actual use of the keyword is in small molecule screens: here, an uncontrolled floating point exception would lead to the termination of the entire process, and relying on THRESHOLD_INCR instead allows CAMPARI to continue with the run. The default value is 1.0. For the keyword to work as intended, this value should generally be smaller (0.1 or less).

TMD_UNKMODE

If a simulation is performed in mixed torsional/rigid-body space with a gradient-based sampler (including minimization), then this keyword controls default constraints operating on certain rotatable dihedral angles. A second function of this keyword occurs in structural clustering using a distance function based on dihedral angles (see end of description). As described for sequence input, there is a selection of "native" CAMPARI torsional degrees of freedom that does not include every rotatable dihedral angle in natively supported residues, and for obvious reasons does not include any degrees of freedom within unsupported residues. This keyword therefore controls how to deal with these two categories of additional degrees of freedom. Options are as follows:

0. Only native CAMPARI degrees of freedom are sampled. This will leave any unsupported residues and molecules completely rigid.
1. In addition to native CAMPARI degrees of freedom, all identified degrees of freedom in unsupported residues and molecules will be sampled.
2. In addition to native CAMPARI degrees of freedom, all torsional degrees of freedom in natively supported residues, which are frozen by default, are sampled. This will leave any unsupported residues and molecules completely rigid.
3. All aforementioned classes of degrees of freedom are sampled.

This keyword has a related set of keywords in Monte Carlo simulations (→ OTHERFREQ etc). Note that the keyword is only relevant if either additional set of degrees of freedom is nonempty, .e.g., simulations of a water/methanol mixture are not affected by different settings for TMD_UNKMODE. At the residue level, additional control is offered by virtue of user-requested constraints. The combined information on which degrees of freedom are free and which ones are frozen is obtained with keyword TMDREPORT.
In the context of structural clustering, this keyword co-controls which dihedral angles are eligible as dimensions for a distance function. This applies to cases where a custom request is made through the appropriate input file and to cases where the full dimensionality is ment to be used. Further information is provided elsewhere.

TMDREPORT

This simple logical keyword enables the printing out of information regarding internal degrees of freedom (rigid body, torsional). This file is particularly useful for constructing input for a specific input mode for custom constraints. For every molecule it lists the index of the first atom in that molecule ("Ref."), the total number of atoms ("Atoms"), the total mass ("Mass") after applying all patches, and, if a gradient-based sampler in torsional space is in use, information on whether the (up to) 6 rigid body degrees of freedom are frozen or not ("Frozen"). The order is translation in x, y, and z followed by rotation around x, y, and z axes.
The output on the dihedral angles in the molecule provides the following information. For each atom that, in the Z matrix, corresponds to the definition of a relevant (rotatable) dihedral angle, the structure of the rotation list setup is provided. Specifically, the number of rotating (swiveling) atoms ("Rotat.") is printed out along with their total mass ("Mass"). It is specified how many of the rotating atoms are unique ("Unique") with respect to that atom's rotation list a level above in the hierarchy that contains the rotation list for the present atom entirely ("Parent"). The hierarchy is understood by considering the polymer as a branched chain with a number of tips and a base of motion. This base of motion is defined by keyword ALIGN. Degrees of freedom at the tip have minimal rank (starting at 0) whereas those near the base have maximal rank in the hierarchy ("Rank"). The hierarchy necessitates a particular sequence of processing the individual degrees of freedom ("Order"). The report also provides information on the chemical elements ("Ele.") of the 4 constituent atoms for the dihedral angle (the atom defining the dihedral angle comes last) and on whether the degree of freedom is frozen in torsional space molecular dynamics ("Frozen"). The last bit of information is available only if a gradient-based sampler in torsional space is in use. The report is available irrespective of the type of calculation being performed. Note that keyword ALIGN, while conceptually controlling the same thing, is implemented differently in Monte Carlo moves. This means that most of the columns are representative for the Monte Carlo part only if ALIGN is set to 1. In hybrid samplers, the dynamics portion takes precedence.

FRZFILE

This keyword specifies name and location (full or relative path) of the input file for the selection of molecules or residues for which selected degrees of freedom are to be excluded from sampling by explicit removal from Monte Carlo sampling lists and/or by not integrating equations of motion for them. This means that only such degrees of freedom can be constrained that are in fact explicit degrees of freedom of the sampling scheme in use (see DYNAMICS and CARTINT). If this keyword is not present, no constraints are going to be used beyond the system-imposed ones, which may be sampler-dependent. Note that restricting the Monte Carlo move set defines effective and group-wise constraints not covered here. The same is true for modifying the default picking probabilities for individual degrees of freedom as part of a Monte Carlo move. In Cartesian space, explicit constraints to the x, y, and z coordinates of selected atoms are possible. However, indirect geometric constraints are also supported (differently and independently via SHAKESET).
The input for explicit constraints is described in detail elsewhere. Hard constraints may be necessary for specialized applications, for example when one attempts to just re-equilibrate the sidechains in a folded protein while leaving the fold intact. In general, it will be possible to use restraints (see for example SC_TOR or SC_DREST) as alternatives. Those allow the selected degrees of freedom to respond and fluctuate around a stable equilibrium position. Another example of a highly specialized application would be the simulation of a two-dimensional system.
Note that constraint requests are not entirely arbitrary, and that the level of control being offered depends on the sampling engine and the chosen input mode. In general, it may prove challenging to match custom constraints exactly when a hybrid sampling approach is used. This means that the sampled sets of degrees of freedom between Monte Carlo and dynamics segments may differ slightly, which is sometimes desired. An example is the sampling of five-membered rings, which are frozen in internal coordinate dynamics but can be sampled by a dedicated Monte Carlo move (→ PKRFREQ and SUGARFREQ). Furthermore, introducing constraints may prohibit certain MC samplers from being applied not just to the residues carrying the constraints but surrounding ones as well (such as concerted rotation methods → CRFREQ) due to underlying and conflicting assumptions. Lastly, CAMPARI will exit with an error if user-selected constraints deplete the sampling list for a given MC move type entirely. Here, it is requested of the user to explicitly adjust the move set, since otherwise these moves would have to be converted to another type that is not necessarily desirable (note that this still happens if moves are requested that the chosen system simply does not support).

FRZREPORT

If explicit coordinate constraints are used (→ FRZFILE), this keyword acts as a simple logical whether or not to write out a summary of the constraints in the system to log-output.

SKIPFRZ

If constraints are used (→ FRZFILE) in torsional space simulations, this keyword gives the user some control over the calculation of effectively frozen interactions due to constraints. In Monte Carlo simulations (see DYNAMICS), incremental energies are computed by only considering the parts of the system that move relative to one another. This automatically addresses constraints. Conversely, in dynamics the total system energy and forces are calculated at each step. If this keyword is set, interactions between parts that have no chance of moving relative to one another (relative orientation completely constrained) will no longer be considered. Note that the potentials rigorously have to be (at most) pairwise decomposable for this option to be available (e.g., the polar term in the ABSINTH implicit solvation model is not strictly pairwise decomposable; → SC_IMPSOLV and SCRMODEL). Usage of this keyword can significantly accelerate dynamics runs or minimization runs in heavily constrained systems (such as ligand optimizations within a rigid protein binding site). Note that any reported energies do not contain the frozen contributions either if this option is chosen.

MOL2FOCUS

If a small molecule screen is performed and any sampler in internal coordinate space is used, this keyword controls which degrees of freedom are available for sampling in the remainder of the system (excluding the screened molecule). Specifically, the use of this keyword allows the addition of extra constraints, e.g., those specified through keywords TMD_UNKMODE and FRZFILE. It can never be used to remove existing constraints. This keyword is ignored in scoring mode.
Two options are currently available.

1. If the value given is positive, this is interpreted as a threshold distance in Å. Any torsional or rigid-body (IMD) degree of freedom moving any atom that is within this distance from any atom of the reference ligand, i.e., the first one in the MOL2 input file, will remain free if it is free to begin with. All the other ones will be frozen unless they are already frozen. Because of the definition, small values will be enough to keep the immediate vicinity of the ligand flexible. This will include main chain degrees of freedom if those are not constrained by other means.
2. If the value is given as negative, this is interpreted as follows. Any IMD degree of freedom to remain free must only move atoms that are all within the (absolute value of) the value given in Å of all atoms of the reference ligand, i.e., the first one in the MOL2 input file. This is by definition fairly restrictive and generally requires larger values to prevent everything from being frozen.

A major caveat is that the dynamic extent of flexibility in the remainder of the system is determined solely by the position of the reference small molecule, which is taken as either first one in the MOL2 input file or the one in the dedicated input file given through MOL2_REFMOL. This means that the coordinates of this entry have to be appropriate in relation to the rest of the system (provide a properly "bound" pose) for the option to work as intended. Of course, it is always possible to set values to achieve the two straightforward reference cases of constraining the entire remainder of the system (small negative value) or of keeping everything flexible (large positive value). Because of the dynamic nature of the constraints, an output file is written that can be used as an input to FRZFILE to reproduce these constraints for everything but the small molecule exactly. This file is called MOL2FOCUS.frz. The transfer of these constraints to Monte Carlo move sets works for all simple moves but not for polypeptide pucker moves, sugar pucker moves, and any concerted rotation moves including those for nucleic acids.
With additional coordinates flexible, it may be essential for the CAMPARI output files to document these additional coordinates. This is achievable either with the help of keyword MOL2PDBMODE or in the mol2 output file itself (by means of keyword MOL2AUXINDEX). The former solution is often impractical since the entire systems is written and the output is to individual files. The latter solution is particularly convenient if the special option "automatic" is chosen for MOL2AUXINDEX, which ensures that only a near-minimal set of extra coordinates is written exactly in response to the present constraints. Note that any flexibility on the receptor side means that poses missing this information can no longer be analyzed meaningfully, e.g., in a (re)scoring run.

MOL2FRZMODE

If a small molecule screen is performed and a sampler in internal coordinate space is used, this keyword offers some control over how torsional degrees of freedom are sampled in the screened molecules. For runs in Cartesian space, there is currently no specific customization available.
Since the screened molecules are always single-residue molecules with the same index for the first atom, rigid-body motion can be controlled with maximum flexibility using a custom constraint input file (mode 'A'), and it is thus not covered by this keyword. For both Monte Carlo runs, basic settings are governed by the move set controls and the preferential sampling utility. The major difference between Monte Carlo and gradient-based runs is that the MC move set's prior state may prevent some degrees of freedom to be added. For example, if single dihedral pivot moves on unsupported residues are not enabled to begin with, options 1-3 below will not change this. Note that MOL2FRZMODE is processed but only diagnostically relevant in scoring mode.
The options are as follows:

0. Constraints are left as is, i.e., they are determined by the setting for TMD_UNKMODE, custom constraints, and, for Monte Carlo, by the move set choices.
1. Only those dihedral angles rotating only hydrogen atoms are left free (the detection of a hydrogen atom is based on mass, which is ultimately dependent on the type matching algorithm). All of the eligible dihedral angles receive the same sampling weight in Monte Carlo.
2. All dihedral angles are left free. In Monte Carlo, the same sampling weights are proportional to the number of atoms being rotated except if there are more than 3 (below, the weights are flat).
3. All dihedral angles are frozen. This is rarely useful and may lead to crashes.

Note that all choices except 0 can override settings determined by keyword TMD_UNKMODE in a gradient-based calculation.

SHAKESET

It is standard practice in molecular dynamics simulations in Cartesian space to employ holonomic constraints such that the system evolves according to Gauss's principle of least constraint. The reader is referred to the literature as to what exactly constitutes a time-reversible, symplectic integrator if holonomic constraints are enforced. In general, it will possible to formulate an algorithm which at least is drift-free, has some target precision for the constraints, and is approximately symplectic when the microcanonical ensemble is in use.
The idea behind holonomic constraints in molecular dynamics is to eliminate fast vibrational modes in the system to allow for a larger integration time step to be used. This keyword allows the user different choices for which holonomic constraints to employ as follows:

1. No holonomic constraints are used.
2. All "native" bonds to terminal atoms with a mass of less than 3.5 a.m.u. are constrained in length. A terminal atom is defined as any atom bound to exactly one other atom. "Native" means that only bonds consistent with the assumed molecular topology (code-internal) are considered. This selection will usually constrain all bonds to hydrogen atoms.
3. All "native" bonds of any type are constrained in length. This does include bonds formed by virtue of chemical crosslinks.
4. All "native" bonds of any type are constrained in length as in mode 3. In addition, several bond angles are constrained explicitly. For a molecule free of rings of size 6 or less all bond angles are constrained (this also constrains improper dihedral angles at trigonal centers). For molecules with rings of size 6 or less, ring-internal bond angles are generally omitted. Note that more bond angles can be formulated at a tetrahedral site than constraints are needed, and that - system-dependent - redundant constraints may be created (which may be harmful). This option is only supported for the standard SHAKE constraint algorithm at the moment.
5. This is nearly identical to option 4. However, bond angles are constrained by additional distance constraints rather than explicitly. This means this option is theoretically available for constraint algorithms other than SHAKE.
6. An input file is read and used to derive the list of constraints. Note that it is possible to derive intra- and intermolecular long-distance constraints that way (geometric information will be taken from starting structure), but that those will very easily cause CAMPARI to crash.

After assembling the initial list, CAMPARI will parse this list and identify all sets of constraints that are coupled. Choices for how the actual values for the constrained distances and angles are set are provided by keyword SHAKEFROM. Two constraints are coupled if any atom is shared. Groups of coupled constraints have to be solved simultaneously using some numerical scheme and analytical solutions are generally not available. An individual uncoupled constraint can always be solved analytically and poses no particular difficulties. A specific case are the three coupled constraints in rigid water molecules, for which the analytical SETTLE algorithm has been derived. In these and similar cases, CAMPARI will substitute the numerical scheme with the analytical version for reasons of efficiency and accuracy regardless of specifications otherwise. However, in most cases, the constraint set specified via this keyword will not make water molecules rigid per se, and for this case a dedicated keywords exists (→ SETTLEH2O). Note that the use of virtual sites (sites with no mass) is only permissible if they have rigid geometry, and if their positions can be constructed from real atoms with smaller index values. Choices for this keyword, and the auxiliary keywords SETTLEH2O and SHAKEFILE will have to reflect this requirement.
The cost, accuracy, and applicability of constraint algorithms all scale poorly with the level of coupling. Options 4 and 5 from the list above will therefore be usable only in special cases (→ SHAKEMETHOD) such as systems without any rings or planar, trigonal centers. For specific applications using angle constraints, we strongly recommend defining a minimum set of distance-based constraints via option 6 above. This has the best chance to succeed.

SHAKEFILE

If SHAKESET is set to 6, this keyword specifies the name and location of the file defining user-selected holonomic constraints to be enforced during the simulation. Its format and requirements are documented elsewhere.

SETTLEH2O

This keyword allows the user to append/modify the constraint set selected via SHAKESET to replace all preexisting constraints acting on three-, four-, or five-site water molecules (SPC, TIP3P, TIP4P, TIP4P-Ew, or TIP5P) with constraints that completely rigidify each water molecule. It acts as a simple logical and is turned on by default since CAMPARI as of now does not support explicitly any inherently flexible water models. This means that a setting of 2 or 3 SHAKESET for a calculation in explicit water will still constrain waters to be rigid, and therefore correspond to a standard (and - for the supported water models - correct) simulation setup. Specifying this keyword and setting it to anything else but 1 will disable this override. Note that for water models possessing virtual sites (all four- and five-site models), it is assumed that the extra sites have no mass (see below). If this is not the case, the use of the analytical SETTLE algorithm for water is no longer possible, and the more complex set of constraints may no longer be solved efficiently (or may no longer be solved at all).

SHAKEFROM

This keyword allows the user to control how the actual values for the set of holonomic constraints are determined at the beginning of simulations in Cartesian space. There are currently the following options:

1. Irrespective of structural input, all distance constraints of atoms bound covalently to one another are taken directly from the (hard-coded) CAMPARI default geometries that use, wherever possible, databases of high-resolution crystallographic structures of biomolecules (see for example the reference by Engh and Huber). For indirect angle constraints, i.e., constrained distances of atoms separated by two covalent bonds, the bond angle and two bond lengths in question are used to compute the effective length in similar fashion. For explicit angle constraints the reference value can be used directly. Lastly, simulations of unsupported residues require the structural input to be used directly (see comments on option 3 below for implied caveats). This option is currently the default.
2. Irrespective of structural input, CAMPARI will try to reconstruct the required constraint lengths from the minimum positions of bonded potentials (see SC_BONDED_B and SC_BONDED_A) that are provided by the force field in use. As for option 1, this extends to indirect and explicit angle constraints. If terms are missing in the force field, covalent distances are taken from the default CAMPARI geometry as for option 1. This option is the recommended one for "standard" molecular dynamics calculations. Note that patches to bonded parameters are recognized and respected in this context.
3. CAMPARI takes all reference values for constrained degrees of freedom directly form the structure the simulation is started in. This requires no adjustments but comes with caveats. Since input in pdb format is of limited precision, the various bond lengths and angles can only be extracted to the same precision. This means that constraints that are chemically identical will be set to slightly different values (e.g., the C-H bonds in a methyl group), which can cause small artifacts. For bond lengths involving hydrogen, rebuilding is an alternative to circumvent this problem (see PDB_HMODE). A second problem arises due to the lack of reproducibility caused by the limited precision. Specifically, simulations started from two different and minimized conformations of the system will end up using different values for the constraints. A more extreme version of this problem is encountered when starting simulations from snapshots of other simulations, in which the constrained degrees of freedom had been left free to move (this exceeds the mere precision effect). Due to these caveats, it is not recommended to use this option. Note that CAMPARI will have to use values defined by structural input for cases where no other information is available.

With file-based input to SHAKESET, it is possible to constrain distances between atoms that are not connected by just one or two covalent bonds. Since neither CAMPARI nor force fields prescribe "correct" distances to such pairs, a constraint of this type is always dependent on structural input (if input is absent, the initial geometry generated by CAMPARI according to settings for RANDOMIZE is used, which is rarely useful).
When restarting simulations, this keyword should generally be left unchanged. In case of option 3 being in use, it is recommended to either never supply an input pdb file or to always use the same one supplied as a template. For a simulation started normally, options 1 and 2 above entail the possibility that constrained degrees of freedom are adjusted before the simulation begins. This adjustment is reflected in the reference structure files written at the beginning of each run ({basename}_START.pdb, {basename}_START.int, and {basename}_START.mol2).

SHAKEMETHOD

This keyword allows the user to choose which of the currently implemented algorithms CAMPARI should use to enforce the chosen set of holonomic constraints during a molecular dynamics simulation in Cartesian space. Options are as follows:

1. The standard, iterative SHAKE procedure is used. Coupled constraints are solved iteratively by assuming independence and linearity (Newton's method). SHAKE may converge in very few steps to good accuracy if the coupling is weak (coupling matrix is sparse). This is the only method that currently supports explicit constraints on bond angles (see SHAKESET and SHAKEATOL). It is also the only method that allows parallelization of an individual constraint group across multiple threads if the shared memory (OpenMP) parallelization of CAMPARI is in use, and if the constraint group is otherwise expected to become a bottleneck. Due to the use of Newton's method, SHAKE is not guaranteed to converge if the underlying "landscape" is non-linear due to the introduction of coupling between constraints. Then convergence is only guaranteed within a small enough environment around the actual solution. Therefore, SHAKE places an upper limit on the time step that can be used even though it is meant to allow increases of precisely that time step. Nonetheless, in canonical applications (bond length constraints only), SHAKE will be a reasonably efficient solution, i.e., the desired tolerance can usually be reached within few steps. The main weakness of SHAKE and related algorithms is their inherent inability to enforce planarity at a given site. This is because at a planar site all bond vectors which form the basis set for the application of iterative corrections are part of the same plane, i.e., it is impossible to correct an out-of-plane motion using those vectors. Depending on the exact set of constraints used, SHAKE will require many steps, not converge at all or converge with limited accuracy, and occasionally crash if bond length and angle constraints at a site deem it to be perfectly planar.
2. A mix of the SHAKE and P-SHAKE (see below) algorithms is used in which P-SHAKE is applied only to those constraint groups which are internally entirely rigid. Because P-SHAKE, at least as implemented, fails as a general purpose constraint algorithm, this option is practically obsolete. It can be enabled for testing purposes with the help of keyword UNSAFE.
3. The so-called P-SHAKE (preconditioned SHAKE) procedure is used. In P-SHAKE, SHAKE is augmented by introducing a pre-conditioning step which changes the convergence rate from linear to quadratic. The preconditioning step is a matrix multiplication essentially forming linear combinations from the bond vectors in the constraint vectors. Corrections employed along those new directions minimize the linear error by decoupling the constraints (within the bounds of a linear theory → hence the quadratic and not instantaneous convergence). Unfortunately, this method currently is implemented either inefficiently or incorrectly and does not usually offer a discernible improvement. However, it is also fundamentally flawed as large constraint groups are handled inefficiently due to the requirement of a full matrix multiplication that is needed to increment the coordinates at each iteration step. This operation in P-SHAKE has a cost of 3·n_p·n_c and of only 6·n_c in standard SHAKE. In addition, the matrix used to precondition the procedure, has to be recalculated frequently if a molecule undergoes significant conformational changes (currently hard-coded to 100 integration steps). P-SHAKE is therefore suitable only for enforcing holonomic constraints in small rigid or quasi-rigid molecules that can be solved by SHAKE as well. Just like SHAKE, it fails badly for planar sites (see above). As a consequence of the above, P-SHAKE can be enabled for testing purposes only with the help of keyword UNSAFE (otherwise CAMPARI terminates). When using P-SHAKE, CAMPARI may crash without any indicative messages due to failures in the LAPACK routines used by the algorithm (see installation).
4. The LINCS method is used. LINCS is a linear constraint solver that uses a projection approach. In the end, a matrix equation needs to be solved which requires the inversion of a matrix related to the coupling matrix of the constraints in the group. This is the critical step and grossly ineffective as a general procedure. For sparse matrices, however, the inversion can be performed approximately by a series expansion. It is the order of this expansion and its applicability that will determine the success and accuracy of LINCS. LINCS is generally inapplicable to anything involving bond angle constraints, in particular in all-atom representation. It will work well for loosely coupled groups of constraints. Since the accuracy depends on the unknown convergence properties of an infinite sum, the accuracy of LINCS cannot be tuned directly to yield a specific tolerance for satisfying the constraints. Instead, a combination of the expansion order and a number of corrective iterations controls the achieved discrepancy. To make LINCS more comparable to SHAKE in results, CAMPARI will dynamically adjust the former to achieve the target tolerance. Note that LINCS currently cannot split the workload for an individual constraint group across multiple threads if the shared memory (OpenMP) parallelization of CAMPARI is in use. This can be a performance limitation.

Unfortunately, the constraint algorithm often becomes the weakest link in the integration scheme if the dynamics itself is unstable (for example due to too large an integration time step). Therefore, not all reported failures of the SHAKE or LINCS procedures are due to those procedures. Conversely, if highly coupled constraints are selected via SHAKESET, CAMPARI may produce many warnings pertaining to failed constraint solving attempts that are in fact due to the limitations of those algorithms. In such cases, CAMPARI attempts to subtly change the targets for the constraint values to potentially steer the system toward conditions where solutions are obtained more easily. This - as may be expected - will not usually solve the problem (only delay critical errors), in particular for very large constraint groups. Ultimately, it will be more useful to consider internal coordinate space simulations if high-level constraints are desired (→ CARTINT).
There is an additional issue that arises when virtual sites (technically atoms with no mass) are used, for example in rigid water models like TIP4P. Such sites have to be circumvented by the integration scheme (displacement is dependent on inverse mass), and therefore they have to be exactly constrained with respect to the positions of atoms with finite mass. These constraints cannot be solved within the standard framework (also dependent on inverse mass). Instead, the least constraint solution is obtained by simply rebuilding the positions of these sites with fixed internal geometry. For this to yield a correct integrator, however, the forces acting on the sites need to be remapped to the atoms they are connected to. This is done by decomposing the Cartesian force acting on the site into internal forces, for which compensating terms are added to all the atoms comprising the respective internal degree of freedom. This cancels exactly the net force on the site, and makes integration symplectic. Virtual sites cannot occur in constraint groups that are handled by a method other than standard SHAKE or SETTLE.
Note that if the shared memory (OpenMP) parallelization of CAMPARI is in use, there are most two levels of parallelization, across constraint groups and within a given constraint group. The second level is only available with standard SHAKE at the moment. The first level is balanced dynamically (see THREADS_DLB_FREQ and related keywords for general information on load balancing in CAMPARI).

SHAKETOL

If SHAKE or P-SHAKE are in use (→ SHAKEMETHOD), this keyword allows the user to set the target tolerance for satisfying distance constraints. The tolerance is relative to the target value of the constraint. As soon as the maximum deviation is less than this value, the iteration stops unless it is terminated earlier for other reasons (→ SHAKEMAXITER).
If LINCS is in use, this keyword still has meaning even though the tolerance cannot be set explicitly. Should CAMPARI find that LINCS with the given settings satisfies the constraints significantly worse than defined by this keyword, it will adjust one of the open parameters of the method (→ LINCSORDER) in an attempt to remedy this situation. Similarly, should the opposite occur (LINCS satisfies constraints significantly more accurately than the desired tolerance), the parameter will be adjusted in the opposite direction. All this happens within sane bounds (2-16).

SHAKEATOL

If SHAKE (→ SHAKEMETHOD) is in use with explicit bond angle constraints (→ SHAKESET), this keyword allows the user to set the target tolerance for satisfying angular constraints. The tolerance is absolute and applies to the unitless cosine of the respective angle. As soon as both maximum deviations drop below the threshold tolerances (see also SHAKETOL) the iteration stops unless it is terminated earlier for other reasons (→ SHAKEMAXITER).

SHAKEMAXITER

If SHAKE or P-SHAKE are in use (→ SHAKEMETHOD), this keyword allows the user to alter the maximum number of iterations permissible to the algorithm. Since poor convergence properties are generally indicative of a more fundamental problem, increasing the value for SHAKEMAXITER will rarely be useful. After exceeding this many steps, the algorithm will simply continue with its current solution meaning that - for a good case - constraints will be violated slightly more than specified by SHAKETOL and eventually SHAKEATOL. Note that CAMPARI will then adjust the constraint targets in an attempt to rescue a simulation otherwise doomed. This may not always work and also lead to unwanted drift. Appropriate warnings are provided.

LINCSORDER

If LINCS is in use (→ SHAKEMETHOD), this keyword allows the user to define the initial expansion order for the approximate matrix inversion technique. As mentioned above, the convergence properties of this approximation are not really known and prevent LINCS from satisfying an exact tolerance explicitly. In particular, for a fixed number of corrective iterations, convergence does not improve strongly for comparatively large changes in expansion order. Thus, CAMPARI adjusts the expansion order dynamically if it find that constraints are satisfied significantly better or worse than the desired tolerance provided through SHAKETOL. The allowed range is from 2 to 16, and relative tolerances below 10^-4 will generally require a setting of 2 or larger for keyword LINCSITER. Very small tolerances are feasible and meaningful in CAMPARI since the representation is entirely in 64-bit floating point precision. Warnings are produced if the tolerance is missed, and the average expansion order across all LINCS constraint groups is reported at the end. If this value is large (in particular, if it is close to 16), it is strongly recommended to increase LINCSITER.

LINCSITER

If LINCS is in use (→ SHAKEMETHOD), this keyword allows the user to define the number of iterations for correcting rotational lengthening. Typically, LINCS assumes only one such correction, but the matrix expansion cannot become arbitrarily precise with a single iteration. Thus, this keyword, which defaults to 2 in CAMPARI, can be used to alter the minimum tolerance achievable by LINCS. Since CAMPARI operates entirely in 64-bit floating point precision, meaningful tolerances can be chosen that are comfortably solvable by SHAKE in few iterations yet for which LINCSITER being 1 is insufficient.
CAMPARI will not vary the number of iterations throughout the run, but it will vary the expansion order per constraint group to achieve the desired tolerance. It thus may be computationally less efficient to set LINCSORDER to 1 (depending on tolerance, system, integration time step, etc.) as it requires a larger expansion order.

MINI_MODE

If a minimization run is performed, this keyword lets the user select the method of choice. CAMPARI currently supports three canonical and one nonstandard minimizer. All minimizers can operate either in mixed rigid-body/torsional space, i.e., the "native" CAMPARI degrees of freedom or in Cartesian space; → CARTINT. However, there are algorithmic restrictions that the canonical minimizers (options 1-3 below) only support trivial constraints (see FMCSC_FRZFILE), which is an issue in Cartesian space (rigid water models, etc).
Let us define γ as a vector of base increment sizes suitable for each of the degrees of freedom (partitioned into three classes: rigid-body translation, rigid-body rotation, and dihedral angles; keywords MINI_XYZ_STEPSIZE, MINI_ROT_STEPSIZE, and MINI_INT_STEPSIZE are used to specify each element γ_i). Also, let f_m be an outside scaling factor in units of mol/kcal set by keyword MINI_STEPSIZE. Lastly, we introduce a unitless dynamic step length factor λ. If we now denote the heterogeneous vector of phase space coordinates as x, and the Hamiltonian is written as U(x), then we can write how the system is evolved through either one of four different protocols as follows:

1. Steepest-descent:
   x_i+1 = x_i - λ·f_mγ•∇U(x_i)
   Here, "•" denotes the Hadamard (Schur) product, i.e., simply the element-by-element multiplication. Should the new conformation have overstepped in the direction of steepest descent, λ is iteratively reduced by a constant factor until a valid step is found (lower energy). In case of successful steps, λ is iteratively increased to improve the efficiency of the procedure if the underlying landscape is relatively smooth and flat. Successful steps are used as well to construct an appropriate guess for the initial step size should a complete reset be necessary. This mimics a line search.
2. Conjugate-gradient:
   x_i+1 = x_i - λ·f_m [ γ•∇U(x_i) + f_CG,id_i-1 ]
   f_CG,i = [ ∇U(x_i)·∇U(x_i) ] / [ ∇U(x_i-1)·∇U(x_i-1) ]
   d_i-1 = γ•∇U(x_i-1) + f_CG,i-1d_i-2
   This conjugate-gradient method follows the Polak-Ribiere scheme and augments the steepest-descent prediction by an additional term that is estimated according to the suggestion by Fletcher and Reeves. Much like in steepest-descent, should the new conformation have overstepped, λ is iteratively reduced by a constant factor until a valid step is found (lower energy). In case of successful steps, λ is iteratively increased analogously to what is described above.
3. Memory-efficient Broyden-Fletcher-Goldfarb-Shanno method (L-BFGS) according to Nocedal (reference):
   x_i+1 = x_i - λ· [ H^-1·(γ•∇U(x_i)) ]
   This quasi-Newton approach technically employs the inverse of the Hessian which is typically unknown. However, the L-BFGS method constructs a numerical estimate directly for the matrix product H^-1·(γ•∇U(x_i)) from the recent history of the minimization process. This widely used recursive two-loop scheme has the advantage of i) only requiring very few floating point operations, and ii) not requiring a running guess for the complete Hessian (inverse or not) due to the recursive formulation. Note that the inverse Hessian in our implementation is constructed from γ•∇U(x_i), i.e. has units of mol/kcal throughout, irrespective of which degree of freedom is considered. This means that the factor f_m does not show up in the L-BFGS equation except for the first step (initially or after a reset) when the steepest-descent approximation is used (see mode 1). The usage of (estimated) second derivative information should generally help inform the minimizer of more useful directions to pursue but step size limitations and inadequate guesses of the Hessian may render this potential benefit ineffectual. The reader is referred to the literature for further details.
   
4. Thermal noise quasi-stochastic (akin to simulated, thermal annealing):
   This minimizer couples the system to a variable temperature bath. By changing the coupling parameters, the degrees of freedom are successively brought to a state consistent with a very low temperature ensemble. A similar quench in conditions is used in simulated annealing, a general solution strategy for optimization problems.
   Initially, the system uses a heat bath as defined by the settings for TSTAT and TEMP. The system is then evolved using NVT molecular dynamics in either mixed rigid-body/torsional space or Cartesian space. Depending on initial conditions, this may heat up the system to a variable extent, and the maximum temperature is recorded. After a prescribed fraction of the total simulation steps, the target temperature is successively lowered to the value specified by keyword MINI_SC_TBATH. This interpolation uses a Gaussian function on the normalized time axis such that all interpolation curves can be rescaled in temperature to exactly coincide. Simultaneously, the algorithm measures the rate in change of temperature from the recorded maximum toward MINI_SC_TBATH. If the actual rate appears too slow or too fast, the time constant, τ_T, of the thermostat in use (→ TSTAT_TAU) is successively altered so as to achieve a cooling down of the system to a negligible temperature within the remaining number of available iterations. These alterations happen within bounds of 10 times the integration time step on the low end and the original setting for TSTAT_TAU on the high end.
   This minimization approach employs two convergence criteria as soon as the number of steps specified via MINI_SC_HEAT has passed. During the cooling schedule, the procedure will stop either because the RMS-gradient fell below the threshold (→ MINI_GRMS) or because the target temperature (MINI_SC_TBATH) was reached which - per se - does not provide information on the local gradient. Of course, it may be possible to minimize such a structure further using a canonical approach. Both temperature and RMS-gradient are written to log-output to allow for easy inspection whether the parameters are set reasonably well. As an additional note it must be pointed out that - much like in standard molecular dynamics - runs starting from very unfavorable structures will cause large accelerations which may lead to a catastrophic blow-up of the system. This behavior can be avoided by performing a number of steepest descent minimization moves upfront. This number is set by keyword MINI_SC_SDSTEPS.

In general a minimization run will terminate after either the maximum number of iterations has passed (see NRSTEPS) or after convergence is achieved (see MINI_GRMS). Note that bad combinations of the various step sizes and the convergence criterion can easily lead to non-terminating runs even if convergence is achieved de facto.
In general, minimizations are unlikely to be interesting for on-the-fly analysis. This is because the conformations encountered do not correspond to a meaningful ensemble: neither in terms of coverage nor in terms of relative weights. Nevertheless, all analysis routines are supported and will work assuming that a single step corresponds to a single successful perturbation doing minimization (due to overstepping, the number of energy/gradient evaluations in minimization is usually larger than the actual number of steps: keyword NRSTEPS sets the maximum for the former).

MINI_STEPSIZE

If a canonical minimization run is performed, this keyword acts as a scale factor applied to all conformational increments applied during minimization. It therefore sets the global step size and corresponds to factor f_m in the equations above. It - for technical reasons - has units of mol/kcal to eliminate the energy units of the normalized gradients. There are no canonical rules one can formulate but values significantly less than unity will typically be most appropriate to avoid that the algorithm frequently oversteps in a subset of the degrees of freedom and then has to iteratively reduce the step size. However, step size management is dynamic (consult factor λ introduced in the equations for minimization modes 1-2(3) above). This means that the impact this keyword has may be less than what one would generally expect.

MINI_GRMS

If a minimization run is performed, this keyword allows the user to set the convergence criterion in units of kcal/mol. Since minimization runs can occur in torsional and rigid-body space, the "raw" gradient over all degrees of freedom is unsuitable. CAMPARI utilizes a simple workaround by normalizing all gradients by a basic step size for the respective types of degrees of freedom (see keywords MINI_XYZ_STEPSIZE, MINI_ROT_STEPSIZE, and MINI_INT_STEPSIZE). The resultant, normalized gradient is used to obtain its root mean square (→ GRMS) which is compared to the convergence criterion provided here. Since the normalized gradients assume a default step size, this parameter becomes dependent on them. For unit values for all three base step sizes, values around 10^-2 are recommended. Conversely, in Cartesian space, only MINI_XYZ_STEPSIZE is relevant for the gradient criterion.

MINI_XYZ_STEPSIZE

If a minimization run is performed, this keyword determines a basic step size to be considered for all rigid-body translations of molecules and for all Cartesian displacements of atoms. This value is to be provided in units of Å. Note that this keyword determines the effective initial translation step size in conjunction with MINI_STEPSIZE and that it is mostly needed to be able to handle the different units occurring when minimizing in mixed rigid-body and torsional space. All translational gradients are normalized by this number such that numerical estimates of the Hessian (→ BFGS) or even a meaningful root mean square can be written (→ MINI_GRMS). Note that for simulations in (effective) Cartesian space, it would be possible to combine this parameter with MINI_STEPSIZE to a single step size parameter.

MINI_ROT_STEPSIZE

If a minimization run in mixed rigid-body and torsional space is performed, this keyword determines a basic step size to be considered for all rigid-body rotations. This value is to be provided in units of degrees (compare MINI_XYZ_STEPSIZE).

MINI_INT_STEPSIZE

If a minimization run in mixed rigid-body and torsional space is performed, this keyword determines a basic step size to be considered for all dihedral angles. This value is to be provided in units of degrees (compare MINI_XYZ_STEPSIZE).

MINI_UPTOL

If a minimization run is performed, and if the BFGS method is used, this keyword lets the user choose a tolerance criterion in kcal/mol for accepting uphill steps. At most ten or MINI_MEMORY (whichever one is smaller) such steps will be tolerated until a reset of the estimate of the Hessian occurs. This reset will reorient the (multidimensional) direction back onto a steepest descent path and the procedure can start anew. This feature is included since the curvature-based estimate of the direction in the BFGS method does not always guarantee a downhill direction (i.e., the energy resultant upon a perturbation in such a direction is larger than the current one for all steps within a finite interval (including arbitrarily small ones → this is a different problem from "overstepping" for which step size reductions are employed).

MINI_MEMORY

If a minimization run is performed, and if the BFGS method is used, this keyword lets the user choose the memory length for the running estimate of the Hessian. Since the system will evolve throughout the minimization, the estimate of the Hessian is of course a moving target and it will only be useful to include points from the immediate vicinity in its numerical, gradient-based estimate. This keyword simply gives the (integer) number of immediately preceding steps to consider. Note that very long values will typically be irrelevant since the BFGS procedure will - in rough landscapes - frequently propose an ill-fated (uphill) direction (see MINI_UPTOL for comparison). Such moves will eventually lead to a reset of the estimate of the Hessian which includes "forgetting" all the memory. Hence, the effective usable memory length will be limited by the system as well. Note that the resets are necessary for the BFGS method to find any minima.

MINI_SC_SDSTEPS

If a stochastic minimization run is performed, this keyword allows the user to request the program to first run the specified number of steps as canonical steepest-descent (SD) minimization. These SD moves will follow the same parameter settings as described above and are completely independent of the stochastic steps. Note that these steps are always skipped if the settings request the use of holonomic constraints when minimizing in Cartesian space.

MINI_SC_HEAT

If a stochastic minimization run is performed, this keyword specifies the fraction of the total number of steps (NRSTEPS) that are going to be used to perform NVT dynamics at the user-supplied initial temperature and thermostat settings. Generally, for an efficient annealing protocol, it is probably advisable to combine a large value for this keyword with a high enough temperature and/or a comparatively large value for the thermostat's time constant, τ_T, such that NVE dynamics are mimicked over short periods of time (this will lead to heating in itself). Conversely, for straight minimization, it will be more appropriate to supply small values in conjunction with tight thermostat settings and low initial temperature.

MINI_SC_TBATH

If a stochastic minimization run is performed, this keyword lets the user specify the target temperature of the bath the system will be coupled to at the very end of the run. From the simulation step defined by MINI_SC_HEAT onward, the target temperature is interpolated between TEMP and MINI_SC_HEAT using a Gaussian function operating on a normalized time axis. For the protocol to work as intended, it will not be useful to specify anything but values close to (but not exactly) zero here.

Move Set Controls (MC):

---

(back to top)

Preamble (this is not a keyword)

A Monte Carlo simulation is a series of biased or unbiased random perturbation attempts to the system, in which some moves will be accepted (the Markov chain transitions to a new microstate) and the others rejected (the Markov chain remains in place) dependent on some criterion. This acceptance criterion is designed to sample a specific distribution, and the most common example is the Metropolis criterion designed to produce Boltzmann-distributed ensembles.
The type of random perturbation attempts possible constitute the move set, and the resultant microstate transitions are usually very different from those observed in molecular dynamics (MD). In dynamics, all unconstrained degrees of freedom evolve simultaneously (high correlation), but in small increments (low effective step size). In Monte Carlo, one or few degrees of freedom evolve at a given time, but in step sizes of varying amplitudes. It is not required that individual degrees of freedom are all sampled with equal weight (nor would it be clear how to establish this). The effective sampling weight is determined by three components:

1. The overall picking frequencies for move types (e.g., OTHERFREQ) are implemented by CAMPARI through a binary decision tree invoked at each step of the MC simulation. This means that the decisions taken at the root will influence the actual number of attempted moves of types chosen further up the tree, and that it may be complicated to calculate the expected numbers of attempts for those moves. This is why formulas are provided. Some totals (attempted and accepted moves) are reported in the log output at the end.
2. The organizational unit for a move is often a residue, but not all residue may possess equal numbers of degrees of freedom. For instance, sidechain moves have a variable number of degrees of freedom they sample (→ NRCHI), but the actual numbers per degrees of freedom will not be uniformly distributed since different residues may have different numbers of χ-angles.
3. Sampling weights can be adjusted explicitly with the help of the preferential sampling utility.

If one takes into account that selected degrees freedom may be eligible for different move types (while others are not), it should be abundantly clear that the details of a Monte Carlo move set are ultimately adhoc or empirical quantities (see Tutorial 4 for additional, theoretical considerations on move sets).
Because elementary Monte Carlo only change a few degrees of freedom at a time, the algorithms should be (and usually are) smart enough to only consider an incremental energy change associated with a move. The energy complexity of moves differs by type (see reference for details). The technical complexity with regards to applying the random perturbation also differs by type and sometimes behaves antagonistically to energy complexity. Taken together, these characteristics mean that it is challenging to parallelize a Monte Carlo sampler efficiently. CAMPARI generally tries to parallelize both coordinate operations and incremental energy calculations and strives to achieve load balance by explicitly estimating and then splitting the overall load for each significant task. This involves specialized routines for special move types. Because of the heterogeneity of MC move sets (and the controls offered over them), it is recommended to always perform a quick scaling check when using CAMPARI's shared memory (OpenMP) parallelization.

---

PARTICLEFLUCFREQ

This keyword is relevant only when ENSEMBLE is set to either 5 or 6, i.e., those ensembles which allow numbers of particles to fluctuate. In this case, the keyword defines the fraction of all moves that attempt to sample the particle number dimension of the thermodynamic state of the system. For the semi-grand ensemble, this corresponds to attempting to transmute one particle type into another while preserving the position of the target particle. For the grand ensemble, it will with 50% probability try to insert a particle of permissible type in a random location in the simulation container and with 50% probability attempt to delete a permissible particle. These moves are applied at the molecule level and most closely related to rigid-body moves in terms of complexity (→ RIGIDFREQ).
Technically, the GC ensemble is supported in CAMPARI by maintaining a set of ghost particles for each fluctuating type which work as "stand-ins". This framework entails certain limitations which are detailed elsewhere.
Expected numbers of such moves overall are calculated trivially as:
NRSTEPS · PARTICLEFLUCFREQ
Note that the default picking probabilities are such that every molecule type allowed to fluctuate in numbers receives equal weight. In case of particle permutation moves, which are implemented as joint insertion/deletion, there is no way to adjust these. This is because the implementation mandates the molecule types to be different, which would require additional corrections in the acceptance probability, which would cancel out the preferential sampling weights. For independent insertion and deletion available in the grand ensemble, the preferential sampling utility allows the user to at least adjust the picking probabilities on a per-type basis. This can be relevant for example in electrolyte mixtures with disparate target concentrations (and correspondingly disparate bath particle numbers), for which it would make sense to preferentially insert and delete those particle types with overall larger numbers. Such an adjustment would also bring the sampling weights in line with the default picking probabilities for rigid-body moves, which are flat on a per-molecule basis.

RIGIDFREQ

This keyword specifies what fraction of all remaining moves (i.e., 1.0 - PARTICLEFLUCFREQ) is to perturb rigid-body degrees of freedom. This encompasses translations and rotations of individual molecules as well as of groups of molecules. The default picking probabilities are even for all molecules regardless of type, size, or other properties. They can be adjusted via the preferential sampling utility, and this may be relevant in dense or semi-dilute systems with different molecule types of vastly different size (e.g., proteins and inorganic ions). In such a case, the acceptance rates for the macromolecules will be noticeably smaller, and this could be compensated for by sampling them preferentially.
While translations are generally simpler than rotations, they encounter difficulties when systems with nonperiodic boundaries are used in conjunction with large amplitudes of displacement. Relevant auxiliary keywords are RIGIDRDFREQ, TRANSSTEPSZ, and RIGIDRDBUF. Rotations are particularly tricky when more than molecule is considered. The relevant keywords for rigid rotation moves are RIGIDRDFREQ, ROTSTEPSZ, CLURBROTFREQ, and CLURBSPINFREQ. Finally, single molecule rigid-body moves can be coupled (→ COUPLERIGID). In case the moves are not coupled, keyword ROTREQ sets the fraction of rotation attempts. Some more implementation details are also given there.

COUPLERIGID

This keyword is a simple logical deciding whether or not to couple translational and rotational rigid-body moves for single molecules (see CLURBFREQ for multi-molecule moves). Like any type of move coupling, this means that up to six independent perturbations of individual degrees of freedom are employed (translation in x, y, and z, rotation around three axes) before energies and the acceptance criterion are evaluated. Note that molecules with no rotational degrees of freedom, while still enjoying the full sampling weight in terms of picking probabilities, will have their moves downgraded and counted as pure translation moves in the log-output.

ROTFREQ

This keyword can be used to set the sub-frequency for purely rotational moves if uncoupled moves are used (→ COUPLERIGID is false). It will then determine the fraction of those rotational moves. Total number:
NRSTEPS · (1.0-PARTICLEFLUCFREQ) · RIGIDFREQ · (1.0-CLURBFREQ) · ROTFREQ.
And the total number of purely translational moves will be:
NRSTEPS · (1.0-PARTICLEFLUCFREQ) · RIGIDFREQ · (1.0-CLURBFREQ) · (1.0-ROTFREQ)
Note that the above formulas do not account for the choice between randomizing and stepwise perturbations (→ RIGIDRDFREQ), which would introduce an additional factor into the above product (this is always a terminal decision).
Rotation moves for single molecules are implemented as follows. For a free molecule, three rotation axes are identified as the eigenvectors of the molecule's gyration tensor. For each axis, a random angle is picked with uniform probability, either globally or from a finite interval centered at 0.0 (see RIGIDRDFREQ). The composite rotation is constructed from the individual values and applied to the molecule. The composite rotation corresponds to a particular order of applying these rotations individually (note that rotations in 3D do not permute), which is arbitrary but fixed. The composite rotation axis passes through the molecule's geometric center (if the calculation is a pure MC run) or through its center of mass (if the calculation is a hybrid MC/dynamics run. For a molecule with custom constraints on individual rotational axes (a, b, c), the implementation is adjusted so that it uses the cardinal axes as rotation axes. If this were not the case, the constraints would be largely meaningless.

RIGIDRDFREQ

This keyword sets a terminal choice in the selection tree that is common to many of the moves in CAMPARI (see similar keywords PIVOTRDFREQ, NUCRDFREQ, and so on). Amongst the available rigid-body moves (it applies to three separate branches: coupled single-molecule moves, decoupled multiple-molecule moves, and decoupled single-molecule moves), this keyword chooses the fraction to completely randomize the underlying degrees of freedom. For example, the complete randomization of translational degrees of freedom would displace the molecule's reference center to an arbitrary point in the simulation container (with some tolerance for aperiodic boundaries, see below). The remaining fraction will correspond to stepwise perturbations in which a usually small random increment is added to the degrees of freedom in question. For example, such a move would displace a molecules reference center by a random vector small in absolute magnitude.
As an example consider single-molecule translation moves. The total number of expected randomizing translation moves would be (assuming COUPLERIGID is false):
NRSTEPS · (1.0-PARTICLEFLUCFREQ) · RIGIDFREQ · (1.0-CLURBFREQ) · (1.0-ROTFREQ) · RIGIDRDFREQ
And the number of stepwise translation moves would be:
NRSTEPS · (1.0-PARTICLEFLUCFREQ) · RIGIDFREQ · (1.0-CLURBFREQ) · (1.0-ROTFREQ) · (1.0-RIGIDRDFREQ)
The same modifications apply to any other branch of rigid-body move as explained above. As an additional complication, the decision about randomization vs. stepwise perturbations is decoupled itself in coupled rigid-body moves. Also note that the log output does not distinguish between the stepwise and randomizing varieties for any move type.
Randomizing rigid-body translations have one peculiarity. Unless a spatial dimension is periodic (see BOUNDARY), the absolute coordinates in this dimension have no strict bounds, which means that a fully random prior would have to extend to infinity. If the restraining force of the present interacting boundaries is not infinitely strong, it therefore gives rise to a consistent bias if particles are regularly placed randomly in a volume confined exactly to the formal definition of system size (the regions extending beyond this formal size become undersampled). This bias decreases with increasing restraining force. It is also less noticeable whenever the boundary potential does not act on just a single atom in the molecule. It acts on just a single atom for monoatomic "molecules" with an atom-based boundary condition and for single-residue molecules with a residue-based boundary condition (see BOUNDARY). In other cases, the bias is less apparent because the translation is applied to the molecule's geometric center, which in general is more likely to reside in the formal volume than the outermost atoms/residues. The same reason causes cluster rigid-body moves to be affected less as well, To avoid this type of bias, keyword RIGIDRDBUF can be used.

ROTSTEPSZ

For any stepwise perturbation of rotational rigid-body degrees of freedom, this keyword sets the maximum step size in degrees. It is implemented such that the actual step size is drawn with uniform probability from an interval from -ROTSTEPSZ° to ROTSTEPSZ° for every individual axis that enters the computation of the net rotation axis and increment.

TRANSSTEPSZ

For any stepwise perturbation of translational rigid-body degrees of freedom, this keyword sets the maximum step size in Å. Analogous to ROTSTEPSZ, it is implemented such that the actual step size is drawn with uniform probability from an interval from -TRANSSTEPSZ to TRANSSTEPSZ Å.

RIGIDRDBUF

For any full randomization attempt in a rigid translation move in the presence of an explicit boundary potential acting on at least one of the coordinates, this keyword sets a scale ratio of sampling dimension and the size of the simulation container. Specifically, this means that the point to be placed, which is the geometric center of a molecule or a group of molecules, samples from a uniform distribution inside a container with dimensions that are RIGIDRDBUF times larger than the formal size specified. For a rectangular box these are the side lengths, for a sphere it is a radius, and for a cylinder it is the height and the radius. In all cases, the scale factor applies only to those dimensions, which are not periodic, i.e., which are "closed" by an explicit boundary potential of controllable strength. The factor is applied uniformly to all of these eligible dimensions. The default value is 1.0, and only values greater than or equal to 1.0 are allowed. The computational efficiency of these move types decreases with increasing RIGIDRDBUF because an increasing number of moves will be rejected on account of the boundary potential. However, a value of 1.0 introduces systematic biases. Essentially, the full randomization move is nonergodic and will lead to a systematic underestimation of occupancy probabilities for positions with finite values of the boundary potential. This effect is strongest for the displacement of single-atom molecules by single-molecule rigid translation moves. Appropriate values for RIGIDRDBUF are those that effectively mask the bias. These appropriate values depend on boundary force, temperature, formal size, and system composition (see above for details regarding the last point).

CLURBFREQ

This keywords sets the fraction of all available rigid-body moves to simultaneously perturb the rigid-body degrees of freedom of more than one molecule in concerted fashion. In other words, these moves allow the concerted translation (by the same vector) and two types of rotations (either around the "cluster" center-of-mass or collectively around individual axes) of several molecules in one shot.
The expected total number of multi-molecule moves would be:
NRSTEPS · (1.0-PARTICLEFLUCFREQ) · RIGIDFREQ · CLURBFREQ
And that of all single molecule rigid-body moves would be:
NRSTEPS · (1.0-PARTICLEFLUCFREQ) · RIGIDFREQ · (1.0-CLURBFREQ)
Currently, the picking of the molecules in a "cluster" is completely random. This is generally inefficient when there are many molecules. In particular, these moves offer absolutely no advantage for dense systems composed of many molecules because the "cluster" will almost always be a set of molecules whose degrees of freedom are not strongly correlated (and allowing correlation is the only real motivation for attempting multi-degree of freedom moves in MC).
As mentioned, multi-molecule moves are split into a translational variant and two rotational variants, with the latter explained below (see CLURBROTFREQ and CLURBSPINFREQ). Cluster translation moves proceed by picking a common displacement vector for more than one molecule (→ CLURBMAX). The expected total number of multi-molecule translation moves is:
NRSTEPS · (1.0-PARTICLEFLUCFREQ) · RIGIDFREQ · CLURBFREQ · (1.0-CLURBROTFREQ)
Since these molecules have no controlled spatial relationship, picking random displacements for them can easily get very inefficient. For example, in droplet boundary conditions, translations of clusters formed by distal molecules will frequently incur significant boundary penalties. Like all other rigid-body moves, cluster moves can be stepwise or completely randomizing (still in concerted fashion). This is all regulated by the previously introduced keywords RIGIDRDFREQ, RIGIDRDBUF, ROTSTEPSZ and TRANSSTEPSZ.
With the preferential sampling utility, it is possible to alter the picking weights on a per-molecule basis (the default weights are the same for every molecule irrespective of size, shape, etc). Note that this should yield either zero or reasonably large weights for all molecules, because the weights combine in a product sense during the picking process. This also means that it is tedious to compute the expected sampling probabilities for all possible "clusters" of molecules of sizes 2 to the maximum value. These moves are likely to be replaced by a more efficient variant in the future that uses spatial information to make the correlation component more meaningful.
Custom constraints on individual translational directions (x, y, z) are observed by these moves in a restrictive manner. This means that if just one of the molecules attempted to be moved has constraints in a given Cartesian direction, this direction is eliminated for the entire cluster. In the unlikely case that different molecules have different constrained directions, it is therefore possible that the move is depleted entirely. This is inefficient as it constitutes a type of "empty" MC move with absolutely no sampling benefits. The correct handling of individual constraint directions is most useful for simulations in reduced dimensions (2 or 1).

CLURBROTFREQ

If cluster rigid-body moves are in use, this keyword selects the fraction of these moves to attempt rotations. The "normal" way of rotating is around a common cluster centroid and thus perturbs translational degrees of freedom of individual molecules. There is an alternative type of rotation move enabled by keyword CLURBSPINFREQ, in which the same rotation is applied to several molecules. These rotations are not around inertial axes of individual molecules but always around the cardinal axes of the laboratory reference frame.
Note that cluster rotation moves of the first type can become somewhat counterintuitive. In periodic boundary conditions, the nearest image and hence the internal structure of the cluster may actually change upon rotation of a cluster. Similarly, in droplet boundary conditions, rotations (and translations) of clusters formed by distal molecules may incur significant boundary penalties and suffer from low acceptance rates. Like all other rigid-body moves, cluster rotation moves can be stepwise or completely randomizing (still in concerted fashion). This is all regulated by the previously introduced keywords RIGIDRDFREQ and ROTSTEPSZ.
The expected number of multi-molecule rotation moves around a common pivot (the "clusters" centroid) would be:
NRSTEPS · (1.0-PARTICLEFLUCFREQ) · RIGIDFREQ · CLURBFREQ · CLURBROTFREQ · (1.0-CLURBSPINFREQ)
Note that molecules whose translational degrees of freedom have been frozen (by custom constraints) are ineligible for rotations around a common pivot (while they are eligible for the spinning moves explained below). The rotational axes considered for the "cluster" of molecules are always the cardinal axes of the laboratory frame passing through the geometric center of the clusters.
Custom constraints on individual translational directions (x, y, z) are observed by these moves in a restrictive manner. This means that if just one of the molecules attempted to be moved has constraints in a given Cartesian direction, no rotations are allowed that would change this direction. This means that already a single constrained direction eliminates two of the three axes and more than one constrained direction prevents the entire move. The latter case is inefficient as it constitutes a type of "empty" MC move with absolutely no sampling benefits. The correct handling of individual constraint directions is most useful for simulations in 2D where a single rotation axis remains.

CLURBSPINFREQ

If cluster rigid-body moves are in use, and cluster rotation moves are enabled, this keyword selects the fraction of these molecules to be of the spinning variety. "Spinning" here refers to the selection of a "cluster" of molecules and applying the same rotation around parallel axes where each axis passes through each molecule's geometric center. As a result, these moves do not change translational coordinates of molecules.
The expected number of multi-molecule rotation moves of the spinning variety would be:
NRSTEPS · (1.0-PARTICLEFLUCFREQ) · RIGIDFREQ · CLURBFREQ · CLURBROTFREQ · CLURBSPINFREQ
The three individual rotational axes considered for every molecule in a "cluster" are always the cardinal axes of the laboratory frame passing through the respective geometric centers (if the calculation is a pure MC run) or the centers of mass (if the calculation is a hybrid run). This differs from the single molecule rigid rotation moves (and the coupled ones), which use axes derived from the gyration tensor whenever all three dimensions are free to move.
Custom constraints on individual rotational axes per molecule (x, y, z) are observed by these moves in a restrictive manner. This means that if just one of the molecules attempted to be moved has constraints for rotating around that cardinal axis, this axis is eliminated entirely when constructing the net rotation axis. This means that the unlikely case of different rotation axes having been eliminated for different molecules, the constraints prevent the entire move. This is inefficient as it constitutes a type of "empty" MC move with absolutely no sampling benefits. The correct handling of individual constraint directions is clearly most useful for simulations in 2D where a single rotation axis remains.

CLURBMAX

This keyword sets the maximum "cluster" size for concerted multi-molecule rigid-body moves (see CLURBFREQ). The assignment is completely random at any given step such that detailed balance is maintained. Note that the number of possible "clusters" grows as binomial coefficients with increasing size of the cluster until CLURBMAX reaches half the number of molecules in the system. It is important to point out that picking values close to the number of molecules can cause search problems that CAMPARI actively avoids. Specifically, if the total sampling weight of available molecules remaining is less than 10%, a new molecule has not been found to add to the "cluster" in 100 tries, and the current size is at least 2, then the value picked initially for CLURBMAX is decreased to the current size. This is to avoid the code spending an excessive amount of time in an inefficient search procedure. The control on total sampling weight is particularly relevant for cases where the picking weights have been altered on account of the preferential sampling utility.

ALIGN

This keyword is an integer indicating how to handle the fact that lever arm effects can be asymmetric in multimolecular simulations. A brief explanation is in order. Consider a macromolecule with multiple dihedral angles along the backbone. Then, a perturbation of an individual of those dihedral angles may be implemented in two basic implementations corresponding to two building directions of the (unbranched) main chain. Either one of the ends will swivel around (lever-arm) while the other remains fixed in place. In a simulation with just a single molecule, the new conformations for either type will be identical except for an implied rotation of the reference frame. In a simulation with multiple molecules, however, the two conformations will be explicitly different since the other molecules define the now static reference frame. In general, moves with longer lever-arms will have lower acceptance rates and are slower to evaluate and should generally be avoided. For MC, this affects polypeptide pivot moves (coupled and uncoupled (see COUPLE)), ω-moves (see OMEGAFREQ), Favrin et al. inexact CR moves (see CRMODE), pivot-type nucleic acid moves (see NRNUC), sugar pucker moves (see SUGARFREQ), and polypeptide cyclic residue pucker moves (see PKRFREQ). It affects single torsion pivot moves (see OTHERFREQ) in a slightly different manner, and this is described there. It is also relevant for torsional dynamics for which it in similar vein determines the assumed building direction and resultant base of motion for the chains. Options are as follows:

1. Always leave N-terminus unperturbed (C-terminus swings around).
2. Always leave C-terminus unperturbed (N-terminus swings around). This is only recommended in special applications since the C-terminal alignment requires the whole molecule to be rotated around, which makes this mode more expensive but analogously asymmetric when compared to mode 1.
3. Always leave the longer end unperturbed (shorter lever-arm is chosen). This is the default (and a good) choice as it should be the most efficient one for simulations with multiple chains of significant length. It is also the recommended setting for torsional dynamics in which the kinetics at one of the termini will otherwise be artificially slowed (note that the criterion determining lever arm length uses number of atoms rotated rather than number of residues in dynamics).
4. A stochastic modification of mode 3 only available in MC: The probability with which the longer end swivels around is equal to:
   p_lt = (L_st + 1) / (L_st + L_lt + 2)
   And conversely:
   p_st = (L_lt + 1) / (L_st + L_lt + 2)
   Here, L_st is the smaller number of residues beyond the pivot point towards the nearer terminus and L_lt is the larger number of residues beyond the pivot point towards the more distant terminus such that L_st+L_lt+1 yields the total number of residues in the molecule. For example, a molecule with six residues would yield probabilities for doing C-terminal alignment (the N-terminus swings around) of 6/7 for residue 1, 5/7 for residue for residue 2, and so on down to 1/7 for residue 6.
   This choice represents the most flexible move set and should normally be preferred in MC when sampling problems are encountered.

Note that the "N"-terminus in polynucleotides is the 5'-end and the "C"-terminus the 3'-end. In general, when set to 2 or 3, this keyword may (currently) have slightly different effects in torsional dynamics vs. MC calculations. This is because the former considers each polymer as a generic branched chain, which means that, e.g., in lysine peptide the sidechain becomes the "terminus" owing to its greater length. As a general rule, terminal dihedral angles rotating only one or more hydrogen atoms are not considered for alignment regardless of setting. Additional, terminal dihedral angles may also be excluded in MC. It is relatively straightforward to extract the convention in use by running a short test simulation without rigid-body movement and comparing initial and final structures. In doing so, it becomes apparent that the last (and stochastic) option is the only one that clearly does not maintain a fixed base of motion. However, in a hybrid run, depending on the sequence and the exact move set, it is also not guaranteed that, with the exception of strict N-terminal alignment, the bases of motion coincide exactly (because they depend on related but slightly different criteria). As a consequence, all torsional moves, and this includes exact concerted rotation moves albeit for different reasons, might fail to respect existing constraints on the rigid-body coordinates, which in technical terms can only refer to the base of motion. Thus, for molecules where the base of motion is meant to stay fixed, options 3 or 1 above are the recommended ones. The only move type for which constraints have an influence on chain alignment are the single-dihedral angle pivot moves (see elsewhere for details).
Finally, it should be mentioned that the N-terminal alignment corresponds exactly to the way molecules are built (hierarchically) in CAMPARI from their Z-matrix entries, and that this is a purely technical choice that should not have an impact on the thermodynamics of a system.

COUPLE

If this keyword is set to 1 (logical true), all polypeptide pivot moves are coupled to sidechain moves on the same residue (→ PIVOTMODE). This means that new conformations for the φ- and ψ-angles as well as for some of the sidechain χ-angles (if any) are proposed before the energy and acceptance criterion are evaluated. Like any other unbiased move perturbing multiple degrees of freedom, this procedure drastically increases the chance of generating an unacceptable conformation (assuming a typical excluded-volume interaction potential is used). Consequently, acceptance rates will be very low and it is generally not recommended to use this option. Note that it is still possible to use independent sidechain moves but that it is impossible to do independent pivot moves for residues with sidechains. In other words, all frequency settings are used as normal but all standard polypeptide pivot moves (the default move type of the decision tree) are coupled to a mandatory sidechain move (of a (sub)set of sidechain angles in that residue). Keywords PIVOTRDFREQ, PIVOTSTEPSZ, CHIRDFREQ, CHISTEPSZ, and NRCHI and all observed in the respective parts of the underlying base move types.
The expected number of those coupled moves would be:
NRSTEPS · (1.0-PARTICLEFLUCFREQ) · (1.0-RIGIDFREQ) · (1.0-CHIFREQ) · (1.0-CRFREQ) · (1.0-OMEGAFREQ) · (1.0-NUCFREQ) · (1.0-PKRFREQ) · (1.0-OTHERFREQ)
Note that the same formula applies to uncoupled polypeptide pivot moves.

PIVOTMODE

Polypeptide pivot moves are historically the oldest move type in CAMPARI. Therefore, they are placed at the outermost branch of the move selection tree and possess no frequency selection keyword. In general, pivot moves simultaneously sample the φ- and ψ-angles of a single polypeptide residue unless the residue is ring-constrained (such as proline or hydroxyproline) in which case only the unconstrained degree of freedom (ψ for proline) is sampled. See PKRFREQ for "pivot" moves which sample the φ-angles of proline and analogous residues. The default picking probabilities for polypeptide moves are even for all residues with peptide φ/ψ-angles. They can be adjusted with the help of the preferential sampling utility. An example where this can be useful is in reducing the picking weight of proline and similar residues, for which the number of degrees of freedom is smaller.
Mostly for historical reasons, this keyword allows the selection of different modes for pivot moves as follows:

1. Blind backbone sampling, i.e., all angles have equal likelihood (unbiased and the default)
2. Using grids (requires GRIDDIR), i.e., angle pairs are sampled come from within an approximate envelope derived from the space available to the corresponding dipeptide if one assumes typical excluded volume interactions (biased).

The second option is an attempt to improve conformational space sampling but introduces bias. It is not fully supported at the moment and may be removed entirely in the future.

PIVOTRDFREQ

Much like for other move types, CAMPARI allows the user to mix two types of polypeptide pivot moves: the first randomizing the φ- and ψ-angles of the residue in question (for proline only the ψ-angle, for coupled moves also the sidechain χ-angles → COUPLE), the second perturbing them by a small increment whose size is set by the auxiliary keyword PIVOTSTEPZ. Note that randomizing moves may be extremely ineffective for the sampling of dense phases (collapsed states of macromolecules) and that the only accepted moves will be those realizing small displacements by chance.
To calculate the expected number of randomizing and stepwise polypeptide pivot moves, the user may employ the formula listed under COUPLE and multiply it with PIVOTRDFREQ and 1.0-PIVOTRDFREQ, respectively.

PIVOTSTEPSZ

This keyword sets the step size in degrees for local perturbation attempts to the φ- and ψ-angles of polypeptide residues (see PIVOTRDFREQ). Note that this step size encompasses the entire symmetric interval around the original position, i.e. a value of 10° will attempt uniformly distributed random displacements within the interval of -5° to 5°.

GRDWINDOW

This keyword sets a parameter determined by external input files which are used to assist conformation space sampling in biased fashion when PIVOTMODE is set to 2. Then, GRDWINDOW needs to specify half the bin size for the steric grids (see GRIDDIR). The files are supplied in the data-directory and the default value to be used here would be 5.0°. Note that grid-assisted sampling is not a fully supported option in CAMPARI and may be removed entirely in the future.

OMEGAFREQ

In polypeptides, the dihedral angle along the actual peptide bond (ω) is different from the φ- and ψ-bonds since the carbon and nitrogen atoms have partial sp²-character. This inhibits free rotation around the bond due to electronic effects and means that only a very narrow range of conformations is typically available to the ω-angle. The two dominant states are the planar cis- and trans-conformations with the latter being almost exclusively seen for non-proline residues and both contributing for proline. In molecular mechanics force fields, these effects are typically represented via strong torsional potentials (see SC_BONDED_T and SC_EXTRA). From a sampling point of view, this means that it would be unwise to couple the sampling of such a stiff degree of freedom to any other degree of freedom. ω-moves therefore perturb nothing but the ω-angle of an individual polypeptide residue. They technically are equivalent to pivot moves in that the "free" end will swivel around lowering the acceptance rates additionally if the perturbations are large (→ ALIGN).
To calculate the number of expected ω-moves use:
NRSTEPS · (1.0-PARTICLEFLUCFREQ) · (1.0-RIGIDFREQ) · (1.0-CHIFREQ) · (1.0-CRFREQ) · OMEGAFREQ
Note that the moves are additionally split up into those attempting to completely randomize the ω-angle and those that attempt stepwise perturbations (→ OMEGARDFREQ). It should be emphasized that the randomizing move will typically be the only way of converting between cis- and trans-conformations due to the height of the barrier separating the two. The default picking probabilities are identical for all residues with ω-type bonds. They can be adjusted with the help of the preferential sampling utility, and such adjustment could be useful in mixed systems with small molecule amides and polypeptides, where it may be beneficial to preferentially sample the polypeptide ω-bonds.

OMEGARDFREQ

This keyword is completely analogous to PIVOTRDFREQ but applies to ω-moves instead of φ/ψ-moves.

OMEGASTEPSZ

This keyword is completely analogous to PIVOTSTEPSZ but applies to ω-moves instead of φ/ψ-moves.

PKRFREQ

Of the fraction of all pivot-type polypeptide backbone moves, what is the fraction of backbone moves to selectively alter the dihedral angles around the N-C_α bond in proline or similar residues? These rotations are hindered by the presence of the ring and hence they cannot be sampled independently. Moves of this type therefore alter the pucker state of the amino acid sidechain belonging to the chosen residue and the backbone conformation of the polypeptide (pivot-type move) simultaneously. These moves are analogous to sugar pucker moves for polynucleotides (see SUGARFREQ).
The expected number of polypeptide pucker moves would be:
NRSTEPS · (1.0-PARTICLEFLUCFREQ) · (1.0-RIGIDFREQ) · (1.0-CHIFREQ) · (1.0-CRFREQ) · (1.0-OMEGAFREQ) · (1.0-NUCFREQ) · PKRFREQ
Note that these moves are split up into two variants - a non-ergodic one which inverts the pucker state, and one which introduces new degrees of freedom, bond angles, but allows sampling of most of the relevant phase space (bond length changes remain quenched). This is determined by PKRRDFREQ. When analyzing high-resolution structural databases, it can be seen that proline residues occupy two dominant pucker states separated by a barrier. The non-ergodic move can jump across this barrier but is unable to explore the basin around its current position. The latter requires bond angle changes as otherwise the problem is overconstrained. This introduction of new degrees of freedom is generally undesirable (see discussion under ANGCRFREQ) but in this particular case of small impact since none of the bond angles along the main chain are allowed to change. This keeps the effects of bond angle changes local while allowing exploration of the continuous manifold of conformations of the five-membered ring.
The exact set of degrees of freedom used to sample the ergodic move type is explained in detail elsewhere, and an implementation reference is given in the literature. The default picking probabilities for this move type are flat for all polypeptide residues possessing ring pucker degrees of freedom. The probabilities can be adjusted by the preferential sampling utility, and this could be used to fine-tune sampling weights in polymers. For example, puckering equilibria for central residues in polyproline are expected to be both more relevant and more difficult to sample than those for terminal residues and may benefit from being sampled preferentially. Finally, like sugar pucker moves, these moves are using no parallelization to the closure problem for the ring when CAMPARI's shared memory (OpenMP) parallelization is in use, which is a limitation.

PKRRDFREQ

As pointed out above, finding arbitrary conformations of a five-membered ring while keeping all bond lengths and angles constant is an overconstrained problem (→ PKRFREQ). Therefore, CAMPARI releases the constraint on bond angle rigidity for those systems which include proline and similar polypeptide residues. This necessitates the use of bond angle potentials (see SC_BONDED_A) to keep local geometries reasonable. To sample different ring conformers effectively, CAMPARI uses a strategy of combining a non-ergodic reflection of the pucker step (non-local) with stepwise but unbiased excursions away from the current state. This keywords regulates the fraction of pucker moves to be of the former type (reflection). The formulas listed under PKRFREQ multiplied with PKRRDFREQ and (1.0-PKRRDFREQ), respectively, would give the expected numbers for either type. Note that it typically is not a good idea to set this to either zero or unity. A value of unity would create an effective two-state model (with fixed bond angles), while a value of zero would make it very difficult for the gross pucker state to switch due to the barrier separating the two (this last statement assumes typical interaction potentials).

PUCKERSTEP_DI

This keyword applies to the second type of pucker sampling (see PKRRDFREQ) and controls the maximum step size for dihedral angles in degrees for the random stepwise excursions from the current state. It simultaneously applies to the problem of sugar pucker sampling (→ SUGARFREQ). In both cases, four of the seven freely sampled degrees of freedom are dihedral angles.

PUCKERSTEP_AN

This keyword applies to the second (stepwise) type of pucker sampling (see PKRRDFREQ) and controls the maximum step size for bond angles in degrees for the random stepwise excursions from the current state. Much like PUCKERSTEP_DI, this keyword simultaneously applies to the problem of sugar pucker sampling (→ SUGARFREQ). In both cases, two of the seven freely sampled degrees of freedom are bond angles and one bond angle is derived to correctly close the loop.

NUCFREQ

This keyword controls the frequency of all types of polynucleotide moves excepting those sampling just sidechain degrees of freedom. This set includes algorithms to sample stretches of polynucleotides with end-constraints (concerted rotation → NUCCRFREQ), dedicated algorithms to sample the constrained dihedral angles around the sugar bond (→ SUGARFREQ), and simple polynucleotide backbone pivot moves. The description below applies only to the latter type which does not possess a dedicated keyword but is the default fall-through choice for this branch of the decision tree.
Non-terminal polynucleotides have six backbone degrees of freedom one of which is not sampled by this type of move. Much like for proline, the rotation around the sugar bond is hindered and a dedicated algorithm is needed to sample this dihedral angle (→ SUGARFREQ). An overview of the backbone degrees of freedom for terminal and non-terminal nucleotides can be gleaned from the description of sequence input. Nucleotide pivot moves are physically analogous to polypeptide φ/ψ-moves in that they sample the backbone of a single nucleotide residue. The new conformation will imply the rotation of a lever arm which will render large-scale perturbations very unlikely to be accepted (→ ALIGN). Technically, these moves are implemented slightly differently in that the number of sampled degrees of freedom may vary (→ NRNUC). This is to make it possible to fine-tune sampling efficiency. As with any move coupling the sampling of independent degrees of freedom blindly, efficiency will typically be unacceptably low for more than two backbone dihedral angles given a realistic interaction potential and the complicated topology of polynucleotides. In the future, these moves are sought to cover any type of non-polypeptide polymer and the flexible setup was implemented partially with that in mind.
Expected numbers for all polynucleotide pivot moves may be calculated as follows:
NRSTEPS · (1.0-PARTICLEFLUCFREQ) · (1.0-RIGIDFREQ) · (1.0-CHIFREQ) · (1.0-CRFREQ) · (1.0-OMEGAFREQ) · NUCFREQ · (1.0-NUCCRFREQ) · (1.0-SUGARFREQ)
Remember that NUCFREQ does not control the fraction of polynucleotide pivot moves directly but only sets the expected number for all polynucleotide moves. Note that the moves are additionally split up into those attempting to completely randomize the nucleotide backbone angles and those that attempt stepwise perturbations (→ NUCRDFREQ). The default picking probabilities for these pivot moves are flat on a per-residue basis. They can be adjusted by the preferential sampling utility, and this could become routinely relevant in future applications, for which other polymer types are subjected to pivot moves through this facility. In such a case, it would almost certainly be desirable to make the picking frequencies (at the very least) proportional to the number of backbone degrees of freedom in each residue, which may not necessarily be homogeneous.

NRNUC

This keyword allows the user to set the maximum number of nucleic acid backbone angles to be sampled within a pivot polynucleotide move. The dihedral angles will always come from the same residue. The implementation has the following features:

• Whenever NRNUC is equal to or larger than the number of backbone angles on a certain residue, all backbone angles on that residue will be sampled simultaneously.
• Whenever NRNUC is smaller than the number of backbone angles on a certain residue, on average NRNUC of the available angles should be sampled simultaneously. However, the actual average will be larger since always at least one angle has to be sampled (in other words, there is a stochasticity to the number of angles chosen, and the asymmetry is introduced by the constraint to always have at least one angle in the set).

NUCRDFREQ

This keyword is completely analogous to PIVOTRDFREQ but applies to polynucleotide backbone pivot moves instead of φ/ψ-moves.

NUCSTEPSZ

This keyword is completely analogous to PIVOTSTEPSZ but applies to polynucleotide backbone pivot moves instead of φ/ψ-moves.

NUCCRFREQ

This keyword sets the fraction of exact nucleic acid concerted rotation (CR) moves amongst all nucleotide moves. Concerted rotation algorithms are provided both for polypeptides and polynucleotide and function generally analogously although there are important implementation differences. Important general information for this type of move is provided elsewhere, along with parameters that apply to all variants of exact CR moves (such as UJCRBIAS, UJCRSTEPSZ, and UJCRWIDTH). In particular, the reader is referred to both the literature and the documentation on CR moves for polypeptides (→ CRFREQ and TORCRFREQ) in particular with regards to the interpretation of auxiliary keywords (NUCCRMIN and NUCCRMAX) and the handling of picking probabilities and their alteration by user-level constraints and preferential sampling weights.
The general idea of a concerted rotation move is to sample a stretch of polymer without changing the absolute positions and relative orientation of the termini. Six degrees of freedom are required to solve this constrained problem. Note that for nucleic acid CR moves the rotation around the sugar bond (C4*-C3*) is always excluded from the algorithm (treated as a rigid segment). The order of angles is as follows:

1. Any number of consecutive and permissible backbone dihedral angles immediately preceding nuc_bb_4 on residue i
2. O5P-C5*-C4*-C3* (nuc_bb_4 on residue i)
3. C4*-C3*-O3P-P (nuc_bb_5 on residue i)
4. C3*-O3P-P-O5P (nuc_bb_1 on residue i+1)
5. O3P-P-O5P-C5* (nuc_bb_2 on residue i+1)
6. P-O5P-C5*-C4* (nuc_bb_3 on residue i+1)
7. O5P-C5*-C4*-C3* (nuc_bb_4 residue i+1)

The first entry is the so called pre-rotation segment, and the remaining six degrees of freedom are those for which to find a numerical solution that closes the chain exactly without changing the position of any atom from C3* on residue i+1 onward. The solution is obtained through a 1D numerical root search in an algebraically transformed set of equations. This part follows the work of Aaron Dinner exactly and its parameters are explained in further detail below. The pre-rotation segment uses its own biasing scheme for improved efficiency based on the work by Favrin et al.. Both types of biases are removed through a modified acceptance criterion. However, it must be pointed out that the reliability of the root search is nonetheless a critical component to obtain an unbiased Markov chain observing detailed balance. If unfamiliar, the user should read all of the documentation on exact concerted rotation methods below in addition to consulting the literature.
The expected number of nucleic acid concerted rotation moves is obtained as follows:
Expected numbers for polynucleotide CR moves may be calculated as follows:
NRSTEPS · (1.0-PARTICLEFLUCFREQ) · (1.0-RIGIDFREQ) · (1.0-CHIFREQ) · (1.0-CRFREQ) · (1.0-OMEGAFREQ) · NUCFREQ · NUCCRFREQ
The user is reminded again that some of the parameters required for this move type apply universally to all exact CR methods while some apply specifically to the nucleic acid variant. Finally, these and all other exact torsional concerted rotation moves are (currently) unavailable when using CAMPARI's shared memory (OpenMP) parallelization.

SUGARFREQ

This keyword sets the fraction of polynucleotide backbone moves to selectively alter the dihedral angles around the sugar bond (C4*-C3*) amongst all polynucleotide moves not of the CR variety. Exactly analogous to the case for proline and similar cyclic residues in polypeptides (→ PKRFREQ), these rotations are hindered by the presence of the ring and cannot be sampled blindly. Moves of this type will therefore alter the pucker state of the sugar belonging to the chosen nucleotide and the backbone conformation of the polynucleotide (including lever arm) simultaneously.
The expected number may be calculated as follows:
NRSTEPS · (1.0-PARTICLEFLUCFREQ) · (1.0-RIGIDFREQ) · (1.0-CHIFREQ) · (1.0-CRFREQ) · (1.0-OMEGAFREQ) · NUCFREQ · (1.0-NUCCRFREQ) · SUGARFREQ
The approach chosen to sample sugars is identical to the one for proline. There are two basic move types, one which inverts the pucker state by flipping the sign of two dihedral-angles, and a second one which perturbs the bond angles and dihedral angles defining the 5-remembered ring by small random increments while maintaining bond lengths exactly (→ SUGARRDFREQ). The default picking probabilities for this move type are even for all eligible, sugar-containing residues. They can be adjusted by the preferential sampling utility. An example application could be to preferentially sample sugars close to the binding interface of a well-defined protein-DNA complex rather than those in the rigid portion of the DNA. Finally, like polypeptide pucker moves, these moves are using no parallelization to the closure problem for the ring when CAMPARI's shared memory (OpenMP) parallelization is in use, which is a limitation.

SUGARRDFREQ

This keyword is exactly analogous to PKRRDFREQ but applies to sugar pucker moves in polynucleotides instead of to polypeptide pucker moves.

CHIFREQ

Most biologically relevant polymers possess at least minor branches off the main chain. These sidechains are typically short and usually encode the alphabet underlying for instance polypeptides and polynucleotides. From a technical point of view, such short branches are much easier to sample than the backbone of a polymer since the impact of a change in conformation of the branch only affects the branch (lever arm effects are minimal and the assumed direction is always from the main chain outward towards the end of the branch). Since the perturbation is local, energy evaluations are much less costly and acceptance rates generally higher. There is no need for advanced algorithms and simple pivot-style moves re-setting or perturbing the dihedral angles angles in such a sidechain branch are sufficient to explore phase space. This keyword sets the fraction of all sidechain moves including a specialized move type used for analysis only (→ PHFREQ).
Expected numbers for actual sampling moves (denoted as χ-moves) are:
NRSTEPS · (1.0-PARTICLEFLUCFREQ) · (1.0-RIGIDFREQ) · CHIFREQ · (1.0-PHFREQ)
And for moves trying to determine the pK-values of ionizable polypeptide sidechains:
NRSTEPS · (1.0-PARTICLEFLUCFREQ) · (1.0-RIGIDFREQ) · CHIFREQ · PHFREQ
Note that the former are decomposed further into those randomizing the contributing degrees of freedom and those applying stepwise perturbations (→ CHIRDFREQ). The default picking probabilities for this move type give equal weight to all residues with at least one χ-angle independent of the number of χ-angles. This can be adjusted by the preferential sampling utility, which as an example would allow making all residue picking probabilities directly proportional to the number of χ-angles for each residue.

CHIRDFREQ

This keyword is completely analogous to PIVOTRDFREQ but applies to χ-moves instead of φ/ψ-moves.

CHISTEPSZ

This keyword is completely analogous to PIVOTSTEPSZ but applies to χ-moves instead of φ/ψ-moves.

NRCHI

Many sidechains have different numbers of χ-angles and the complexity of a move would depend on the number of such angles sampled concurrently. Therefore, this keyword allows the user to set the maximum number of χ-angles to be sampled within a sidechain move. The dihedral angles will always come from the same sidechain on the same residue. Analogously to NRNUC, the implementation has the following features:

• Whenever NRCHI is equal to or larger than the number of χ-angles on a certain residue, all χ-angles on that residue will be sampled simultaneously.
• Whenever NRCHI is smaller than the number of sidechain angles on a certain residue, on average NRCHI of the available angles should be sampled simultaneously. However, the actual average will be larger since always at least one angle has to be sampled (in other words, there is a stochasticity to the number of angles chosen, and the asymmetry is introduced by the constraint to always have at least one angle in the set).

OTHERFREQ

MC move sets are highly specialized tools that have to reflect the choice of the system's degrees of freedom, its density, etc. Some of the choices enforced by the "standard" CAMPARI move sets and mandated by the default parameterization of the ABSINTH implicit solvent model are somewhat arbitrary. This is primarily an issue for degrees of freedom describing rotations around electronically hindered bonds and for rotations around terminal bonds between heavy-atoms (methyl and ammonium spins). For example, the amide bond in secondary amides is allowed to vary with dedicated moves, but these are not available for primary amides (the reasoning behind it is connected to the vanishing relevance of cis/trans isomerization in the latter case). However, these choices may not always be desirable. Second, when attempting to simulate entities that CAMPARI does not support natively, the majority of "standard" move types may not be available (exceptions apply if the entities are recognized as conforming to a supported biopolymer type). This would limit simulations containing such entities to pure rigid-body sampling.
To address both issues, CAMPARI offers a separate class of dihedral angle pivot moves that can be applied to any freely rotatable torsion angle in any of the system's components. There is a requirement that the Z-matrix be constructed such that only a single Z-matrix angle needs to be edited to describe the perturbation, and this is true for all candidate dihedral angles in residues supported natively by CAMPARI that are frozen by default (e.g., C-N bond in the lysine sidechain, all C-N bonds in primary amides, CA-CB bond in alanine, and so on). For unsupported residues, the Z-matrix is inferred from the input structure, and it may require some reordering of atoms to achieve the desired results (see a tutorial relevant in this context). In addition, these moves can also sample torsional degrees of freedom supported by other move sets as long as they fulfill the Z-matrix criterion (this currently excludes the polypeptide φ/ψ-angles, which are supported by the widest range of specialized move sets).
In terms of parameters, some care has to be taken that torsional potentials describing electronic effects (e.g., in primary amides) are included. Technically, moves of this type are unique in that they always sample only a single degree of freedom. Chain alignment works slightly differently for these moves. Specifically, for options 3 and 4, the number of atoms (rather than the number of residues) moving is critical in determining alignment. Also, all degrees of freedom are eligible for an inverted alignment including sidechain degrees of freedom. Even for option 3, this may consequently lead to the absence of a "base of motion" that would stay rigorously in place in the absence of rigid body moves. Because these moves will allow a main chain to swivel around a bond in a sidechain (branch), degree of freedom-based custom constraints would be seriously violated if ALIGN is set to 4. Thus, CAMPARI will defer option 4 to option 3 when there are active constraints set through the input file. Note that this does not apply to the Monte Carlo move set in general; it is only effective for the moves controlled by OTHERFREQ. For option 2, CAMPARI attempts to preserve a well-defined base of motion at the C-terminus, but this may not work as expected, in particular for polynucleotides and/or very short chains.
To calculate the number of all expected moves of type of OTHER, use:
NRSTEPS · (1.0-PARTICLEFLUCFREQ) · (1.0-RIGIDFREQ) · (1.0-CHIFREQ) · (1.0-CRFREQ) · (1.0-OMEGAFREQ) · (1.0-NUCFREQ) · (1.0-PKRFREQ) · OTHERFREQ
Note that these moves are additionally split up into three basic types (see OTHERUNKFREQ and OTHERNATFREQ for choosing different subsets of degrees of freedom), each of which is again split into two variants, i.e., those completely randomizing the dihedral angle and those that attempt stepwise perturbations (→ OTHERRDFREQ). The default picking probabilities for OTHER moves are different from other move types in CAMPARI, since they are identical for all eligible degrees of freedom (and not identical for all residues containing at least one eligible degree of freedom). For each subcategory of degrees of freedom, sampling weights can be adjusted individually with the preferential sampling utility. Details and examples are given for the individual subcategories.

OTHERUNKFREQ

If single dihedral angle pivot (OTHER) moves are in use, and if the simulation utilizes entities (residues, molecules) that are not natively supported by CAMPARI, this keyword allows the user to choose the bulk sampling weight for degrees of freedom in those unsupported residues. The use of unsupported residues in simulations is explained in a dedicated tutorial.
To calculate the number of expected moves acting on single dihedral angles in unsupported residues, use:
NRSTEPS · (1.0-PARTICLEFLUCFREQ) · (1.0-RIGIDFREQ) · (1.0-CHIFREQ) · (1.0-CRFREQ) · (1.0-OMEGAFREQ) · (1.0-NUCFREQ) · (1.0-PKRFREQ) · OTHERFREQ · OTHERUNKFREQ
As mentioned above, these moves are additionally split up into two subtypes i.e., those completely randomizing the dihedral angle and those that attempt stepwise perturbations (→ OTHERRDFREQ). The default picking probabilities for OTHER moves are different from other move types in CAMPARI, since they are identical for all eligible degrees of freedom (and not identical for all residues containing at least one eligible degree of freedom). They can be adjusted at the level of individual degrees of freedom by the preferential sampling utility. As an example, this can be useful when sampling an unsupported polymer (e.g., a polyester) and greater sampling emphasis should be placed on backbone degrees of freedom.

OTHERNATFREQ

If single dihedral angle pivot (OTHER) moves are in use, and if not all OTHER moves are consumed on unsupported residues (→ OTHERUNKFREQ), this keyword allows the user to choose the bulk sampling weight amongst remaining OTHER moves for degrees of freedom that are supported natively by CAMPARI.
To calculate the number of expected moves acting on single dihedral angles natively supported, use:
NRSTEPS · (1.0-PARTICLEFLUCFREQ) · (1.0-RIGIDFREQ) · (1.0-CHIFREQ) · (1.0-CRFREQ) · (1.0-OMEGAFREQ) · (1.0-NUCFREQ) · (1.0-PKRFREQ) · OTHERFREQ · (1.0 - OTHERUNKFREQ) · OTHERNATFREQ
This keyword also controls the fraction of moves acting on dihedral angles frozen by default, but located in residues supported natively by CAMPARI. Compute expected number as:
NRSTEPS · (1.0-PARTICLEFLUCFREQ) · (1.0-RIGIDFREQ) · (1.0-CHIFREQ) · (1.0-CRFREQ) · (1.0-OMEGAFREQ) · (1.0-NUCFREQ) · (1.0-PKRFREQ) · OTHERFREQ · (1.0 - OTHERUNKFREQ) · (1.0 - OTHERNATFREQ)
Both subclasses are additionally split up into two subtypes i.e., those completely randomizing the dihedral angle and those that attempt stepwise perturbations (→ OTHERRDFREQ). The default picking probabilities for OTHER moves are different from other move types in CAMPARI, since they are identical for all eligible degrees of freedom (and not identical for all residues containing at least one eligible degree of freedom). They can be adjusted at the level of individual degrees of freedom by the preferential sampling utility. For the natively supported degrees of freedom, this could be useful in order to aid sampling of backbone degrees of freedom, whereas for the natively frozen degrees of freedom it could be used to selectively enable a few of those degrees of freedom (e.g., enable flexibility of arginine sidechains, but keep suppressing the methyl spins in hydrophobic residues).

OTHERRDFREQ

This keyword is completely analogous to PIVOTRDFREQ but applies to all moves of type OTHER instead of polypeptide backbone pivot moves.

OTHERSTEPSZ

This keyword is completely analogous to PIVOTSTEPSZ but applies to all moves of type OTHER instead of polypeptide backbone pivot moves.

CRFREQ

This keyword is a global frequency setting which controls and entire branch of Monte Carlo moves all sharing the feature that they are of the concerted rotation (CR) type and apply to polypeptides. The general idea of a CR move is to sample a stretch of polymer without changing the absolute positions and relative orientation of the termini. Six degrees of freedom are required to solve this constrained problem exactly but simpler methods exist to use more degrees of freedom to solve it approximately (→ CRMODE). The reader is referred to NUCCRFREQ for CR moves on polynucleotides.
There are four different types of CR moves for polypeptides provided in CAMPARI:

1. Exact CR moves utilizing both bond angles and dihedral angles along the polypeptide backbone to solve the closure problem exactly given fixed end constraints: these moves are based on the work of Ulmschneider and Jorgensen (→ ANGCRFREQ). (reference)
   
2. Exact CR moves utilizing φ-, ψ-, and ω-angles along the polypeptide backbone to solve the closure problem exactly given fixed end constraints: these moves are primarily based on the work of Dinner (→ TORCRFREQ and TORCROFREQ). (reference)
   
3. Exact CR moves utilizing just φ- and ψ-angles along the polypeptide backbone to solve the closure problem exactly given fixed end constraints: these moves are also based on the work of Dinner (→ TORCRFREQ and TORCROFREQ).
4. Inexact CR moves utilizing just φ- and ψ-angles along the polypeptide backbone to approximate a solution to the closure problem by linear response: these moves are based on the Favrin, Irbäck, and Sjunnesson (default fall-through for this branch). (references)
   

Note that the default picking probabilities for all CR moves (including those for polynucleotides) are chosen such that every final residue in a CR-eligible stretch of minimal length has equal probability. There are many factors influencing the eligibility, most notably terminal residues are excluded to different extents in the four algorithms described above, and cyclic residues (proline, etc.) are only supported in the exact torsional variants (caveats apply). The minimal length aspect is also handled differently in different algorithms. Specifically, the exact torsional variants will allow dynamic shortening of the entire stretch to include the minimal number of degrees of freedom (see TORCRMIN_DJ and TORCRMIN_DO; this also holds for the analogous move type for nucleotides → NUCCRMIN). This means that more residues are eligible. Conversely, both the exact bond angle variant and the approximate torsional variant enforce the lower limit specified for the stretch length leading to a more restrictive scenario (see UJCRMIN and CRDOF). Finally, the inexact torsional moves also may require additional buffer residues (see CRMODE). It is important to point out that this does not lead to equivalent numbers of attempted CR moves for all eligible residues. This is because eligible stretches are generally overlapping leading to a bias toward sampling residues that are part of many stretches. This is particularly true if the maximum stretch length possible is large (it results from a combination of the length of the polymer and keywords UJCRMAX, TORCRMAX_DO, TORCRMAX_DJ, NUCCRMAX, and CRDOF). The default picking probabilities for moves of this general type can be adjusted via the preferential sampling utility. Note that there is a very important difference compared to the application of user-level constraints. Whereas the latter render all possible CR stretches ineligible that contain the constrained residue, the preferential sampling utility will only alter the probability for a residue being picked as the final (most C-terminal) residue in a CR stretch. This means that the residue is generally not actually constrained even if the picking weight is chosen as zero.
The general appeal of exact CR methods partially lies in the reduced complexity of energy evaluations since the move only perturbs conformation locally and large parts of the polymer (assuming sufficient length) will remain static with respect to each other. This is never true for pivot-type moves applied to residues at the center of the chain. The other aspect which makes CR moves appealing is that they introduce correlation into the MC move set (the reader is referred to Vitalis and Pappu for further reading).
To compute expected numbers, use (same numbering as above):

1. NRSTEPS · (1.0-PARTICLEFLUCFREQ) · (1.0-RIGIDFREQ) · (1.0-CHIFREQ) · CRFREQ · ANGCRFREQ
2. NRSTEPS · (1.0-PARTICLEFLUCFREQ) · (1.0-RIGIDFREQ) · (1.0-CHIFREQ) · CRFREQ · (1.0-ANGCRFREQ) · TORCRFREQ · TORCROFREQ
3. NRSTEPS · (1.0-PARTICLEFLUCFREQ) · (1.0-RIGIDFREQ) · (1.0-CHIFREQ) · CRFREQ · (1.0-ANGCRFREQ) · TORCRFREQ · (1.0-TORCROFREQ)
4. NRSTEPS · (1.0-PARTICLEFLUCFREQ) · (1.0-RIGIDFREQ) · (1.0-CHIFREQ) · CRFREQ · (1.0-ANGCRFREQ) · (1.0-TORCRFREQ)

Finally, be aware that all concerted rotation moves involve steps that are difficult to parallelize. Thus, when CAMPARI's shared memory (OpenMP) parallelization is in use, some of the move types in this class are (currently) unavailable while others are supported but do not offer scaling for the geometric problem (only for the incremental energy calculations).

ANGCRFREQ

This keyword selects the (sub-)fraction of Ulmschneider-Jorgensen (UJ) CR moves (see J. Chem. Phys. 118 (9), pp4261-4271 (2003)) according to the formulas shown above. Like any other exact CR move implemented in CAMPARI, UJ-CR moves combine two strategies for efficient conformational sampling: the approach of Favrin et al. (→ CRMODE) is used to obtain a variable length pre-rotation which biases the end of the pre-rotation segment to a position with high chance of having at least one real solution when attempting to close it. The closure problem is solved exactly using a numerical root search for an algebraically transformed equation for the following six degrees of freedom:

1. Dihedral angle C_i-2, N_i-1, C_α,i-1, C_i-1 (φ_i-1)
2. Bond angle N_i-1, C_α,i-1, C_i-1
3. Dihedral angle N_i-1, C_α,i-1, C_i-1, N_i (ψ_i-1)
4. Bond angle C_α,i-1, C_i-1, N_i
5. Bond angle C_i-1, N_i, C_α,i
6. Dihedral angle C_i-1, N_i, C_α,i, C_i (φ_i)

This assumes the C-terminal constraint is defined by the "latter half" of residue i. The pre-rotation segment may be of variable length but must employ degrees of freedom immediately preceding the closure segmen(→ UJCRMIN and UJCRMAX). The use of this method in general and specifically within CAMPARI is marred as follows:

1. The chain closure algorithm relies on a search process to locate roots for a complicated equation, which makes repeated matrix operations necessary which generate a considerable computational overhead for a single UJ-CR move. This is true for all exact CR methods, even much more so for exact torsional variants than for UJ-CR moves (→ TORCRFREQ).
2. The inclusion of bond angles into the pre-rotation stretch is not a particularly useful extension but required for reasons of ergodicity. Additional parameters are needed to manage this aspect properly (→ UJCRSCANG). The inclusion of bond angles in the closure segments simplifies the root search procedure by eliminating branches for solution space and generally reducing the number of possible solutions. This makes the algorithm faster than comparable methods using dihedral angles only. However, varying bond angles cause two crucial issues:
   1. Allowing bond angles to change violates CAMPARI's typical paradigm of fixed geometry in MC calculations and therefore might invalidate some of the force field calibration done under this assumption. In general, it is very important to match the degrees of freedom chosen for the calibration phase of a force field with that for the application phase. The commonly held belief that the introduction of constraints does not alter the positions and relative weights of basins but merely influences barriers in the free energy landscape is not correct.
   2. CAMPARI currently has no way of independently sampling bond angles in Monte Carlo simulations. This means that effectively a subset of all bond angles are introduced as new degrees of freedom, for which is there is no a priori justification whatsoever (in other words: selectively sampling a few bond angles makes unjustified assumptions about the remaining bond angles). It is therefore recommended to use this feature with the utmost caution until a more sound implementation surrounding it is added. Presently, it may be most suitable as part of the MC move set in hybrid runs (see DYNAMICS) employing Cartesian sampling in the dynamics portions (see CARTINT) although this approach has its own caveats.

Note that there currently is no analogous implementation of this approach for nucleic acids even though Ulmschneider and Jorgensen developed one. The only CR moves available to nucleotides are exact torsional CR moves (→ NUCCRFREQ). Final remarks: 1) for details on picking probabilities, see above; 2) these moves are using no parallelization whatsoever for the closure problem when CAMPARI's shared memory (OpenMP) parallelization is in use, which is a limitation.

TORCRFREQ

Aside from the UJ-CR moves which employ bond angles (see ANGCRFREQ), analogous methods have been formulated to instead employ exclusively dihedral angles in both the closure and pre-rotation stretches. This keyword sets the frequency with which both subtypes of those moves occur during the simulation according to the formulas listed above. The preceding discussion has outlines the appeal of exact CR methods and it is not repeated here. Much like Ulmschneider and Jorgensen, CAMPARI employs a hybrid scheme of biased pre-rotations according to Favrin et al. (see CRMODE) and of exact closures according to Dinner. The latter half of the algorithm is the cost-intensive one. The algebraically transformed equation requires a numerical root search, for which we use a modified Newton scheme outlined below. Typically, multiple solutions need to be found, and a careful weighting and bias-removal strategy has to be employed to choose solutions with the proper probabilities (→ TORCRMODE). Those comments apply equally to exact polynucleotide CR moves (see NUCCRRFREQ). For polypeptides, there are two variants available which differ in which peptide torsions are used to close the chain (described below).
Note that proline (or any other cyclic residue with constrained flexibility around any of the backbone dihedral angles) causes additional problems. In theory, one could formulate algebraic solutions which skip the proline φ-torsion. Since the number and positions of proline residues in the closure stretch are not known a priori, this appears impractical. We therefore provide a coupling to (weakly biased and simplified) pucker moves (see PKRFREQ) which will simultaneously determine and propose a new pucker state while solving the chain closure problem. This means that:

1. Sampling of the φ-angle becomes coupled to the proline sidechain conformation (as it should be).
2. The acceptance rate for CR moves will be significantly lower due to the extra degrees of freedom included.
3. The sampling of the sidechain conformation will be weakly biased towards proper pucker states. In detail, some of the proposed closures will yield φ-angle values incompatible with sidechain closure and those will be discarded. For those which yield a sane φ-angle, a corresponding χ₁-value is proposed with bias toward closable states. One of two free bond angles is perturbed slightly in random fashion and the last one is given by the closure as usual.
4. Due to the above, it will be advantageous to not rely overly on CR-sampling for proline-rich systems - both for reasons of efficiency and accuracy. Conversely, it should be difficult to find a statistically significant impact of the sampler on global chain properties for polypeptides with low proline content.

Final remarks: 1) for details on picking probabilities, see above; 2) unfortunately, these and all other exact torsional concerted rotation moves are (currently) unavailable when using CAMPARI's shared memory (OpenMP) parallelization.

TORCROFREQ

This keyword lets the user set the fraction amongst exact, torsional polypeptide CR moves to include ω-angles in the formulation of the closure problem? Conversely, the remaining moves will use only φ/ψ-angles to close the chain. Expected numbers for either type are listed above. In detail the ω-variant uses the following six degrees of freedom:

1. Dihedral angle C_α,i-2, C_i-2, N_i-1, C_α,i-1 (ω_i-1)
2. Dihedral angle C_i-2, N_i-1, C_α,i-1, C_i-1 (φ_i-1)
3. Dihedral angle N_i-1, C_α,i-1, C_i-1, N_i (ψ_i-1)
4. Dihedral angle C_α,i-1, C_i-1, N_i, C_α,i (ω_i)
5. Dihedral angle C_i-1, N_i, C_α,i, C_i (φ_i)
6. Dihedral angle N_i, C_α,i, C_i, N_i+1 (ψ_i)

This implies that the carbonyl or carboxylate carbon atom of residue i with its three covalent bonding partners define the C-terminal constraint. The pre-rotation segments consists of a certain number of torsional degrees of freedom (including ω-angles) immediately preceding the closure segment.
Conversely, for the non-ω-variant we have:

1. Dihedral angle C_i-3, N_i-2, C_α,i-2, C_i-2 (φ_i-2)
2. Dihedral angle N_i-2, C_α,i-2, C_i-2, N_i-1 (ψ_i-2)
3. Dihedral angle C_i-2, N_i-1, C_α,i-1, C_i-1 (φ_i-1)
4. Dihedral angle N_i-1, C_α,i-1, C_i-1, N_i (ψ_i-1)
5. Dihedral angle C_i-1, N_i, C_α,i, C_i (φ_i)
6. Dihedral angle N_i, C_α,i, C_i, N_i+1 (ψ_i)

Again, this implies that the carbonyl or carboxylate carbon atom of residue i with its three covalent bonding partners define the C-terminal constraint. The pre-rotation segments consists of a certain number of torsional degrees of freedom (including ω-angles) immediately preceding the closure segment. This implies that the minimal peptides needed for these moves to be applicable is different: For those including ω-bond sampling, the minimal peptide is an uncapped peptide of three amino acids: the first ψ-angle serves as the pre-rotation segment, and the ω-, φ-, and ψ-angles of residues two and three serve to close the chain. For those not including omega sampling, the minimal peptide is an N-capped peptide of three amino acids in length. Here, the ω-angle of the first amino acid residue serves as the pre-rotation segment and the phi- and ψ-angles of the three peptide residue serve to close the chain. For details on picking probabilities, see above.
The need for different implementations is that the problems differ algebraically (for once) and that the stiffness of the ω-bond may make those moves using the ω-bonds in the closure particularly ineffective. This is not the only reason, however, to favor the non-ω-variant which is also better-behaved in terms of finding solutions to the closure reliably. Note that several diagnostics of the performance of exact CR methods are reported during the simulation and after its completion in the log-file.

CRMODE

This defines the mode to use for concerted rotation moves roughly according to the Favrin et al. reference: J. Chem. Phys. 114 (18), 8154-8158 (2001). In general, this type of move attempts to introduce correlation into a MC move by coupling several consecutive backbone angles (only φ/ψ are considered) together to minimize a cost function which in this case is the difference of the position of the last atom in the stretch compared to its original position. Larger biases lead to smaller moves and higher acceptance. More often than not, this algorithm suffers from its computational inefficiency. Because the loop is only approximately closed, energy evaluations of high complexity (even more expensive than a pivot move) are necessary. It is not recommended to use moves of this type extensively.

There are two modes available:

1. A matrix relating changes in the degrees of freedom to changes in the cost function (dr/dφ) is computed by considering effective lever arms. In this implementation six effective restraints are imposed through the three reference atoms (N, C_α, C) on the residue following the last one of those whose torsions are sampled (note, though, that algorithmically all nine Cartesian positions are used). Note that this mode therefore requires an additional buffer residue at the C-terminus. Specifically, sampling is possible only within an interval from the third residue (in addition to the ineligible terminal residues, there is a symmetry-creating N-terminal buffer residue as well) to the third last residue in each polypeptide chain. In that sense, these moves are trivially non-ergodic since they fail to sample a subset of the chosen degrees of freedom (i.e., those within terminal residues).
2. The dr/dφ matrix is computed by nested rotation matrices (propagating changes via matrix multiplication). This directly accounts for peptide geometry within the reference atoms and yields six actual restraints. Here, the reference atoms are C_α, C, and O on the last residue of which torsions are to be sampled. The implementation with nested rotation matrices is costlier and this mode is only marginally supported, i.e., offers very limited adaptability through the keywords below.

These inexact CR moves are supported exclusively for polypeptides and sample only their φ/ψ-angles. For details on picking probabilities, see above.

CRDOF

If inexact concerted rotation moves for polypeptides are in use (→ CRMODE), this keyword allows the user to provide the exact number of torsions to use each time such a move is performed. The default value is eight but a different number may be chosen as long as the chain is long enough to accommodate these moves. A minimum of seven degrees of freedom applies since the linear equations are otherwise overdetermined and only trivial solutions are (asymptotically) found. Note that this keyword is only supported if CRMODE is set to 1. Extensions of this to support mode 2 or to allow random, variable lengths during the simulations are currently not anticipated. This is due to the overall inefficiency of the Favrin et al. approach (see discussion here).

CRWIDTH

This keyword gives the standard deviation in radian of the random normal distribution underlying inexact concerted rotation moves for polypeptides (→ CRMODE), from which the (unbiased) displacement vectors are implicitly drawn. This corresponds to parameter "a" in the reference but is specified here as its inverse (a = 1/CRWIDTH). Note that the actual resultant distribution width is only set by this keyword if the bias toward minimizing the cost function is zero. If the latter is non-zero the resultant distribution width will be co-controlled by the setting for CRBIAS. Note that only values up to π/2 may be specified to avoid wrap-around artifacts which may upset the procedure of removing the bias from these moves.

CRBIAS

This keyword specifies the strength of the bias for inexact concerted rotation moves for polypeptides (→ CRMODE) and corresponds to parameter "b" in the reference. It essentially controls how close the end of the rotated segment will end up to its original position (satisfying the restraints). Unfortunately, this also co-regulates the step size, hence there is a need for parameter optimization (i.e., the variance of the resultant biased distribution cannot be controlled easily). Intuitively, the reason is that - in a linear response-type theory - tiny step sizes always represent one way of satisfying the restraint. Note that with a choice of zero for this keyword, these inexact CR moves relax to random pivot moves of multiple residues in a row (→ CRDOF) with a sampling width controlled by CRWIDTH. Conversely, when choosing very large numbers for this keyword, it should be kept in mind that the evaluation of the acceptance criterion requires inclusion of an exponential factor, exp[- (Δφ^T A Δφ) + (Δφ'^T A' Δφ') ]. Here, the primed quantities are for the reverse move. Matrix A is diagonal if this keyword is set to zero which implies A = A', and the bias correction is unity. For large values of CRBIAS, the two elements within the exponential become disparate in magnitude very quickly and the exponential may exceed numerical limits even for double precision variables. This may cause some compilers to throw exceptions. Note that the complete bias correction formula includes the determinant of matrix A as well.

UJCRBIAS

Despite its name, this keyword regulates the biasing strength for the pre-rotation steps in all exact CR methods, i.e., nucleic acid CR moves, UJ-CR moves and both types of exact polypeptide CR moves (→ ANGCRFREQ, TORCRFREQ, and NUCCRFREQ). The strength of the bias controls how close the end of the pre-rotation segment remains to its original position hence improving the chances for successful closure. This parameter is strongly co-dependent "with" the default distribution width in the absence of any bias (→ UJCRWIDTH). This keyword parameter is analogous to CRBIAS in the Favrin et al. scheme and is called "c2" in the UJ reference. It should be stressed that all caveats outlined above apply here as well.

UJCRWIDTH

Despite its name, this keyword regulates the general (in the absence of bias) width of the distribution (in degrees) sampled in the pre-rotation segment for all exact CR methods (→ ANGCRFREQ, TORCRFREQ, and NUCCRFREQ). As in the Favrin et al. scheme (which is practically embedded in all exact CR methods implemented in CAMPARI), the resultant width is co-dependent on the bias factor (see UJCRBIAS and for comparison: CRBIAS and CRWIDTH). It corresponds to "1/c1" in the UJ reference and therefore larger values give wider distributions.

UJCRSTEPSZ

The chain closure algorithm works in most exact CR implementations by reducing a multi-dimensional variable search to a 1D root-search, which is then solved by some form of step-through protocol and subsequent bisection. This keyword allows the user to choose the step-size for that root search in degrees for all exact CR methods. Currently, the UJ-CR method (→ ANGCRFREQ) uses a simple, non-adaptive stepping protocol (see also UJCRINTERVAL). Larger step-sizes there increase the speed of the algorithm significantly, but also increase the fraction of attempts in which no solution is found at all (a quantity reported at the end of the log-file). The recommended value by the authors is 0.05°. Conversely, the exact torsional CR methods for both polypeptides and polynucleotides (→ TORCRFREQ and NUCCRFREQ) employ a modified Newton scheme to map out the complete solution space in three hierarchical steps. In those cases, this keywords merely defines the largest step size to ever be used (i.e., if target function and derivative indicate that no root is near, the step size is not adjusted to very large values but instead to the value given by this keyword). For these methods, a setting of around 1.0 appears much more appropriate. In the future, the implementation of the UJ-CR method may be adjusted to use the same protocol as the torsional methods. For clarity, it shall be repeated that this keyword applies to all exact CR methods (but is inapplicable to inexact CR moves: → CRMODE). It is very important to understand that the numerical root search will invariably be unreliable, i.e., that there are conformations for which the function may be approaching zero asymptotically while also approaching imaginary solution space. This implies that with such a technique, it will be nearly impossible to eliminate all biases rigorously although it will be possible to reduce their amplitude below that of statistical noise, even when the settings are such that satisfactory computational efficiency is provided (which of course is a crucial element to consider for expensive algorithms such as exact CR methods).

UJCRMIN

Specifically for the bond angle-based Ulmschneider-Jorgensen algorithm (→ ANGCRFREQ), this specifies the minimum requested length (in terms of number of residues) for the pre-rotation segment in the implementation. Note that if no molecule in the system is at least UJCRMIN+4 residues long (two for closure, two terminal buffer residues that can be caps), CR moves will be disabled entirely. Due to the problems outlined above, this suboptimal implementation has not yet been improved. Note that UJCRMIN and UJCRMAX are analogous to keywords TORCRMIN_DO and TORCRMAX_DO, but use residue numbers instead of numbers of degrees of freedom. Another restriction is that - unlike for TORCRMIN_DO and analogous keywords - UJCRMIN is enforced strictly, i.e., candidate residues are only those that provide the correct padding on either side (for the exact, torsional variants, the specified minimum padding is generally adjusted to the absolute minimum for stretches that would otherwise be too short). Therefore, the implementation of the angular UJ-CR moves generally offers less flexibility.

UJCRMAX

Specifically for the bond angle-based Ulmschneider-Jorgensen algorithm (→ ANGCRFREQ), this keyword specifies the maximum requested length (in numbers of residues) for the pre-rotation segment in those moves. Note that this parameter is automatically reduced if a move is attempted for a molecule which is too short to allow the full range of segment lengths (but long enough to satisfy UJCRMIN of course). This will make it difficult to predict the resultant distribution of pre-rotation segment lengths (compare TORCRMIN_DO).

UJCRINTERVAL

Specifically for the bond angle-based Ulmschneider-Jorgensen algorithm (→ ANGCRFREQ), this keyword lets the user choose the size of the search interval for the one-dimensional root-search (see UJCRSTEPSZ). The algebraically isolated degree of freedom is scanned over the interval [φ-d;φ+d] where φ is the original value and d is the (half-)interval size specified by this keyword. The recommended value is 20.0°. Note that this implementation is unique to the bond angle UJ-CR method and offers much reduced overhead cost per CR move compared to the exhaustive search performed by exact torsional methods. The efficiency and justifiability of the method both rely on the crucial assumption that - given a typical pre-rotation - approximately one solution will be found in the scanned interval. If the number of solutions is often zero or larger than one, the algorithm violates detailed balance and the resultant distributions will be strongly biased. It is generally recommended to analyze the performance of the algorithm beforehand by checking for proper Boltzmann weights in the distributions of both torsional and angular degrees of freedom. This is most easily and meaningfully done employing only bond angle potentials (→ SC_BONDED_A) but no other terms in the Hamiltonian. Then, the distributions of the dihedral angles must be flat and those for the angular degrees of freedom must be such that to -k_bT·ln(p(α)) equals the acting bond angle potential on α.

UJCRSCANG

This keyword applies exclusively to the bond angle-based Ulmschneider-Jorgensen CR algorithm for polypeptides (→ ANGCRFREQ). It lets the user set a scaling factor to reduce the magnitude of pre-rotation perturbations of bond angle degrees of freedom (in the absence of pre-rotation bias, resultant width will be proportional to UJCRWIDTH·UJSCRANG → values less than unity are desirable). Large perturbations on those bond angles would reduce the efficacy of the method considerably due to the stiff potentials typically used to keep bond angles in the valid regimes. Note that the UJ-CR method never considers ω-angles for conformational sampling and that they are consequently excluded from pre-rotation sampling in their entirety. This is a bit of an arbitrary choice - in particular when considering the problems introduced by the bond angle sampling in the first place (discussion here) - and remedied in exact but purely torsional CR methods (→ TORCRFREQ). The parameter specified here corresponds to "1/c3" in the UJ reference.

TORCRMODE

Unlike standard MC moves (such as φ/ψ-pivot moves), exact CR methods do not constitute an ergodic move set beyond the subspace satisfying the constraint (which is of course invariant toward sampling on that manifold). This necessitates mixing exact CR moves with other types of moves to achieve sampling of the entire phase space. Moreover, they solve an analytical problem numerically with finite error rate, i.e., not all solutions are always found. If these errors are dependent on the "position" of the constraint, i.e., on polymer conformation, the resultant sampling is biased even though Jacobian corrections are applied. This small bias is nearly impossible to remove entirely. CAMPARI supports two implementations for exact, torsional CR methods:

• When set to 1, at each step, a superset of solutions is created containing the original solution, a set of alternative closures given the original pre-rotation state, and a set of new conformations with a given, altered pre-rotation state and a set of closures for that altered state. For each solution, the Jacobian determinants with respect to the closure constraint and the pre-rotation constraint are evaluated, multiplied, and a solution is picked using the net Jacobian as a weight factor. The chosen move is then evaluated via the acceptance criterion given the additional bias correction of evaluating the randomness of the pre-rotation move forward and backward as in the Favrin et al. scheme. In the absence of any pre-rotation bias, this algorithm is conceptually rejection-free. It also (in theory) satisfies detailed balance on account of the construction of the solution superset.
• When set to 2, at each step, a finite number of trials (see UJMAXTRIES) of pre-rotations according to the Favrin et al. scheme is performed. Closure is attempted and in case solutions are found, the possible closures along with the sampled pre-rotation constitute the set of possible moves. A random one is chosen (uniform probability) and the new conformation is evaluated via Metropolis with the Jacobian corrections for the proposed vs. the current state (with respect to both types of constraints) and the randomness correction for the pre-rotation step. Because solutions only need to be found given the pre-rotation, this algorithm is usually twice as fast as the one above given sane pre-rotation settings. This implementation does not satisfy detailed balance even in theory but attempts to remain globally balanced.

Note that this keyword applies to all exact, torsional CR methods, i.e., to torsional polypeptide CR (→ TORCRFREQ and TORCROFREQ) as well as to nucleic acid CR (→ NUCCRFREQ) but that it is not (yet) supported for the Ulmschneider-Jorgensen bond-angle CR algorithm (→ ANGCRFREQ) and inapplicable to the Favrin et al. scheme (→ CRMODE).

TORCRMIN_DO

This specifies the minimum requested number of degrees of freedom for the pre-rotation segment for exact CR moves for polypeptides utilizing ω-angles during closure (→ TORCRFREQ). Note that this minimum number is not rigorously enforced but will be ignored if closure residues too close to the N-terminus are used. This is done in the interest of generality and to prevent the code from disabling these types of moves frequently. It is therefore not as straightforward as one may think to compute the expected distribution of pre-rotation segment lengths (and which residues are part of them with what probability) for each polypeptide. Note that here numbers of degrees of freedom are specified whereas for the bond angle UJ method, numbers of residues are specified (→ UJCRMIN).

TORCRMAX_DO

This specifies the maximum requested number of degrees of freedom for the pre-rotation segment for exact CR moves for polypeptides utilizing ω-angles during closure (→ TORCRFREQ). Note that this maximum number is in fact a rigorous upper limit and never exceeded but that the length of some polypeptides in the system may be such that it is never realizable. In the latter case, there will be an additional complication in predicting the resultant distribution of pre-rotation segment lengths (see TORCRMIN_DO as well).

TORCRMIN_DJ

This keyword is exactly analogous to TORCRMIN_DO but applies to exact CR moves for polypeptides without using ω-angles in the closure.

TORCRMAX_DJ

This keyword is exactly analogous to TORCRMAX_DO but applies to exact CR moves for polypeptides without using ω-angles in the closure.

TORCRSCOME

This parameter is analogous to UJCRSCANG and scales down the magnitude of the step-size for ω-bonds in the pre-rotation segment of exact torsional CR methods for polypeptides. Since stiff torsional potentials usually act on ω-bonds (→ OMEGAFREQ), the likelihood of obtaining rejected moves mostly on account of excursions of the ω-angle is high. This unwanted behavior may be alleviated by employing small values for TORCRSCOME. Remember, however, that the pre-rotation step size will often be relatively small in general.

UJMAXTRIES

Despite its name, this keyword regulates the maximum number of pre-rotation sampling events to consider in exact, torsional CR methods with TORCRMODE set to 2. If no solution is found within UJMAXTRIES, the move is counted as rejected. Naturally, detailed balance is maintained only if there is always at least one solution found given the new pre-rotation (i.e., this keyword is rendered obsolete). As alluded to above, this is never the case for the entirety of a simulation. It is difficult to predict what setting in those cases would best preserve global balance. The main utility of this keyword, however, lies in different sampling applications, e.g., in the efficient and exhaustive sampling of different loop conformations given a fixed constraint.

NUCCRMIN

This keyword is analogous to TORCRMIN_DO but applies to exact CR moves for polynucleotides. Note that the sugar bond (C3*-C4*) is always excluded from pre-rotation sampling.

NUCCRMAX

This keyword is analogous to TORCRMAX_DO but applies to exact CR moves for polynucleotides. Note that the sugar bond (C3*-C4*) is always excluded from pre-rotation sampling.

PHFREQ

This is the frequency out of all sidechain moves (see CHIFREQ) whether to perform a (de)ionization MC move. These moves will be turned off automatically in case there are no titratable residues in the system (currently only polypeptide residues D, E, R, K, and H (use neutral form) are supported). Note that these are pseudo-MC moves, i.e., they do not interface intuitively with the rest of the MC code. This means that the guidance criterion for accepting / rejecting titration moves is based on a distinct and simplified energy evaluation which has no impact on the actual Markov chain. These moves are therefore analyzing (on-the-fly) an independently generated Markov chain (using whatever Hamiltonian was specified) but do not perturb the conformational ensemble generated by said Markov chain in any way. This essentially corresponds to the assumption that the generated ensemble is independent of titration states - an assumption which is always wrong but may - in certain circumstances such as extreme denaturing conditions - nonetheless be justified. These moves rely on environmental settings (PH and IONICSTR) and are required for obtaining output in PHTIT.dat. The default picking probabilities for ionizable residues are flat and cannot be altered.

PSWFILE

This keyword specifies name and location (full or relative path) of an optional input file parsed to alter the default picking probabilities for all types of moves in CAMPARI at most down to the residue level (but not further). In general, the idea of preferential sampling rests on the realization that any ergodic and unbiased move set is theoretically capable of producing a Markov chain yielding the correct phase space distribution. This means that the sampling weights given to degrees of freedom of the system need not be equivalent, but rather can be chosen arbitrarily (as long as a choice of zero somewhere does not eliminate ergodicity). Of course, the convergence properties of a Monte Carlo simulation are an exceptionally complicated function of the move set, and therefore deviation from default choices should be properly justified. Examples have been listed above, e.g. in the discussion of sidechain sampling.
CAMPARI generally allows the preferential sampling facility to overlap with user-level constraints. Constraints are applied first, and then picking probabilities are altered. In the process, it is possible to effectively introduce additional constraints on account of setting selected sampling weights to zero. This is tolerated as long as it does not deplete the pool for a class of moves entirely. In such a case, the program terminates with an error. There is a notable difference in zero sampling weights and constraint requests for concerted rotation moves of polymers (described elsewhere). Note that it is not possible to control frequencies that would lead to incorrect sampling. In particular, it is impossible to control picking probabilities for particle permutation moves, and particle insertion and deletion moves can only be controlled down to the molecule type level. Rigid-body moves are generally limited to the scope of molecules, not residues. The format of the input file is described elsewhere.

PSWREPORT

If the default picking probabilities are altered (→ PSWFILE) in torsional space Monte Carlo simulations, this keyword acts as a simple logical whether or not to write out a summary of the resultant picking frequencies for every move type that is active and has been modified (to the log-file).

Files and Directories:

---

(back to top)

Preamble (this is not a keyword)

In general, files and directories should be provided using absolute paths. This is often advantageous in deployment-based computing where relative directory structures and/or shortcuts may change or not exist. However, CAMPARI may fail in reading strings longer than 200 characters leading to truncation and subsequent failure. This should be kept in mind. Also, this section is merely a list of the auxiliary files potentially required by CAMPARI. The functionalities itself (including the files) are usually explained elsewhere (links are provided).

---

BASENAME

This keyword allows the user to pick a name for the simulation/system that is going to be used in the names of all structural output files. However, all other output files produced by CAMPARI use generic names and will be overwritten if simulations are continuously run in the same directory.

SEQFILE

This is the most important input file as it instructs CAMPARI which system to simulate. Its format and possible entries are explained in detail elsewhere.

SEQREPORT

This keyword is a simple logical (specifying 1 means "true", everything else means "false") that controls whether CAMPARI writes out a summary of some of the system's features initially. In detail, it will provide an overview of the identified molecule types, viz., the numbers of each molecule type present, the first instance, their formal concentration, their molecular mass, and their high-level suitability for performing CAMPARI-internal analyses. The latter would for example report that urea molecules are not suitable for peptide-centric analysis such as secondary structure analyses. In addition, the parsing of these molecule types into analysis groups is written to log-output.

PDBFILE

Among other functions, this is the main input file for providing a starting conformation for a simulation. See below for details.

DCDFILE

 See below.

XTCFILE

 See below.

NETCDFFILE

 See below.

FRZFILE

 See above.

PSWFILE

 See above.

SHAKEFILE

 See above.

PARTICLEFLUCFILE

This keyword is relevant only when ENSEMBLE is set to either 5 or 6 (ensembles with fluctuating particle numbers). It provides the location of the file that specifies the particle types that are allowed to fluctuate, the numbers of particles of those types to initially include in the system, and the chemical potentials of each fluctuating particle type (see here).

REFILE

 See below.

FEGFILE

This keyword lets the user specify name and location of the input file from which CAMPARI extracts which residues and/or molecules to subject to scaled interaction potentials with the rest of the system in free energy growth (ghosting) calculations.

DRESTFILE

 See below.

BIOTYPEPATCHFILE

 See above.

MPATCHFILE

 See above.

RPATCHFILE

 See above.

BPATCHFILE

 See below.

LJPATCHFILE

 See below.

CPATCHFILE

 See below.

FOSPATCHFILE

 See below.

SAVPATCHFILE

 See below.

ASRPATCHFILE

 See below.

NCPATCHFILE

 See below.

TORFILE

 See below.

POLYFILE

 See below.

TABCODEFILE

 See below.

TABPOTFILE

 See below.

TABTANGFILE

 See below.

EMMAPFILE

See below.

EMPROPERTYFILE

See below.

WL_GINITFILE

 See above.

EWWISDOMFILE

 See below.

ANGRPFILE

See below.

MOL2FILE

See above.

SYBYLLJMAP

See below.

MOL2FOSLIBFILE

See below.

MOL2_PDB_RELAXED

See below.

BBSEGFILE

This keyword lets the user choose an input file containing a map annotating φ/ψ-space for polypeptides with canonical secondary structure regions. This mapping is used to perform segment-based analyses of polypeptide secondary structure. CAMPARI provides two such files already (in the data/ subdirectory). These and the files' format are explained in detail elsewhere.

GRIDDIR

This keyword sets the directory CAMPARI browses to find input files for grid-assisted sampling (see above). CAMPARI provides by default sample input files in $CAMPARI_HOME/data/grids/. The code assumes filenames to follow a systematic naming convention "xyz_grid.dat", where xyz is the lower-case, three-letter code of the standard 20 amino acids.
This functionality is de facto obsolete and should not be used. It may be removed entirely in the future.

BESSELFILE

This keyword sets the location and name of the file CAMPARI expects to read for the tabulation of Fourier-Bessel (Hankel) transforms. This is required for diffraction analysis and is normally contained in the CAMPARI data directory. Details on the input are found elsewhere.

PCCODEFILE

 See below.

SAVATOMFILE

 See below.

ALIGNFILE

 See below.

TRAJIDXFILE

 See below.

MOL2AUXINDEX

 See below.

MOL2AUXINPUT

 See below.

FRAMESFILE

 See below.

TRACEFILE

 See below.

CFILE

 See below.

TRAJBREAKSFILE

 See below.

TRAJLINKSFILE

 See below.

CLUFILE

 See below.

NBLFILE

 See below.

CLUUNFOLDFILE

 See below.

CLUFOLDFILE

 See below.

NCDM_NCFILE

 See below.

NCDM_ASFILE

 See below.

NCDM_CFILE

 See below.

NCDM_FRAMESFILE

 See below.

Structure Input and Manipulation:

---

(back to top)

RANDOMIZE

This keyword determines the randomization aspects of initial structure generation. CAMPARI can generate default structures, completely random structures or, alternatively, use some or all available information from a structural input file. The outcome is determined both by the choices below and by the choice for keyword PDB_READMODE. In general, the program employs a hierarchical procedure whereby stretches of the input sequence are randomized residue-by-residue or molecule-by-molecule. If no excluded volume term has been enabled (SC_IPP or SC_WCA), the randomization will almost certainly produce structures with steric clashes (the majority of energy terms are ignored; for example, it is not possible to implement excluded volume only by means of tabulated potentials and to rely on randomization to produce a clash-free initial structure). The only other, possibly relevant terms during randomization are boundary potentials, bonded potentials (like torsional potentials), and bias potentials acting on individual degrees of freedom (compartmentalization potentials, distance/position restraints, and torsional restraints). It is a general limitation that other stiff potentials (including bias potentials acting globally such as spatial density restraints) as well as suboptimal clash resolution can easily generate very large energies and forces for the initial structures produced by randomization. While not generally a problem in Monte Carlo runs, the large forces will make any gradient-based simulation immediately unstable. In these cases, the cleanest workaround is to set up a hybrid calculation (see DYNAMICS) that first runs a number of Monte Carlo steps large enough to resolve all large forces (see CYCLE_MC_FIRST) followed by a single, very long dynamics segment (keywords CYCLE_DYN_MIN and CYCLE_DYN_MIN should both be set to NRSTEPS-1). Alternatively, two separate calculations can be run with the Monte Carlo one being restarted as a gradient-based one with the help of keywords RESTART and RST_MC2MD. Because of the large forces, CAMPARI will exit during a randomization encountering an unresolvable clash for a pure gradient-based calculation (including minimization) unless UNSAFE is set to 1. The definition of "clash" is provided primarily by keyword RANDOMTHRESH.
Any possible randomizations proceed according to the following three-step hierarchy, but not all steps are performed depending on the choice for RANDOMIZE.

1. If a structural input file was read and parts but not all coordinates of one or more complex molecules were read, CAMPARI may generate random conformations for sidechains (i.e. short branches off a main chain confined entirely to a single residue, which excludes crosslinks). This happens if one or more relevant heavy atoms in the sidechain are missing from structural input. The step is desirable because sidechains constructed using default dihedral angles are likely to create local but significant clashes. The interactions the sidechain in question is subjected to are evaluated with respect to all residues read at least in part from structural input and include an excluded volume bias (if either SC_IPP or SC_WCA is turned on), all enabled bonded potentials (SC_BONDED_B, etc.), any possible boundary potentials, torsional bias potentials (SC_TOR) Sidechain resampling treats every sidechain independently in the order they appear in the sequence by a Monte Carlo minimization procedure. Importantly, some natively frozen degrees in supported residues (such as the out-of-plane torsion χ₅ in arginine), can be moved during this procedure. CAMPARI will print, in the summary of the calculation, some information as to how many residues the procedure was applied to (if nonzero).
   At the end of the first stage, if performed (RANDOMIZE is 1 or 2), structural input has been augmented by missing sidechains, and the resultant conformations, aside from missing parts, should be free of major clashes that are not already present in the input pdb file. If this stage was skipped (RANDOMIZE is 0 or 3), missing sidechains are in default conformations, and clashes are extremely likely.
2. If a structural input file was read and parts but not all coordinates of one or more complex molecules were read, CAMPARI may generate random conformations for any missing tails. This is fully supported only in conjunction with option 3 for PDB_READMODE because otherwise at most a single C-terminal tail in the last processed molecule is treated this way. Missing chain-internal residues are a separate problem and not dealt with. The tails are built in a systematic and hierarchical Monte Carlo minimization procedure starting from the residue closest to the part that was read in and proceeding towards the respective terminus. Different tails are processed in the order that they appear in in the sequence. During randomization, every tail interacts at most with those atoms read in from file and those having already been placed as part of tails occurring before in the sequence. The interactions are an excluded volume bias (if either SC_IPP or SC_WCA is turned on), all enabled bonded potentials (SC_BONDED_B, etc.), torsional bias potentials (SC_TOR), any possible boundary potentials, and any distance and position restraints (SC_DREST) that are meaningfully modified at this stage by the procedure. "Meaningfully modified" is a complicated criterion at this stage for distance restraints. For example, considering a distance restraint between an N-terminal and a C-terminal tail in the same molecule really requires optimizing them simultaneously which is not possible in the aforementioned hierarchical framework. Thus, the results are likely similary suboptimal as for the case of chemical crosslinks, which is what is described next. If the tails contain residues participating in intramolecular crosslinks, these crosslinks will at best be satisfied approximately. During the randomization procedure, they are whenever possible implemented in the same way as during the final simulation, i.e., by means of bonded potentials (which are thus required for obtaining a meaningful result). This is the case if a crosslink exists entirely within the same tail or if it links a tail to part of the coordinates having been read in. The situation is more complicated if a crosslink links tails in different molecules or two different tails in the same molecule. In these cases, results may be entirely unsatisfactory because all the burden of achieving a "closable" conformation is deferred to the tail occurring later in the sequence whereas the tail occurring earlier ignores crosslink constraints entirely. At the end of the second stage, if performed (RANDOMIZE is 1 or 2), all molecules read in at least partially from structural input should be in a state that is defined by the input or built randomly in a way that is approximately free of intramolecular clashes. If RANDOMIZE is 1, and there is more than one such molecule, they should additionally be free of intermolecular clashes. If the second stage is not performed but eligible tails exist, they are simply constructed in default polymer conformations and disregarding any clashes or crosslinks. This is unlikely to be useful and will almost certainly cause an error unless the simulation starts with a sufficient number of or uses only Monte Carlo steps.
3. The third stage loops over all molecules and deals, for each molecule in this order, with internal followed by external degrees of freedom. The internal conformation of molecules for which no structural input was provided is constructed randomly unless RANDOMIZE is 0 or 3 or unless the molecule has no relevant internal degrees of freedom. This random conformation is constructed as follows. For each residue, CAMPARI reserves RANDOMATTS total attempts per residue and applies a threshold penalty of RANDOMTHRESH kcal/mol. This penalty corresponds to the required mean interaction energy per relevant (i.e., included by the short-range cutoff) residue pair. The relevant energy terms are a possible excluded volume bias and any torsional potentials but do not include boundary potentials or other bonded potentials. Energies are evaluated for residue pairs involving the current residue and all residues further toward the N-terminus of the stretch (already processed) and the single residue immediately following in the stretch (not yet processed). If the sum of these energies plus the difference in any torsional potential energies from the initial state is less than the threshold, the algorithm proceeds to the next residue. Thus, the excluded volume contribution is evaluated as its absolute value, which means that the threshold will have to depend on the particular choice of Lennard-Jones parameters (→ PARAMETERS). If the threshold criterion is passed, the calculation proceeds to the next residue.
   This randomization occurs in three hierarchical phases (1/3 each of the total attempts per residue). In the first, only freely rotatable backbone angles (excluding all pucker and ω-angles) are considered, e.g., the φ/ψ-angles of polypeptides, or any backbone-like angles in unsupported residues. In the second stage, rotatable sidechain angles (excluding those in native CAMPARI residues that are frozen by default) of the current residue are added to the set as well. In the third stage, all aforementioned degrees of freedom for the residue immediately prior in the sequence are added. It is obvious that even with all 3 stages triggered, a stretch may be "stuck", e.g. fold back onto itself, thus requiring a completely new solution. Resolving such situations is not supported as this would lead to an uncontrollable runtime. Instead, the energetically most favorable conformation of the sampled ones is picked and a warning or error (depending on keyword DYNAMICS) is produced.
   For molecules free of internal crosslinks, the stretch considered is the entire molecule. If there are internal crosslinks, the molecule is divided hierarchically into stretches. Stretches under no constraint are processed sequentially (from N- to C-terminus). Crosslink-constrained stretches are parsed, and CAMPARI tries to find a hierarchical order starting with the "innermost" stretches in the hope of arriving at a solution that is both clash-free and satisfies all intramolecular crosslinks exactly. Priority is given to crosslinks over clashes because it is very easy to arrive at structures that are more or less clash-free and have a dramatically perturbed crosslink geometry that cannot relax properly without a complete reorganization of the molecule. This procedure can be very slow because RANDOMATTS" attempts per residue are used to construct a potentially closable stretch conformation (using an empirical bias in addition to the aforementioned potentials) followed by an energetic evaluation of all identified loop closures. If the solutions have too many clashes or none are found, the entire cycle is repeated up to RANDOMATTS times. In the case of coupled crosslinks (for example, nested or staggered), it remains likely that the hierarchical procedure encounters a dead end and exits with a warning or error as before.
   If successful, at the end of this step, the molecule processed should be in one of four possible states:
   • In a newly generated, random, and clash-free conformation that satisfies any intramolecular crosslinks exactly (RANDOMIZE is 1 or 2 and no structural input was provided).
   • In a conformation partially or fully supplied by structural input with any tails randomized (RANDOMIZE is 1 or 2 and structural input was provided, see above).
   • In a conformation partially or fully supplied by structural input with any tails in default conformations (RANDOMIZE is 0 or 3 and structural input was provided, see above).
   • In its default conformation, which is generally not clash-free, with all (if any) intramolecular crosslinks broken (RANDOMIZE is 0 or 3 and no structural input was provided).
   In the second step of the third stage, the rigid-body coordinates of the molecules are dealt with (position of centroid and rotational orientation). This step is skipped only if structural input was provided and RANDOMIZE is either 0 or 1. It is performed in all other circumstances.
   If the molecule is not connected to another molecule occurring earlier in the sequence by an intermolecular crosslink, the procedure is simple. There is only a single phase with the same number of total attempts (now per molecule). Energies are evaluated in pairwise fashion for all molecules occurring prior in sequence input vs. the current molecule. As before, the computed energy is taken as the mean interaction energy per relevant (i.e., included by the short-range cutoff) residue pair. The relevant energy terms are a possible excluded volume bias, all enabled bonded and torsional bias potentials (although they matter only for intermolecular crosslinks), any boundary potentials, and all relevant position and intermolecular distance restraints all of which are taken as absolute values. The step ends as soon as the computed mean interaction energy is below the specified threshold.
   Conversely, a molecule bound by an intermolecular crosslink to a molecule earlier in the sequence may not be placed freely. CAMPARI analyzes intermolecular crosslinks to determine a hierarchy that prioritizes molecules with more crosslinks (these should ideally be placed as early as possible in the sequence). While the higher-priority molecule is placed freely, a lower priority molecules instead satisfies the crosslink exactly, and the molecule is placed with the only randomization coming from the central 3 dihedral angles of the actual crosslink. This may require deferring this step until the higher priority molecule has been placed. Depending on the conformations of the involved molecules determined previously, this can easily lead to an unresolvable clash, which, as before, will be reported as a warning or error. Notably, there is no mechanism in place to displace molecules that have already been placed in previous iterations of the loop. This means that it is advantageous to place molecules joined by an intermolecular crosslink directly adjacent in the sequence file. If a molecule is crosslinked to more than one molecule occurring earlier in the sequence, a warning is produced and at most one of these crosslinks is respected in the generated conformation. Intermolecular crosslinks will at best be satisfied approximately in such a case (the same is true if only the position of a lower priority molecule in a crosslinked pair is determined by structural input).
   At the end of the second step of the third stage, the molecule should be placed randomly in the simulation container without clashing with any molecules occurring earlier in the sequence. It should also satisfy intermolecular crosslinks to at most one molecule occurring earlier in the sequence. Note that even if PDB_READMODE is 3, it is not possible for a molecule requiring random placement to precede, in sequence input, a molecule placed based on structural input. The only molecules not placed randomly at the end of this stage are those read from structural input if RANDOMIZE is 0 or 3. To continue, the second stage proceeds to the next molecule until there are no unprocessed molecules left. The placement of molecules is very unlikely to be clash-free if the density is high (for example, liquid water).

This summarizes the procedure CAMPARI uses to generate initial conformations where all or parts are missing. As mentioned, if the resulting starting structure is not free of clashes or other problems, a warning or error is produced. The options selectable for RANDOMIZE are listed below. To understand the implications, it is necessary to refer to the description above:

0. Minimal randomization is performed. It is the same as option 1 below if a structural input file is given that provides coordinates for all parts of the system. It is the same as option 3 if no structural input file whatsoever is provided. With this option, any missing tails in molecules with partial input are built in default conformations. No intramolecular crosslinks missing from structural input are satisfied initially. All molecules missing from structural input are built in default conformations and placed randomly in the box. Intermolecular crosslinks are satisfied as possible (see above).
1. Supplementary randomization is performed, which is the default. This option is the same as option 0 if a structural input file is given that provides coordinates for all parts of the system. It is the same as option 2 if no structural input file whatsoever is provided. With this option, any missing tails in molecules with partial input are built in random, clash-free conformations that satisfy any crosslinks at best approximately. All molecules missing entirely from structural input are built in random conformations that satisfy intramolecular crosslinks exactly, and are placed randomly in the box. Intermolecular crosslinks are satisfied as possible (see above).
2. This is the same as option 1 above only that the rigid-body coordinates are randomized even for those molecules read fully or at least partially from the structural input file. This option is the same as option 3 if a structural input file is given that provides coordinates for all parts of the system. This option can be useful for generating random starting structures for studies of the assembly of a protein complex from rigid components.
3. This is the same as option 0 above only that the rigid-body coordinates are randomized even for those molecules read fully or at least partially from the structural input file. This option is the same as option 2 if a structural input file is given that provides coordinates for all parts of the system.

Some additional technical information is provided next. In a small molecule screen in sampling mode, the screened molecules are always read in from file. However, these coordinates (absolute and conformation-wise) may or may not be desirable. The fixed/static part of the system (if any) will generally have to be read-in completely from a structural input file, which implies choosing mode "0" above. If this is not the case, users are advised to build in an extra step to generate a complete input structure. For the small molecules, MOL2RANDOMIZE controls the randomization options.
It is a very important restriction that initial structure randomization does not observe user-level constraints. In order to have a degree of freedom, which is accessible to randomization, start out in a well-defined state, randomization of the corresponding class of degrees of freedom must be disabled entirely (in which case the initial state comes either from the CAMPARI default or - more likely - from structural input). This is somewhat similar to the limitation regarding restraint potentials before. Stiff potentials acting globally such as polymeric biases, density restraints, and secondary structure biases are ignored by the initial structure generation. This means that a (partly) random structure can be clash-free, can satisfy all crosslinks, yet can still be subjected to very large forces initially. Performance-wise, the initial structure randomization procedure (like all initial setup) is unaware of the shared memory (OpenMP) parallelization of CAMPARI. Computationally, it may thus be more efficient to use an explicit Monte Carlo simulation to generate initial structures in comparable fashion (although the overall cost is often negligible regardless).
In general, the importance of initial structure randomization lies in avoiding initial structure biases that may be difficult to detect. Alternative procedures found in the literature often use simple reference states (fully extended chains) or results from high-temperature runs of an experimentally determined structure. With these approaches, it is quite difficult or even impossible to rigorously assert that the final results are not subtly influenced by the choice of starting conformation(s). Conversely, the random structures generated by CAMPARI are usually so independent from each other that the convergence of results is a good indicator of statistical error at the level of the chosen analysis. This is not to say that they are not biased by the simplified Hamiltonian used to construct them, which they of course are. Intramolecular crosslinks in particular generate constraints that can restrict the available space down to just a few "clusters" of solutions, and CAMPARI's hierarchical procedure may well pick with a strong bias from this set. Disregarding crosslinks, the excluded volume-centric Hamiltonian used in randomization will differ from the one used in the actual production simulations. This in itself is a bias of course. In most cases, the production Hamiltonian differs dramatically, in particular since it will generally contain net attractive potentials. This means that the beginning of a simulation corresponds to a quench/relaxation scenario, similar to what is seen experimentally in temperature-jump experiments or computationally in methods like simulated annealing. This instantaneous quench, broadly speaking, leads to the sampler taking the system to configurations, which are (more) compliant with the production Hamiltonian and most easily accessible from the starting configuration. Here, "most easily accessible" depends critically on the chosen sampler. Thus, memory can be retained and errors can be masked if the starting structures are not completely independent. It should be kept in mind that it is, outside of trivial cases, never possible to know a priori the subspace of configurations relevant to the system under the chosen conditions as this is usually the question one tries to answer by means of simulations. Errors pertaining to a lack of exhaustiveness can therefore not be diagnosed or understood based on randomized starting structures. For this, a robustness across different samplers and simulation lengths
Note that in replica exchange or MPI averaging runs, all replicas will start from different conditions unless RANDOMSEED is given explicitly by the user.

RANDOMATTS

If any type of initial structure randomization is requested, this keyword sets the general number of maximum attempts in randomizing the permissible degrees of freedom for a single residue or molecule. Large numbers (> 10000) may produce unacceptably slow performance when trying to randomize a long, complex polymer and/or a dense fluid. Large numbers in conjunction with too small a threshold can also be counterproductive. This is because this scenario corresponds to a hierarchical minimization and thus may limit the search space for dependent elements of the hierarchy. This problem can be exacerbated for intramolecular constraints, in particular coupled ones.

RANDOMTHRESH

If any type of initial structure randomization is requested, this keyword sets the universal energy threshold to be applied with respect to energetic penalties for excluded volume, boundary potentials (rigid-body only), and bonded terms (e.g., torsional potential energies). Roughly speaking, for every residue or molecule being processed, there will be a given number of interacting residues (depending on the short-range cutoff). While the total energy is used to pick the best current solution, the threshold is evaluated against a mean interaction energy per residue pair, and this is the value specified by RANDOMTHRESH (in kcal/mol). Different terms contribute for different stages of randomization as described above. All these terms are pure penalty terms and cannot yield negative energies. Specifying small values for the threshold will generally yield lower starting energies because they make the procedure more minimization-like. There is a caveat in that parts of the randomization procedure are hierarchical, i.e., the solvability of a subproblem may depend on the solution of previous problem. Since the algorithm has very limited capability to "go back," a well-minimized result for a particular task may actually prevent subsequent problems from being solved satisfactorily. It is thus recommended to keep the threshold large enough and the number of attempts small enough that solutions remain diverse.

MOL2RANDOMIZE

If a small molecule screen is performed, the system consists of a fixed and a variable part. While keyword RANDOMIZE describes the initial randomization of the fixed part (and, in virtually all circumstances, this should really be fixed in a small molecule screen, so RANDOMIZE should be "0"), MOL2RANDOMIZE controls how the input coordinates found in the main input file of the screen are treated:

0. The coordinates of the small molecules are not randomized. This is a good option to use if alignment to a tether group defined in a reference molecule occurs but can, depending on the sampler, lead to biases if this is not the case. Such bias might stem from absolute positions in the main input file that are systematic (which is frequently the case).
1. The rigid-body coordinates of the small molecules are randomized if and only if no alignment to a tether group defined in a reference molecule occurs. This is the most common and default option.
2. The rigid-body coordinates of the small molecules are randomized. This happens after any possible alignment to a tether group defined in a reference molecule (otherwise it would be ineffectual). The decisions made by the matching algorithm (see MOL2RMSDTHRESH) are not affected by this.
3. The internal conformations (conformers) of the small molecules are randomized. This should only be used in conjunction with proper bonded potentials acting on dihedral angles. Most curated libraries of small molecules contain only sterically feasible conformers, and conformer randomization should not be necessary. This option should only be used in very particular circumstances.
4. Both the internal conformations (conformers) and rigid-body coordinates of the small molecules are randomized. This should only be used in conjunction with proper bonded potentials acting on dihedral angles.

Note that the rigid-body randomizations are aware of the fixed part of the system and of relevant position and distance restraints, in particular those created via MOL2DRESTMODE. Conversely, the conformer relaxation is unaware of the receptor and most restraints. The main usefulness of these randomization procedures stems from the fact that, unlike a Monte Carlo or hybrid sampler using a full Hamiltonian, they are tailored to prioritize the removal of steric clashes and compliance with harmonic restraints (position/distance) and nothing else. As a result, they do not get stuck as easily.
To help with efficiency, the rigid-body randomization of the small molecules will generally try to refer to a subvolume of the chosen simulation container. If position and or distance restraints are found, this subvolume is defined entirely by these restraints plus a buffer parameter that is at least 10Å and at most twice the maximum extent of the cuboid defined by the input conformer. Distance restraints with large target distances should be avoided for this to work efficiently. If no such restraints are found, the fixed part of the system is measured, and the buffered volume is derived from this extent instead. If neither is present, randomization defaults to the normal container defined by SHAPE and BOUNDARY. Using periodic boundary conditions or using restraints and/or a fixed system that favors positions outside of the container might lead to unwanted consequences in a small molecule screen when used in conjunction with options 2, 4, and possibly 1 above. These result from the randomization volume no longer being a proper subvolume.
The logic behind the idea of focusing the randomization of small molecule positions is to enable users to define a spatially large simulation container without relying on excessively large numbers for RANDOMATTS to achieve compliance with restraints and/or "find" the receptor. Note that RANDOMTHRESH should be set to a relatively small value for restraints to matter sufficiently during randomization.

PDBFILE

This keyword provides the (base)name and location of a structural input file in pdb convention. This can either be a pdb trajectory (for analysis) or, more commonly, the intended (partial) starting conformation of the system. The two interpretation modes are switched based on keyword PDBANALYZE and have different requirements. General and specific formatting information for pdb files (which also apply to keyword PDB_TEMPLATE) are given in the corresponding input file documentation. The parsing of pdb files depends on a number of auxiliary keywords, specifically PDB_READMODE, PDB_HMODE, PDB_INPUTSTRING, PDB_TOLERANCE_A, PDB_TOLERANCE_B, PDB_R_CONV, and PDB_MPIMANY.
If trajectory analysis mode is enabled, CAMPARI will interpret the input to this keyword either as a pdb trajectory file (using the MODEL/ENDMDL records) or as the first in a series of systematically numbered files (→ PDB_FORMAT). For the former, the MODEL / ENDMDL syntax is checked and has to be interpretable (the actual numbering on the MODEL line is ignored, however). For the latter, a systematic numbering scheme is inferred from the provided file name (based on plain numbers, or numbers with leading zeros). In this scenario, the first of such files should be provided; CAMPARI will then try to extract the numbering scheme and open NRSTEPS-1 consecutive snapshots. Note that in this mode the filename must not contain any additional numeric characters (i.e., foo_001.pdb is permissible while ala7_001.pdb is not). To choose between single-file and multiple-file formats, keyword PDB_FORMAT is used. If the set of numbered files or the trajectory do not provide enough snapshots to satisfy the selected value for NRSTEPS, CAMPARI will either terminate with an error (if any MPI parallel execution mode is used) or dynamically adjust the run length (if serial or OpenMP-only code is used). The latter can be confusing and may produce nonsensical output from built-in analysis routines (if the run is shortened enough to effectively disable an analysis that would have been enabled given NRSTEPS, it is not guaranteed that all output from this analysis is correctly suppressed). Since the point here is to analyze a given trajectory, CAMPARI expects the specified sequence input to match exactly what is present in the pdb input file. This does not necessarily require that all atoms in every residue are read successfully, but it does require that all residues are found. The use of pdb files with atoms that were not read successfully or missing is of course quite confusing depending on the types of analyses to be performed. This is because the positions of these atoms will be reconstructed, i.e., some of the coordinates entering analysis may be derived, arbitrary, or, in the worst case scenario, numerically ill-defined. While possibly tolerated by CAMPARI, it can be extremely confusing to supply a pdb trajectory (or set of files) that do not all contain the exact same set of atoms with the exact same names. The total number of rebuilt atoms will be reported at the end of the run to log output. Mismatches between CAMPARI's representation of a residue and what is present in the pdb file may be circumvented with keyword UAMODEL and can always be masked by renaming them to be recognized as unsupported residues as demonstrated in Tutorial 10.
The more common use of this keyword is for CAMPARI to attempt to read an external file to construct an initial nonrandom conformation for the system. Depending on the setting for RANDOMIZE, only some of the information may be used. Naturally, the system (sequence) in the pdb file has to be at least partially consistent with the choices made via SEQFILE. Note that parallel runs can use multiple input structures (→ PDB_MPIMANY). In particular, CAMPARI will not reorder atoms or residue blocks in the pdb except for very specific exceptions. In a box with a protein, solvent, and ions, it is therefore necessary that the order of the components in sequence input is the same as in pdb input. If not, most of the system information will be discarded. The input file can be processed with varying degrees of leeway and two different paradigms (both depend on the choice for PDB_READMODE).
Note that it is not possible to directly start a simulation from a structure provided in a binary trajectory file format. In this case, however, CAMPARI can be used to extract a suitable pdb file from the trajectory with the help of keywords PDBANALYZE, XYZPDB, XYZOUT, XYZMODE, and - for example - DCDFILE.
Lastly it is important to mention that PDBFILE provides some functionality that is overlapping with that provided by PDB_TEMPLATE. Specifically, runs containing residues not natively supported by CAMPARI require the topology of those moieties to be inferred from file. If an analysis run operates on a single pdb file, a trajectory file in pdb format or a series of pdb files, or if a simulation run is supposed to start from a specific structure supplied via PDBFILE, then PDBFILE can (but need not) serve the function of topology inference as described for PDB_TEMPLATE. Conversely, PDBFILE never replaces the function of PDB_TEMPLATE in the other contexts it is relevant in, viz., to provide a map from binary trajectory input file to CAMPARI, and to serve as a reference structure for alignment.

XTCFILE

This is only relevant if PDBANALYZE is true: It then specifies name and location of the trajectory (xtc format) to analyze. Like all other xtc-related options, this is only available if the code was in fact compiled and linked with XDR support (→ installation instructions). See PDB_TEMPLATE for instructions how to convert binary trajectory files with non-CAMPARI atom order. If the analysis run is parallel (→ REMC), an example is given elsewhere. Because binary trajectory files are not annotated, many of the above formatting options apply, at most, to the template. Specifically, keywords PDB_READMODE, PDB_HMODE, PDB_TOLERANCE_A, PDB_TOLERANCE_B, PDB_R_CONV, and PDB_NUCMODE are all irrelevant for the processing of the actual information in the xtc file whereas XYZ_FORCEBOX is respected. Should the data in the trajectory file be corrupted or exhausted before NRSTEPS snapshots have been read successfully, CAMPARI will either terminate with an error (if any MPI parallel execution mode is used) or dynamically adjust the run length (if serial or OpenMP-only code is used). Binary xtc files have a header section for each snapshot that specifies box coordinates, the number of atoms, and additional information. All of these except the number of atoms are ignored during read-in.

DCDFILE

Analogous to XTCFILE, this keyword is only relevant if PDBANALYZE is true: It then specifies name and location of the trajectory (dcd format) to analyze. See PDB_TEMPLATE for instructions how to convert binary trajectory files with non-CAMPARI atom order. Binary dcd files have a single header section at the beginning of the file that specifies several control parameters including the number of atoms. All of these except the number of atoms are ignored during read-in (as are the box coordinates, if present).

NETCDFFILE

Analogous to XTCFILE, this keyword is only relevant if PDBANALYZE is true: It then specifies name and location of the trajectory (NetCDF format) to analyze. Like all other NetCDF-related options, this is only available if the code was in fact compiled and linked with NetCDF-support (→ installation instructions). See PDB_TEMPLATE for instructions how to convert binary trajectory files with non-CAMPARI atom order. Unlike xtc or dcd files, NetCDF files do not need to be parsed sequentially and are in general fully annotated. CAMPARI thus determines immediately whether NRSTEPS snapshots are present in the file. If not, CAMPARI will adjust this number to the available one. If any MPI parallel execution mode is used, this is the minimum across all MPI processes (which read different files). Binary NetCDF files encode a well-defined standard. For trajectory data of particle systems, CAMPARI resorts to the standard developed for the AMBER program suite described elsewhere both in writing and in reading. Because NetCDF files do not need to be processed sequentially, they offer an additional benefit of analyzing snapshots in a specific order that is not the same as the original trajectory (→ FRAMESFILE for details).

FRAMESFILE

If PDBANALYZE is true, it is possible for CAMPARI to analyze a specific set of frames from the trajectory file (see PDB_FORMAT) rather than the entire trajectory. It is also possible to give every analyzed snapshot a sampling weight, and both functionalities are implemented by this keyword. Example applications are the extraction of structural clusters from a trajectory or the reweighting of biased simulations.
Most input trajectories currently need to be processed sequentially (this applies to xtc, dcd, and pdb trajectory files, i.e., PDB_FORMAT is 1, 3, or 4). For these, the list of requested frames is sorted first, and duplicates are removed. This means that any newly written trajectory files (→ XYZOUT) will have exactly the same order of snapshots as the input. Conversely, the snapshots encoded in individual pdb files and NetCDF trajectory files (PDB_FORMAT is 2 or 5) can be accessed in arbitrary order. For these two settings, the frames file is processed "as is" unless there are floating point weights per snapshot or unless this is a parallel trajectory analysis run. Frames files processed "as is" have the advantage that they can arbitrarily reorder and duplicate individual simulation snapshots, which is relevant, for example, in the construction of synthetic trajectories.
It is important to note that the settings for NRSTEPS and EQUIL and all related frequency settings for analysis routines (see corresponding section) lose their straightforward interpretations if not all snapshots in the original trajectory are processed exactly once and in sequence. For the case of a processed frames file (sorted and free of duplicates), the analysis frequencies will still refer to the original, full trajectory file. This means that CAMPARI will read all frames sequentially and increment step counters accordingly. However, all the frames that are not part of the list are simply skipped. This implies that it is possible for a selection of 20 frames from a larger trajectory to fail to produce any output for polymeric quantities if POLCALC is set to 10, 5, or even 2 (simply on account of chance). It will therefore generally be easier to set such frequency flags to 1 if processed frame lists are used (this is the only setting that guarantees that the number of analyzed snapshots will be exactly proportional to the size of the list). Conversely, for a frames file used "as is," the unused frames are never read and no step counters are incremented. This means that the effective step becomes the processing of the frames file itself. Returning to the above example, a selection of 20 (possibly duplicated) frames from a larger trajectory will in this case always produce output for polymeric quantities if POLCALC is set to any value of 20 or less.
As mentioned above, the frames file allows the user to alter the type of averaging that is normally assumed for CAMPARI analysis functions. By default, each data point (trajectory snapshot) contributes the same weight to computed averages or histograms (distribution functions). This implied that the input trajectory conforms (was sampled from) the distribution and ensemble of interest. If, however, the input trajectory does not correspond a well-defined ensemble (or to a different one), it is common and possible to apply snapshot-reweighting techniques based on analyses of system energies or coupled parameters using weighted histogram methods. The result is a set of weights for each snapshot, which allows simulation averages and distribution functions to conform to that target distribution and ensemble. As an example, one may combine all data from a replica-exchange run (that no longer conform to a canonical ensemble at a given temperature), use a technique such as T-WHAM to derive a set of snapshot weights for a target temperature that was not part of the replica-exchange set, and then use this input file containing the weights to compute proper simulation averages at the target temperature.
The input file for this functionality is very simple and explained elsewhere. There are three important points of caution. First, floating-point weights imply that floating-point precision errors may occur. The implied summation of weights of very different sizes may then become inaccurate. CAMPARI provides a warning if it expects such errors to be large (based purely on the weights themselves). Second, snapshot weights do not influence the values reported for instantaneous output such as POLYMER.dat or for analyses that do not imply averaging (such as structural clustering). Third, reweighting techniques have associated errors that are difficult to predict. Simultaneous assessment of statistical errors via block averaging or similar techniques is therefore strongly recommended.

PDB_FORMAT

This simple keyword lets the user select the file format for a trajectory analysis run:

1. CAMPARI expects a single trajectory file in pdb-format using the MODEL /ENDMDL syntax to denote the individual snapshots.
2. CAMPARI expects to find multiple pdb files with one snapshot each that are systematically numbered starting from the file provided via PDBFILE.
3. CAMPARI expects to find a single trajectory in binary xtc-format (GROMACS style).
4. CAMPARI expects to find a single trajectory in binary dcd-format (CHARMM/NAMD style).
5. CAMPARI expects to find a single trajectory in binary NetCDF-format (AMBER style). (reference)
   

Note that .xtc, .nc, and .dcd trajectory files are not annotated and that the order of atoms between the file and CAMPARI's inner workings must be consistent. Since this is almost never true for binary trajectory files obtained with other software, CAMPARI offers the user to provide a pdb template which contains the order of atoms in the binary file in annotated form (see PDB_TEMPLATE).

PDB_READMODE

This keyword (integer) controls how the information in a supplied pdb file is meant to be used. (see keyword PDBFILE and input file documentation). A maximum of three options is available with the first one offering restricted support depending on the type of calculation:

1. CAMPARI attempts to read in the Cartesian coordinates of heavy atoms from the pdb file, proceeds to extract the values for CAMPARI's "native" degrees of freedom (i.e., the unconstrained dihedral angles and the rigid body degrees of freedom in Monte Carlo or torsional molecular dynamics runs → CARTINT), and lastly rebuilds the entire structure using the determined values as well as internal geometry parameters for the constrained internal degrees of freedom (extracted from high resolution crystallographic databases). This hybrid approach will often lead to a propagation of error along the backbone of longer polymers and is therefore unsuitable for reading larger proteins or particularly for macromolecular complexes. While it is never a useful choice for structural input that contains complex molecules but does not exactly encode the same covalent geometry as what CAMPARI uses by default, it is of limited usefulness even when these conditions are met. Specifically, it should be used in conjunction with high precision PDB input (see PDB_INPUTSTRING and PDB_OUTPUTSTRING) for the remaining cases (essentially, CAMPARI runs in rigid-body/dihedral angle space not relying on any structural input). This input mode does not support the processing of unsupported residues (see PDB_TEMPLATE) and, upon discovery of unsupported residues in sequence input, will be changed automatically to option 3 (the default) below. There are further limitations to this mode. For example, it requires strictly that the first 3 atoms (in CAMPARI convention) are present for each molecule (unless there are less atoms in the molecule or it is a water, ammonium, or methane molecule), it does not recover (read) values for degrees of freedom in supported residues that are considered nonnative (e.g., hydrogen positions in methyl groups irrespective of values for TMD_UNKMODE and OTHERFREQ), and the read in is stopped as soon as there is any mismatch in sequence and structure inputs at the residue level (the remaining degrees of freedom missing from the pdb file are treated according to keyword RANDOMIZE). Overall, this option should be considered largely obsolete.
2. CAMPARI attempts to read in the Cartesian coordinates of all atoms from the pdb file and uses those explicitly (i.e., it implicitly adopts the encoded geometry even for degrees of freedom that are normally constrained within CAMPARI). This will produce warnings if very unusual bond lengths or angles are encountered (see PDB_TOLERANCE_A and PDB_TOLERANCE_B), which are most often indicative of missing atoms in the pdb-file (in particular termini and hydrogens). Some of these problems will be dealt with automatically, but it is always recommended to check the file {basename}_START.pdb to make sure that no drastic deviations occur. Such drastic deviations are almost inevitable if backbone atoms are missing from polymer chains, and in these cases preprocessing of the pdb file may be necessary. Conversely, if the input geometries are merely distorted (experimental structures do not have arbitrary resolution or correctness), the automatic rebuilding CAMPARI may perform should probably be circumvented by increasing the thresholds for PDB_TOLERANCE_B and PDB_TOLERANCE_A. Of course, atoms might be missing in the input PDB file, and their positions will be reconstructed based on standard covalent geometries and on default values for dihedral angles. This applies to missing hydrogen atoms or missing sidechains in crystal structures. The rebuilt coordinates do not consider an energy function, and use of TMD_RELAX, which offers localized relaxation in a hierarchical and focused manner, is recommended.
   Note that simulations with constraints cannot preserve arbitrarily precise values for the constrained degrees of freedom upon restarts of simulations from standard pdb files. If the sampler is in Cartesian space and constraints are used, keyword SHAKEFROM is a potential remedy. Conversely, simulations in rigid body or torsional space have no way of relaxing input geometries to the built-in (or any user-desired) values for bond lengths, angles, and rigid dihedral angles. In these cases, it may be useful (like for mode 1 above) to modify the assumed pdb format to improve precision (see PDB_INPUTSTRING and PDB_OUTPUTSTRING) and/or to rely on restart files whenever possible. The limitations of mode 2 are that atom names must be understood (automatic translation routines are in-place but not exhaustive) and that the read-in stops as soon as there is any mismatch in sequence and structure inputs at the residue level (the remaining degrees of freedom missing from the pdb file are treated according to keyword RANDOMIZE).
3. This mode is identical to mode 2 above with the exception of how mismatches between pdb and sequence input are addressed. Here, CAMPARI will assume that all of the structural input is potentially relevant but that some parts of polymer chains may be missing, which is a common issue with experimental structures. It will thus try to match maximally long sequence stretches from individual molecules (in the order of appearance in the sequence) with the sequence in the pdb file. Read-in stops as soon as structural input is exhausted or whenever an unresolvable mismatch occurs. An unresolvable mismatch occurs when, for a molecule present in sequence input, no information whatsoever can be found in the pdb or when the pdb file contains any residue that cannot be mapped to the current or next molecule in the sequence. This mode enables the generation of initial structures with multiple C- and N-terminal tails to polymers being rebuilt. The rebuilding is under the control of keyword RANDOMIZE. Note that the proper construction of N-terminal tails strictly requires the first 3 main-chain atoms of the subsequent residue to be read in correctly from the input file. This option is the default option. Since longer tails can easily get stuck in the randomization procedure, the initial reconstruction might have to be repeated a few times. In addition, the use of TMD_RELAX is recommended to try to resolve conflicts at the sidechain level not only in general but specifically for the newly built tail(s). It is currently not (yet) possible to reconstruct closed loops. In order to use structures with missing loops, it is recommended, as it is for all PDB files (see Tutorial 16 for an example), to use the sequence file tool shipped with CAMPARI. It will automatically break such loops into two capped tails.

More information, in particular on naming and other pdb conventions is provided in the documentation to the structural input file itself and for keywords PDB_INPUTSTRING, PDB_R_CONV, PDB_NUCMODE, and PDBFILE.

PDB_INPUTSTRING

This keyword allows changing the assumed PDB formatting string (Fortran) for PDB files. This is required to make CAMPARI be able to read in altered PDB files produced by the analogous keyword PDB_OUTPUTSTRING or by other software or scripts. The default is "a6,a5,1x,a4,a1,a3,1x,a1,i4,a1,3x,3f8.3" (with the quotes). Because Fortran in general deals poorly with string-based I/O, any improper use of this keyword can easily lead to abnormal program termination. In the format string, the letters (a, i, f) give the type of variable, which must not change. The numbers give the fields lengths, and these can be customized for variables of type integer ("i") or real ("f"). It is also possible to modify the field widths of string variables ("a") but is not possible for extra content to be read, i.e., the resultant behavior is undefined. The only exception to this is the second variable (atom number), which is of the "wrong" type here because these values are ignored on input. This particular field width can be increased without harm. It is of course intended and required that the corresponding output string format uses an integer field here, by default "i5" instead of "a5".
Common problems with standard PDB files, which can be addressed at least in part by the format string, are that the integer number for atom index overflows, that the chain indicator becomes fused to neighboring columns (because of overlong residue names or large residue numbers), that the residue number column overflows, that the coordinate entries get fused or overflow (if absolute coordinates are not centered at small (in absolute magnitude) values), or that the coordinate precision is insufficient for recovering exact covalent geometries based on this information alone.

PDB_HMODE

If structural input from a pdb file is requested in modes 2 or 3 (see PDB_READMODE and PDBFILE) or if a trajectory analysis run) is being performed, this keyword offers two choices for dealing with hydrogen atoms (which will often be missing from the pdb input file):

1. CAMPARI will attempt to read in the Cartesian coordinates of all hydrogen atoms directly and only rebuild those hydrogen (and other) atoms which cause a geometry violation defined by keywords PDB_TOLERANCE_B and PDB_TOLERANCE_A.
2. CAMPARI will rebuild all hydrogen atoms according to its underlying default models for local geometry in chemical building blocks. This is most useful if hydrogen atoms are missing entirely from the input file.

Note that the second option is not available for analysis runs operating on binary trajectory files in which the atom number match has to exactly match sequence input anyway, and which are typically only generated by computer simulation themselves. Similarly, the keyword has no influence on unsupported residues where there is no knowledge of missing hydrogen atoms or reference geometries (everything is defined by the pdb input file).

PDB_NUCMODE

For processing structural input, keyword PDB_NUCMODE explained below is ignored. It is listed here nonetheless to explain what CAMPARI actually does when reading in a pdb file supplied via PDBFILE or via PDB_TEMPLATE:
If the input file is in CAMPARI convention, i.e., the O3* oxygen atom is part of the same residue as the phosphate it belongs to, the read in is consistent with internal convention. If, however, the input file is in pdb convention (also used by almost all other simulation software), i.e., the O3* oxygen atom is always part of the same residue as the sugar it belongs to, a heuristic is used to avoid an incorrect assignment. This heuristic relies on the geometry of the input structure being sane as it checks the bond distance to the appropriate phosphorous atom. For the heuristic to be successful, it is essential that the 4-letter atom name for the phosphorous atoms is always " P ". In terminal residues, it is possible that two oxygen atoms appear, and in this case it is important that they have different names (" O3*" and "2O3*" in standard CAMPARI convention).
As long as atom names can be parsed (see also below), the user should therefore not have to worry about the placement convention used in pdb input files. This implies that it is possible to supply a binary trajectory file (for example via DCDFILE) written in the non-CAMPARI convention of assigning the O3*-atom to the residue carrying the sugar it is attached to by the use of an appropriate template.

PDB_R_CONV

CAMPARI can in general process different conventions for the formatting of PDB files. A large fraction of simple atom naming convention multiplicities is handled automatically without the use of any keywords. PDB_R_CONV allows the user to select the format a read-in pdb-file is assumed to be in to be able to deal with more severe discrepancies. Possible choices currently consist of:

1. CAMPARI format (of course suitable for reading back in any CAMPARI-generated output even if PDB_NUCMODE was used → see above).
2. GROMOS format (nucleotide naming). This option offers very little unique functionality since most of the supported conversions are handled automatically regardless of the setting for this keyword. It is primarily used to handle the GROMOS residue names for nucleotides (ADE, DADE, and so on).
3. CHARMM format (in particular atom naming, cap and nucleotide residue names and numbering (patches), ...). Note that there are two exceptions pertaining to C-terminal cap residues (NME and NH2) which arise due to non-unique naming in CHARMM: 1), NH2 atoms need to be called NT2 (instead of NT) and HT21, HT22 (instead of HT1, HT2), and 2), NME methyl hydrogens need to be called HAT1, HAT2, HAT3 (instead of HT1, HT2, HT3). For nucleotides, there is an additional exception to 5'-residues carrying a 5'-terminal phosphate (the hydrogen in the terminal POH unit needs to be called "5HO*" instead of " H5T"). This is again due to nonunique naming conventions within CHARMM.
4. AMBER format (atom and residue naming in particular for nucleotides). Note that this option is the least tested one. Please let the developers know of any additional issues you may encounter.

As mentioned above, this setting is relevant for files requiring more advanced reinterpretation (such as the patch conventions in CHARMM / NAMD). It should allow the user to keep the manual processing of pdb files to a minimum. However, support is generally limited to standard biomacromolecules supported within CAMPARI, and in most cases does not extend to small molecules or unusual polymer residues. This is the twin keyword to PDB_W_CONV below.

XYZ_FORCEBOX

This keyword is a combined input/output keyword and explained below. It can be used to process structural input with molecules that are broken up for periodic systems.

PDB_TOLERANCE_A

This setting allows the user to override CAMPARI's built-in defaults for the tolerances it applies on a read-in structure (usually xyz from pdb). Since it is not always easy to distinguish distorted structures from missed input, the code applies a tolerance when comparing read-in bond angles to the internal reference value (which is derived from crystallographic databases). The default is an interval to either side of 20.0° and this setting can be expanded or contracted using this keyword. If a violation is found, the code usually overrides the faulty value with the default since it assumes that atomic positions were missing. This can sometimes lead to unwanted effects which can be avoided by setting this to a large number.

PDB_TOLERANCE_B

This is analogous to PDB_TOLERANCE_A, but allows the user to change the interval for considering bond length exceptions. The difference here is that two numbers are required: a lower fractional (down to 0.0) and an upper fractional number (preferably larger than 1.0 of course). This is because bond lengths ranges are inherently not normalized and in addition nonlinear (exceptions with too long bond lengths are much more frequent). The default is an interval between 80% and 125% of the crystallographic reference value (settings 0.8 and 1.25).

PDB_TEMPLATE

This keyword allows the user to provide name and location of a pdb file that serves in possibly several auxiliary functions. A template pdb file is relevant in the following circumstances:

• In a trajectory analysis run, it can serve as a map to correct a mismatch in atom ordering between a binary trajectory file (dcd, xtc, NetCDF) and CAMPARI's intrinsic convention. Typically, a pdb file provided by the program having generated the binary file will serve this purpose. In order for the map to work, it is crucial to ensure that every single atom to be read in has a proper match (by atom name) in the pdb file, i.e., it is not tolerable to provide a pdb template with missing atoms or with atom names that CAMPARI cannot parse. In general, CAMPARI's pdb parser is relatively flexible and allows additional control via PDB_R_CONV. It is typically not possible, however, to correct mismatches in the grouping of atoms into residues (with the exception of the processing coordinates for nucleotides, see PDB_NUCMODE). This is because CAMPARI treats a change in residue number on consecutive coordinate records as the signal for delineating entries by residue. Conversely, the absolute numbers are irrelevant.
• The template pdb file can simultaneously serve as a reference structure if alignment is requested in trajectory analysis runs (→ ALIGNCALC). This has the same requirements as the previous function meaning that it is not trivially possible to align trajectories using an incomplete or different reference structure. However, alignment to a reference structure is a functionality offered by almost every molecular visualization program.
• In all types of runs, the template pdb file can be used to infer the topology of residues not natively supported by CAMPARI. This is crucial for handling these systems. Importantly, using the template for this purpose decouples the topology determination from structural input for simulation runs, which allows initial randomization (possibly partial) of systems containing such unsupported residues. The content of the template should contain each unique unsupported residue in the same order that they appear in in the sequence file. For unsupported residues that are part of a polymer chain, each occurrence in the sequence must have its own entry also containing the immediate N- and C-terminal sequence context in the polymer chain. This is unless consecutive unsupported residues are part of the same polymer chain (sequence context is mutually shared). If the unsupported residue is a small molecule (single residue), the template should contain a single instance. Beyond this, there are precise requirements for both input files. They are listed in the corresponding documentation for both the sequence file and the pdb file. Assuming both files to be properly formatted, CAMPARI then does the following:
  
  1. From the sequence file, the number of unknown residues and their intended linkages are extracted.
  2. The template is read and the atomic indices delimiting all unknown residues are extracted. Single-residue molecules that are unsupported and occur repeatedly in the sequence can (but need not necessarily) reuse the same indices as the first instance of this type (matched by residue name in the pdb file). The procedure will try to match sequence input with the data in the template while allowing for gaps in both: i) supported residue present in sequence input and not required as context for unsupported polymer residues are skipped; ii) supported residues present in the template are ignored; iii) unsupported single-residue molecules occurring a second or more times in sequence input are skipped if (and only if) a different unsupported residue is found next in the template. The last condition means that the second occurrence of an unsupported single-residue molecule may or may not be used (depending on sequence input). After this, basic parameters such as the effective residue radius and the reference atom are inferred. It is therefore important that the conformation of the residue in the pdb file is somewhat representative.
  3. The remainder of the system topology is constructed. The internal order of atoms for unsupported residues always reflects the order in the input pdb file exactly. The pdb template file is parsed again to ensure that the required sequence context is present. This applies only to those unsupported residues that are part of a chain (polymer).
  4. From the pdb atom names, the chemical element is guessed (C, O, N, H, P, S, halogens, various metals, and metalloids) and the mass is set to that of an appropriate atom type in the parameter file (identification by attempts to match mass and valence). The assignment will be poor if the parameter file does not support the chemical element in question. Further details are found elsewhere. This can later be overridden by a biotype patch and/or a combination of other patches.
  5. A new biotype is created for every new atom type encountered. This biotype is initialized to be empty with the exception of keeping the atom name and the (already) assigned atom type. The numbering of these new biotypes continues from what the highest number in the parameter file is. It is therefore not possible to use the parameter file for these assigned biotypes directly. Instead, it is recommended to use a biotype patch or specialized patches. The assignment of an atom type is sufficient to provide basic support, so for certain applications no patches may be required. For residues duplicated in sequence relative to the template, this and all subsequent information is simply copied from the first (and usually only) instance. For valid unsupported residues with identical names, which occur multiple times in the sequence, only the type (but not the geometry) information is copied from the reference instance.
  6. The covalent bond information is used to infer the molecular topology (including a detection of rings). This defines the Z-matrix entries (internal coordinate representation) for unsupported residues. Similarly, the linkage to covalently bound residues that are either supported or also unsupported is inferred. In the process, rotatable dihedral angles are detected automatically. This procedure, which explicitly tests for bond angle or length variations upon rotation, is critical to most subsequent assignments.
  7. Given a set of pdb names, atom types, valences, and a topology, CAMPARI attempts to conclude by analogy whether the residue conforms to the backbone of one of the supported polymer types (currently, polypeptides and polynucleotides). If it does, as many internal pointers as possible are set to identify the residue accordingly (this does not work for single-residue molecules).
  8. If a residue is recognized as being part of a supported polymer type, the topology itself is corrected (the goal is that it should make no difference to CAMPARI whether a residue is supported or whether it is masked (by changing the name) as an unsupported one and all the information has to be inferred from the input structure). Further corrections pertain to the setup of interactions, etc. Note that the match cannot always be perfect, e.g., fudge factors that are not zero or unity in conjunction with MODE_14 being 2 and INTERMODEL being 1 may lead to energetic inconsistencies. The interaction setup relies on determining local rigidity via its knowledge of which dihedral angles are rotatable. Due to code-specific reasons (scanning for short-range exceptions, exclusions, etc), it is highly recommended to parse the chain into residues such that any pair of atoms in residues i and i+2 is separated by a least four rotatable bonds.
  9. All flexible dihedral angles may be made part of basic sampling routines if the simulation is in internal coordinate space. These are the torsional dynamics sampler (→ TMD_UNKMODE for details) and the basic Monte Carlo moves for degrees of freedom of this type (→ OTHERUNKFREQ). Furthermore, access will be granted to the specialized samplers if the residue is detected as eligible. This, however, may sometimes lead to an altered interpretation of the absolute values of certain dihedral angles or even alter details of the sampler slightly, e.g., the pucker sampling of proline-like, unsupported residues may end up perturbing different sets of auxiliary bond angles.
  10. If analyses are requested, these routines will respond to the unsupported residue according to the values set in the previous steps. Basically, the better the match to natively supported entities is, the more analysis functionalities will be available. Straightforward cases depend only on Cartesian coordinates (e.g., RHCALC or CONTACTCALC), whereas polymer type-specific analyses (e.g., DSSPCALC) require an unsupported residue to be recognized as the corresponding polymer type. Care must be taken in mixed polymers or other exotic cases, and it may occasionally be necessary to disable certain analysis routines.
  The success of the inference depends very strongly on the input pdb file. Atom names and in particular atom order should be - if possible - made as compliant with CAMPARI's internal convention as possible. The code will report if analogy-based settings have been applied. In general, inference regarding polymer type is restricted to the backbone level with the small exception of detecting residues eligible for pucker sampling (see PKRFREQ and SUGARFREQ). The inferred topology is available from the starting Z-matrix coordinate file. Except in output pdb files, unsupported residues will be referenced with the three-letter code "UNK" (for example in the header to the contact map output file). Note that simulation runs featuring unsupported residues will generally require the application of patches to the energy function (see BIOTYPEPATCHFILE, MPATCHFILE, LJPATCHFILE, BPATCHFILE, NCPATCHFILE, CPATCHFILE, RPATCHFILE, ASRPATCHFILE, SAVPATCHFILE, and FOSPATCHFILE).

PDB_MPIMANY

For MPI parallel (multi-copy) runs, this logical keyword (1 means "on") allows the user to provide different starting structures via pdb files for different replicas (copies). The keyword is irrelevant in parallel trajectory analysis mode where this is the required and automatic behavior.
CAMPARI used to restrict the use of this keyword to certain classes of calculations, but this is no longer the case. There are some risks associated with PDB_MPIMANY as follows: In internal coordinate space, the default accuracy of pdb files is too low to ensure that the covalent geometries across multiple input structures are sufficiently similar even when they were exactly the same in the underlying full precision coordinates. The distortions in covalent geometries mean that the simulated systems are no longer exactly the same, which is undesirable in cases where this is implied because the copies are coupled, e.g., in replica exchange or PIGS calculations. The magnitude of this effect can be diagnosed, for instance, by analyzing these geometries (→ INTCALC directly or by comparing short-range energy terms, in particular bonded ones (such as bond angle potentials). The effect can be circumvented with the help of keyword PDB_INPUTSTRING, which allows redefining the pdb format to be high-precision. This is the most obvious solution but only available if pdb files can be generated from higher-precision coordinates to begin with. In Cartesian space simulations, geometries usually relax to their force field minima unless holonomic constraints are in use (in which case keyword SHAKEFROM can be used to circumvent precision issues with PDB_MPIMANY).
If this option is active, CAMPARI expects to find systematically named pdb files with the base name given via keyword PDBFILE. The naming is analogous to the convention CAMPARI uses for outputs of parallel runs and also identical to what parallel trajectory analysis runs require. It is explained elsewhere. A list of keywords specific to running CAMPARI in parallel is found found below.

MOL2AUXINPUT

If a small molecule screen is performed, and the specified files for MOL2FILE and (optionally) MOL2_REFMOL contain not only atoms for the small molecules to be screened but also coordinates belonging to the fixed part of the system, this keyword is a required input file to tell CAMPARI so. The file should contain the indices (in CAMPARI numbering) of the atoms additionally specified in the input file. It is a requirement that they have to have smaller indices than the atoms of the screened molecules (that is, they must occur first). The format is shared with other atom index input files (see elsewhere).

MOL2_PDB_RELAXED

If a small molecule screen is performed in scoring mode, then this keyword allows the user to supply an additional PDB file containing (only) the fixed part of the system. This PDB file is processed according to the same rules and conventions outlined elsewhere. The structure read in this way is used as the reference conformation for computing the "Protein" energies in the finite difference that is reported in the scores. Thus, it can be used to correct scores for what is often referred to as "strain" in the complex (caused by the presence of the small molecules). For a completely fixed base part, this simply creates an offset whereas for a partially dynamic base part, it can also change the rankings (because without using this keyword, the scores would all reference different "Protein" energies.

Energy Terms:

---

(back to top)

Preamble (this is not a keyword)

There are various classes of energy terms. They include the core nonbonded energy terms (SC_IPP, SC_ATTLJ, SC_POLAR, SC_IMPSOLV, SC_TABUL, SC_WCA, and ghosted variants thereof), which typically use a truncation scheme involving neighbor lists. When CAMPARI's shared memory (OpenMP) parallelization is in use, these interactions are calculated in parallel using a detailed scheme operating at the neighbor lists level to achieve load balance. The second class of energy terms are those that are not pairwise, require no cutoff scheme, and are truly "local". Some of these, such as bonded potentials, e.g., bonded terms are generally split by residue across threads without difficulty, i.e., there are sums of independent terms. The final class of energy terms are various restraint (bias) terms requiring a synthesis of information across many residues, e.g., spatial density restraints. For these, the documentation below lists explicitly the parallelization support in each case.

---

HSSCALE

This keyword controls a generic scaling factor for size parameters (Lennard Jones σ_ii and σ_ij) that were read in from the parameter file. This fundamentally alters the excluded volume properties of the system and also affects derived properties. Motivation for using this keyword (which naturally defaults to 1.0) may arise during parameter development or in specialized calculations.
The directly affected potentials are SC_IPP, SC_ATTLJ, and SC_WCA, but the ABSINTH solvation model will also generally respond to it (this depends on the use of "radius" overrides in the parameter file. The analogous modification of scaling universally the ε parameters is achievable by means of the scale factors (SC_IPP, SC_ATTLJ, and SC_WCA).

SC_IPP

This keyword allows the user to specify the linear scaling factor controlling the strength of the inverse power potential (IPP) defined as:

E_IPP = c_IPP·4.0ΣΣ_i,jε_ijf_1-4,ij·(σ_ij/r_ij)^t

Here, the σ_ij and ε_ij are the size and interaction parameters for atom pair i,j, f_1-4,ij are potential 1-4 fudge factors (see FUDGE_ST_14) that generally will be unity, r_ij is the interatomic distance, t is the exponent, and the (double) sum runs over all interacting pairs of atoms. Lastly, c_IPP is the linear scaling factor controlled by this keyword which - unlike most other scaling factors for energy terms - defaults to 1.0. In most applications, the inverse power potential will be the repulsive arm of the Lennard-Jones potential (t = 12 → 12^th power, see IPPEXP). The interpretation and application of the provided parameters (see documentation and keyword PARAMETERS) can be controlled through keywords SIGRULE, EPSRULE, INTERMODEL, FUDGE_ST_14, and MODE_14. Note that the use of the Weeks-Chandler-Andersen (WCA) potential (→ SC_WCA) is mutually exclusive with inverse power potentials.

IPPEXP

This keyword allows the user to adjust the exponent (an even integer that defaults to 12) for the inverse power potential. An important restriction is that many of the optimized loops in dynamics calculations do not support any other choice except 12. Note that very large numbers will of course - possibly in compiler-dependent fashion - slow down code execution due to the increasing complexity of expensive operations in innermost loops. By (formally) setting this to a value greater than 100, CAMPARI is instructed to replace the IPP potential with a hard-sphere (HS) potential, which is only available in pure Monte Carlo runs. In this case the scaling factor is ignored, the "infinity"-value (penalty for nuclear fusion) is determined by the setting for BARRIER, and the use of a size reduction factor (HSSCALE) is strongly recommended. In hard-sphere potentials, any energy readout for the IPP term should now be in multiples of BARRIER, and all persisting non-zero values would indicate a frustrated (non-relaxable) system. The actual value specified for IPPEXP is then irrelevant.

SIGRULE

This keyword defines the combination rule for combining the size parameters of Lennard-Jones (and WCA) potentials, i.e., how to construct σ_ij from σ_ii and σ_jj if σ_ij is not provided as a specific override in the parameter file (for details see PARAMETERS).
The choices are:
 1) σ_ij = 0.5·(σ_ii + σ_jj) (arithmetic mean)
 2) σ_ij = (σ_ii · σ_jj)^0.5 (geometric mean)
 3) σ_ij = 2.0·(σ_ii^-1 + σ_jj^-1)^-1 (harmonic mean)

EPSRULE

Analogous to SIGRULE, this keyword defines the combination rule for interaction parameters of Lennard-Jones potentials. The same options are available and the same caveats apply with respect to overrides in the parameter file.

SC_ATTLJ

This keyword allows the user to specify the linear scaling factor controlling the strength of the dispersive (van der Waals) interactions defined as:

E_ATTLJ = -c_ATTLJ·4.0ΣΣ_i,jε_ijf_1-4,ij·(σ_ij/r_ij)⁶

Here, the σ_ij and ε_ij are the size and interaction parameters for atom pair i,j, f_1-4,ij are potential 1-4 fudge factors (see FUDGE_ST_14) that generally will be unity, r_ij is the interatomic distance, and the (double) sum runs over all interacting pairs of atoms. Together with an inverse power potential with scaling factor 1.0 and exponent 12 (see SC_IPP), the canonical Lennard-Jones potential is constructed if the scaling factor, c_ATTLJ, is set to unity.

INTERMODEL

This very important keyword controls the exclusion rules for short-range interactions of the excluded volume and dispersion types (see SC_IPP, SC_ATTLJ, and SC_WCA). For Monte Carlo or torsional dynamics simulations assuming rigid geometries, the computation of spurious (constant) LJ interactions is inefficient. Conversely, in Cartesian sampling, bonded interactions are almost always parametrized with all 1-4, and certainly with all 1-5-interactions in place. The latter refer to intramolecular atom pairs separate by either exactly three (1-4) or four (1-5) bonds. The ABSINTH implicit solvation model, which is one of the core features of CAMPARI, was parametrized with a reduced interaction model. Hence, this keyword allows two choices:

1. Consider only interactions which are not rigorously or effectively frozen when using internal coordinate space sampling. This setting for example excludes all interactions within aromatic rings. As for determining 1-4-interactions, the rules outlined under MODE_14 apply.
2. Consider all interactions separated by at least three bonds to be valid. This is the default setting for molecular mechanics force fields. Note, however, that many of these interactions are quasi-rigid and that their computation is somewhat nonsensical even in a full Cartesian description. Also note that due to the inherent assumption that every bond is rotatable the setting for MODE_14 does not matter if INTERMODEL is set to 2. All atoms separated by exactly three bonds will be considered 1-4. It is important to point out that the setting chosen for INTERMODEL affects the setting for ELECMODEL as well (see ELECMODEL).
3. The GROMOS force field uses a very specific set of non-bonded exclusions which is supported by choosing this option for INTERMODEL. It is essentially a weakened version of the first (sane) option. Note that to reproduce the GROMOS force field exactly, ELECMODEL (which remains an independent setting) has to be set to 2 and INTERMODEL to 3.

LJPATCHFILE

This keyword can be used to provide the location and name of an input file that allows reassigning the size exclusion and dispersion parameters used in describing generic short-range potentials of the Lennard-Jones (see SC_ATTLJ and SC_IPP) or WCA types. The parameter file that CAMPARI parses will contain atom entries that specify general atom types. These types have associated with them entries of the contact and epsilon types specifying the Lennard-Jones σ_ij and ε_ij parameters (see equations provided with scale factor keywords). Within the list of biotypes, each biotype is assigned an atom type, and the patch functionality described here allows the user to change this to a different atom type for a specific instance of a biotype. Note that the reassignment is restricted to the Lennard-Jones parameters, but excludes other atomic parameters specified by atom types such as mass, proton number, description, or valence. Conversely, parameters derived from Lennard-Jones parameters are altered. This is particularly important for the derived atomic radii and volumes used in the continuum solvation model and analysis. If those parameters are meant to be left unchanged or set to yet another set of values, either the radius facility of the parameter file must be employed (if it is not already in use for the original atom type in question), or a patch of atomic radii must be applied in addition. Because size exclusion and dispersion parameters rely on combination rules and/or many overrides for special cases, it can be tedious to patch them. This is because a patch will often require the user to define a new atom type, which, for example, for the GROMOS force fields can be a lot of work. Some more details are given elsewhere.

SYBYLLJMAP

This keyword can be used to provide the location and name of an input file that allows the user to override the automatically determined map of Sybyl (mol2) atom types to the atom type definitions in the chosen parameter file. This is currently relevant only for output files used for validation/debugging (see elsewhere) and in the context of a small molecule screen where a reliance on patch files is not practical. The mol2 input file must contain atom types according to the Sybyl standard for any inference to be working properly. These types contain information about element and hybridization but do not contain Lennard-Jones parameters. This is why a map is needed. Normally, CAMPARI will scan the existing atom types using valence and nucleus number information in particular to find appropriate matches. This may not work well with all parameter files. In particular, the automatic detection uses three hierarchical searches with increasingly relaxed matching criteria. However, the correct nucleus number is always required and element mismatches are thereby impossible. To offer both more control and more flexibility, this keyword exists. The details regarding atom types and the file format are provided elsewhere.

SC_EXTRA

This (largely obsolete) keyword specifies a linear scaling factor for certain structural correction potentials. Assuming the typical set of torsional space constraints (see CARTINT), these are applied to rotatable bonds with electronic effects which cannot be captured by atomic pairwise contributions. In all applications, this keyword should be left at 0.0 and instead SC_BONDED_T should be set to 1.0.
These covered terms consist of:

1. Secondary amides: The rotation around the C-N bond is hindered due to the partial double-bond character present in amides. Corrections are therefore applied to residues which have an ω-angle (all non-N-terminal peptide residues excluding NH2 as well as the secondary amides NMF and NMA → sequence input). These keep the peptide bond roughly planar while allowing for cis/trans-isomerization and increased overall flexibility. The potentials are directly ported from OPLS-AA.
2. Phenolic polar hydrogens: The rotation around the C-O bond in phenols is hindered due to its partial double bond character and in-plane arrangements of the attached hydrogen are favored. Corrections are applied to tyrosine (TYR) and p-cresol (PCR). These keep the polar hydrogen in their favored position. The potential is not overly stiff so that out-of-plane arrangements will be populated as well. The parameters are again ported directly from OPLS-AA.

Note that this list misses many bonded potentials that occur in CAMPARI-supported systems and are relevant in torsional-space sampling (see OTHERFREQ, TMD_UNKMODE, PKRFREQ, etc.). Like all other linear energy scaling factors with the exception of SC_IPP, the parameter controlled by this keyword defaults to zero. Its use should be restricted to runs testing for rigorous backward compatibility. We strongly recommend employing the torsional potentials specified via the parameter file itself (see PARAMETERS) instead. In that case, concurrent use of canonical torsional potentials (SC_BONDED_T) and this term will produce a warning since this is nonsensical. For all cases, the use of the correct OPLS-based hybrid parameter files with (SC_BONDED_T) should provide an exact match to the potentials available by this keyword.

SC_BONDED_B

This keyword gives the linear scaling factor for all bond length potentials. Their usage is permissible in all simulations but not meaningful unless bond lengths are actually allowed to vary, i.e., typically unless sampling happens fully in Cartesian degrees of freedom (see CARTINT). It is important to remember, however, that even in rigid-body / torsional space simulations, specific move types and systems will require setting this to unity (so we recommend it throughout). For bond length potentials, the only such exceptions are crosslinked molecules (see CRLK_MODE). Note that the parameter file has to provide support to be able to use this energy term (see PARAMETERS for details), and that simulations relying on those terms will otherwise fail, crash, or produce nonsensical results. Use GUESS_BONDED to circumvent those issues for incomplete parameter files, for runs with unsupported residues, and for small molecule screens.

SC_BONDED_A

Similar to SC_BONDED_B for all bond angle potentials. Bond angle potentials (see PARAMETERS for details) matter for sampling in Cartesian space (see CARTINT), for crosslinked molecules (see CRLK_MODE), and for the sampling of five-membered, flexible rings (see PKRFREQ and SUGARFREQ). The coordinate derivatives for bond angles diverge at the extreme values of both 0° and 180°. This means that care must be taken in setting up the Z-matrix such that no terms are included, which would explicitly demand these values. In other software, this is sometimes overcome by the use of dummy atoms. In CAMPARI, this is unlikely to be problematic in Monte Carlo simulations. In dynamics, forces are buffered to avoid program crashes due to floating point errors, but the actual values are no longer meaningful. This issue is primarily relevant when modifying the code or when simulating unsupported residues, for which the Z-matrix is inferred from input (see elsewhere for details).

SC_BONDED_I

Similar to SC_BONDED_A for all improper dihedral angle potentials.

SC_BONDED_T

Similar to SC_BONDED_B for all torsional potentials. Note that these do in fact encompass degrees of freedom sampled in all types of simulations supported within CAMPARI and hence are always relevant. As alluded to above, torsional potentials can be easily set up to cover the same correction terms as the ones applied within SC_EXTRA. If that is the case, we therefore recommend not using SC_EXTRA (otherwise energy terms will in fact be applied twice, which is effectively scaling up those torsions; in such a case, CAMPARI produces an appropriate warning as well).

SC_BONDED_M

Similar to SC_BONDED_B for all CMAP potentials. These grid-based correction potentials are part of the CHARMM force field and explained in PARAMETERS. This keyword specifies the "outside" scaling factor. Note that CMAP corrections can theoretically be relevant for all possible simulations of biopolymers within CAMPARI since they act on consecutive dihedral angles. The default CMAP corrections from CHARMM only apply to polypeptides, however, and are only contained within the reference CHARMM parameter file.

IMPROPER_CONV

If improper dihedral potentials are in use (→ SC_BONDED_I), this very specialized keyword can be used to force a reinterpretation of the input sequence for the assignment of improper dihedral angle potentials to bonded types (see elsewhere). When set to 2, this keyword forces CAMPARI to switch the meaning of the first and third specified bonded type when it comes to energy and force evaluations. This allows a more or less exact match to the convention used in the AMBER set of force fields (and by extension: in OPLS-AA). For any other value specified, CAMPARI will use the CAMPARI-native convention (that is the same as in the CHARMM and GROMOS force fields).

CMAPORDER

If CMAP corrections are used (→ SC_BONDED_M), this keyword sets the interpolation order for cardinal splines (assuming those are chosen through parameter input → PARAMETERS). A higher spline order will yield a smoother surface. Since the splines are non-interpolating, however, rapidly varying or coarsely tabulated functions may not be well approximated in such cases. The only interpolating cardinal B spline is the linear one which requires a choice of 2 for this keyword. This keyword is irrelevant should bicubic splines be chosen.

CMAPDIR

If CMAP corrections are used (→ SC_BONDED_M), this keyword lets the user specify the absolute path of the directory in which the CMAP files are to be found (by default they are in the data/-subdirectory of the main distribution tree).

BPATCHFILE

This keyword can be used to provide the location and name of an input file that allows reassigning or adding bonded potential terms (see bond length potentials, bond angle potentials, improper dihedral angle potentials, torsional potentials, and CMAP potentials). At the level of the parameter file that CAMPARI parses to generate default assignments based on biotypes (see elsewhere), there are limitations to how finely the system can be parsed. For instance, it is technically not possible to have different bond length potentials acting on the N→C_α bonds of two non-terminal glycine residues (because biotypes are identical). Of course, even providing bonded parameter assignments exactly at biotype resolution would generally be inordinately complicated, which is the reason for grouping biotypes into so-called bonded types in the parameter file. In cases where specific alterations to a given a system are desired, the patch functionality provided by this input file will generally be the most convenient (and often the only) route to take. For stiff terms, CAMPARI can also guess values based on initial geometries. Applied patches to bonded interactions are always printed to log-output In order to diagnose their correctness more easily, it is recommended to use the report functionality for bonded potential terms. Note that the most critical limitation is that extra or alternative bonded potentials can only be applied to such internal coordinates that are eligible for default assignments themselves, e.g., it is not possible to apply a bond angle potential to atoms a-b-c if a is not covalently bound to b or if b is not covalently bound to c.

GUESS_BONDED

This keyword lets the user CAMPARI instruct to construct a set of bonded parameters from the most basic information available, which are the default molecular geometries ( usually from high-resolution crystal structures) for residues natively supported by CAMPARI or structural input for unsupported residues (see documentation on sequence input for details). Options are as follows:

0. No potentials are guessed. This means that the only bonded potentials available are those defined in the parameter file and mapped by matching the entries on bonded types to the available potentials, e.g. bond length potentials, as well as those potentials defined in a corresponding patch file, which also rely on the parameter file. Missing bonded interactions can make it impossible or meaningless to run simulations in Cartesian space.
1. CAMPARI will guess missing harmonic potentials (type 1) for all bond lengths and angles defined by molecular topology. The equilibrium positions are defined as mentioned above. The force constants are flat, which is obviously a crude approximation, and evaluate to 300kcal·mol^-1Å^-2 for bond lengths and 80kcal·mol^-1rad^-2 for bond angles, respectively. It is not possible to add potentials to doublets or triplets of atoms that are not topologically derived. This is important for unsupported residues where a suboptimal Z matrix may be constructed because of bad atom input order.
2. This option implies the previous option. In addition, eligible improper dihedral angles (see documentation on bonded types) are given a harmonic potential (type 2), and the strength is set to 40kcal·mol^-1rad^-2. Note that the functional form here includes a factor of 1/2 not present for bond angles.
3. In addition to what is done for options 1 and 2, CAMPARI will also guess the chemistry of the underlying systems purely based on atom types, connectivity, and geometry information. This procedure is not aware of the true chemistry of any supported systems being simulated as it is largely meant for dealing with unsupported residues. It will assign harmonic or twofold dihedral angle potentials to nonterminal bonds that are expected to display electronic limitations to rotation around them. This includes aromatic ring bonds, carbon-carbon double bonds, amides, esters, and many other double-bonded or conjugated systems. The planarity of sp²-hybridized atoms participating in such groups is adjudicated by improper dihedral angles and a tolerance setting (see keyword PLANAR_TOLS). The recognition routine provides information about all relevant bonds, which allows an assessment of the quality of the parsing. This assignment of torsional potentials, which does not assign any threefold potentials to bonds with only weak rotational barriers (e.g., carbon-carbon single bonds), is consistent with the ABSINTH force field paradigm, which implies using an internal coordinates space. All potentials assigned in this manner are reported if BONDREPORT is used.

It is important that the information from the parameter file takes precedence over the guessed potentials. This means that the use of this keyword can add potentials to improper dihedral angle terms that were left empty by design in the force field in question, which can be undesirable. An easy solution avoiding this scenario (that is also used in many parameter files) is to define a null potential and map it to the terms in question. Conversely, patches are able to override both.
While these potentials are obviously too crude to study problems requiring very high resolution at the local geometry level, they can be very useful too quickly enable Cartesian space simulations of unsupported systems where often calibration data are missing (or unreliable) to begin with. In addition, option 3 above is helpful when trying to simulate unsupported residues in internal coordinate space. The guessed potentials are written to log output, and parsing this with a script can help in creating templates for exhaustive patch files, which are tedious to create from scratch. Note that the source data do not come from structural input for supported residues, which means that initial structures deviating dramatically from the assumed local geometries can be subject to large forces. Conversely, since the source data for unsupported residues must come from structural input, it is critical that the input conformations allow the parser to make the right inference. There are many ambiguous cases in terms of electronic conjugation (e.g., in substituted biphenyls) or conformational preferences (Z vs. E). In addition, the presence of flexible rings makes it harder for the force field to be accurate because their conformational preferences are notoriously difficult to describe and determine experimentally. If these input structures are present in odd conformers, CAMPARI's inference will likely be odd as well and either try to perserve the status quo or not put any potential. This is because CAMPARI will no longer understand the bond in question and is unwilling to speculate.

PLANAR_TOLS

If the general chemistry parser is used to automatically assign some dihedral angle potentials to a system, this keyword sets two tolerances (in degrees) for impropers measured at sp²-hybridized atoms. The first is for atoms within rings, and the second is for atoms not in rings. If the measured improper exceeds the relevant tolerance, the atom is considered as something other than sp²-hybridized, which usually will lead to a lack of classification.

MOL2BONDMODE

If a small molecule screen is performed and bonded potentials are in use, this keyword functions exactly like keyword GUESS_BONDED in controlling which types of potentials to guess from input and/or considerations of general chemistry. This refers to the bonded terms for the screened molecules alone. Since the source data for the screened molecules must come from the input conformers, it is critical that these conformers allow the parser to make the right inference. For example, a bond between sp²-hybridized atoms is unlikely to receive a bonded potential favoring planarity if the input conformer has an angle between the two planes exceeding the relevant tolerance setting. If this is not appropriate, there is no simple way to fix it at the moment. This is especially tricky if multiple conformers of the same or very similar molecules are present in the input file (inconsistencies here could split what was meant to be the same molecule into two or more different ones). To be able to diagnose errors of this type, the output of the bond parser is very verbose at the moment.

BONDREPORT

This report flag allows the user to request a summary of the bonded potentials found and not found during processing of the parameter file. This is primarily useful as a sanity and debugging tool for creating parameter files. Note that missing but necessary parameters (necessary ones are all bond length and angle potentials if and only if CARTINT is 2) as well as guessed parameters (see GUESS_BONDED) are always reported upon.

SC_WCA

Mutually exclusive to the use of the Lennard-Jones potential, CAMPARI allows using the extended Weeks-Chandler-Andersen (WCA) potential which is defined as :

E_WCA = 4.0·c_WCAΣΣ_i,jε_ijf_1-4,ij·[(σ_ij/r_ij)¹² - (σ_ij/r_ij)⁶ + 0.25·(1.0 - c₂)]    if r_ij < σ_ij·2^1/6
E_WCA = c₂·c_WCAΣΣ_i,jε_ijf_1-4,ij·[0.5·cos(c₃·(r_ij/σ_ij)² + c₄) - 0.5]    if r_ij < σ_ij·c₁
E_WCA = 0.0    else

with:

c₃ = π·(c₁² - 2^1/3)^-1
c₄ = π - c₃·2^1/3

(reference)

Here, the size, interaction, and fudge parameters are used as defined before. c₁ is the interaction cutoff (in units of σ_ij) while c₂ is the depth of the attractive well to be spliced in (in units of ε_ij). c₁ and c₂ can be set by keywords ATT_WCA and CUT_WCA, respectively. The potential provides a continuous function mimicking a LJ potential in which the dispersive term can be spliced in without shifting the position of the minimum. c_WCA denotes the linear scaling factor specified by this keyword.

ATT_WCA

This allows the user to specify the well depth (positive number) for the attractive part of the WCA potential in units of ε_ij (parameter c₂ under SC_WCA).

CUT_WCA

This allows the user to specify the cutoff value for the extended WCA potential in units of σ_ij (parameter c₁ under SC_WCA). Note that the minimum allowed choice here is 1.5.

VDWREPORT

This keyword is a simple logical deciding whether or not to print out a summary of the Lennard-Jones (size exclusion and dispersion) parameters, i.e., to report the base values (σ_ii and ε_ii), the combination rules, and in particular all "special" values which overwrite the default combination rule-derived result.

INTERREPORT

Mostly for debugging purposes, this simple logical allows the user to demand a summary of short-range interactions. Naturally, this output can be very large and the keyword should only be used when absolutely needed, for example to understand the settings for MODE_14 and FUDGE_ST_14.

SC_POLAR

CAMPARI only supports fixed-charge atom-based electrostatic interactions which work by defining partial charges for each atom and then writing the potential as:

E_POLAR = c_POLAR·ΣΣ_i,j [ (f_1-4,C,ij·q_iq_j) / (4.0πε₀·r_ij)]

Here, the q_i are the atomic partial charges, f_1-4,C,ij are potential 1-4 fudge factors (see FUDGE_EL_14) that generally will be unity, ε₀ is the vacuum permittivity, r_ij is the interatomic distance, and the (double) sum runs over all eligible atom pairs (see ELECMODEL). c_POLAR is the linear scaling factor for all polar interactions specified by this keyword. Since electrostatic interactions are characterized by the potential to yield long-range effects (distance scaling ranges from r^-1 for monopole-monopole terms to r^-6 for dipole-dipole terms between molecules tumbling freely), the Coulombic term can employ a different cutoff in MC calculations (see below) than short-range potential. The correct long-range treatment of electrostatic interactions is one of the most investigated areas in molecular simulations and the user is referred to current literature and keywords LREL_MC and LREL_MD for details. All required partial charges are read either through the parameter file or can be set by a dedicated patch.
Note that the functional form given above is only correct if no implicit solvation model is in use. In such a scenario, Coulomb interactions are usually modified by an extra term s_ij which can be complicated function of interatomic distance and/or the positions of all nearby atoms. The reader is referred to Vitalis and Pappu for the exact functional forms used in the ABSINTH implicit solvation model.

ELECMODEL

This important keyword is somewhat analogous to INTERMODEL and allows the user to set the interaction model for electrostatic interactions:

1. Depending on the setting for INTERMODEL, interactions are either screened for connectivity and frozen interactions are excluded (INTERMODEL is 1), or are purely considered based on the number of bonds separating two atoms (INTERMODEL is 2). In any case, partial charges interact without considerations of net neutrality (see below), which is problematic for short-range interactions. Consider for example the ω-bond in polypeptides and assume that CO and NH both form neutral groups supposed to indicate dipole moments. If INTERMODEL is 2 and ELECMODEL is 1, the interaction between O and H is considered (1-4) but none of the others as they are topologically too close. This leads to spurious (and very strong) Coulomb interactions between what essentially are fractional, net charges. This is an inherent weakness of the point charge model which is typically addressed by extensive co-parameterization of bonded parameters, 1-4-fudge factors, etc. (see FUDGE_EL_14).
2. The partial charge set in the parameter file is read and the assigned charges are screened for (generally) net neutral charge groups. These charge groups are determined largely automatically and are currently not patchable per se. The automatic charge group generation operates by trying to group partial charges into groups of minimum size and spanning a minimum number of covalent bonds satisfying a target net charge without isolating atoms that have only one covalently bonded partner. The net charges serving as default targets are derived from knowledge of every CAMPARI-supported residue and assumptions about their titration states (if any). This means, for example, that a nonterminal lysine residue will be processed by looking for a charge group with a net charge of +1 along with as many net neutral groups as possible. While CAMPARI does not allow grouping charges arbitrarily, there is a dedicated patch that allows defining a set of (arbitrary) target values for the net charges of charge groups in a given residue. This is required to deal with charge sets that do not group at all, or to deal with residues that contain multiple ionic moieties. For example, depending on the charge set in use, one may want to partition free, zwitterionic alanine either as multiple groups with +1, -1, and 0 charges, or simply as one or more net neutral groups. The procedure is described in detail in the corresponding section in Parameters and not only controllable by the aforementioned patch but also by keyword POLTOL, which sets a general upper limit for the accuracy with which the targets can be matched. Resultant groups that are not well-defined charge groups according to CAMPARI's standards will be reported in log output.
   With the groups in place, only interactions between those groups, for which all possible atom-atom pairs are separated by at least one significant degree of freedom, are computed. Interactions within a group are always excluded. What constitutes a significant degree of freedom is predetermined by the choice for INTERMODEL, and the reader is encouraged to read up on this if necessary. Essentially, INTERMODEL will define the maximum set of short-range interaction pairs that can also be considered for polar interactions. As an example, for the 6 net neutral CH units in benzene, if INTERMODEL is 1, no intramolecular polar interactions can be considered (the maximum set is empty). Conversely, if INTERMODEL is 2, several group-group interactions are now permissible (C1H-C4H, C2H-C5H, C3H-C6H). The list of retained atom-atom interactions is printed if ELECREPORT is turned on.
   Depending on the charge set and on the choice for INTERMODEL, setting ELECMODEL to 2 can lead to a massive depletion of short-range electrostatics. The problems motivating this paradigm are of course not unknown in traditional force field development as evidenced by fudge factors, force field-specific exclusion rules (see, for example, choice 3 for INTERMODEL), or topology-specifc nonbonded interaction parameters (see Parameters). There are cases where the exclusions incurred by this model are harmful. For example, if charges group poorly, the Coulombic repulsion between neighboring phosphate backbone units might be omitted, and this is what the next option (#3) is provided for.
3. This is the same as the previous model (#2) except that a correction is introduced for the leading term of any omitted short-range electrostatic interactions, viz., monopole-monopole interactions. This correction was introduced formally in the context of the small molecule extension of ABSINTH, see keyword MOL2SCREEN but has since been generalized to become part of the normal force field. It uses the same functional form as the monopole-monopole corrections for choices 3 and 4 for LREL_MC and LREL_MD, respectively. In words, it loops over the unique pairs of charge groups within residues and over the pairs of charge groups in topologically adjacent residues, and finds those who carry a nonzero charge and whose interatomic interactions are excluded. It then adds a single interaction mapping the full charge to the two atoms closest to the respective centers of charge. If the ABSINTH model is in use, all solvation considerations are dealt with at the atom level. In other words, the only group-based consideration is the lumping of the formal net charge of the group onto a single atom.
   The correction is conditional upon having such pairs of charge groups with nonzero charge whose interactions are excluded. With standard polypeptide residues and normal partial charges, the only case where this might become relevant is for terminal amino acids with charged sidechains, especially aspartate, and, most notably for free amino acids. It might be highly relevant along the polynucleotide backbone, as mentioned above, but also in small molecules as explained in the reference publication. In all cases, the relevance hinges on both the partial charges and their processing by the grouping algorithm (see Parameters). For example, for free amino acids, if the ammonium and carboxylate functions are not put into separate groups, the correction does nothing since it "sees" only a single net-neutral group. If a system is simulated where choices 2 and 3 lead to a different model, it is likely that setting ELECMODEL to 2 causes systematic errors that are at least qualitatively corrected/improved by picking model ELECMODEL as 3. Due to the short distances, the energy scales can be quite large, and it should be avoided to have the two atoms serving as centers of the monopole-monopole interaction be topologically very close (usually, they should be at least two bonds apart). This can be checked with the help of output file MONOPOLES.vmd. The added corrections are shown as atom-atom interactions when ELECREPORT is turned on.

The partitioning into charge groups for options 2/3 is currently relevant for two additional areas (independent of the setting for ELECMODEL):

• The charge groups are important for deciding how long-range electrostatic interactions between ionic groups are computed exactly (see options 1, 2, and 3 for LREL_MC and options 4 and 5 for LREL_MD).
• The charge groups are used as the basis for computing group-averaged screening factors for certain screening models in the ABSINTH framework (see options 1, 3, 5, and 7 for SCRMODEL).

It should be noted that the typical combinations here will be setting ELECMODEL to 1 and INTERMODEL to 2(3) (the standard molecular mechanics force field paradigm) versus setting ELECMODEL to 2(3) and INTERMODEL to 1 (the ABSINTH paradigm). In particular, the combination of both being set to 1 will not be particularly meaningful. This is because the interactions isolated via INTERMODEL must always remain a superset of those isolated here.

AMIDEPOL

One "flaw" in the biotype setup in CAMPARI (see PARAMETERS) is the fact that the two polar hydrogens on primary amides are treated as chemically equivalent which - on a typical simulation timescale - they are not. Instead of creating yet more biotypes, this keyword simply allows to add a small polarization term for partial charges on those hydrogens. The value specified will be added to the hydrogen cis to the oxygen (the electronegative atom nearby increase the partial positive charge) and subtracted from the trans-H to keep them both at the same total charge. For example, if both hydrogens have a charge of +0.36, a specification of 0.05 here will yield charges of 0.41 (cis-O) and 0.31 (trans-O). It will be useful to track these changes using ELECREPORT. It is very important to note, however, that fundamentally a sampling algorithm may isomerize the amide bond and hence render the correction incorrect and - moreover - that reading in a structure may flip the two hydrogens to start out with (because of inconsistent numbering between two software packages). Hence, this keyword should be used only when absolutely necessary (and its sign may have to be flipped to achieve the desired effect).
This correction to primary amides is a specific example for the occasional need to overwrite partial charge parameters for atoms due to "biotype splitting". The more general approach provided CAMPARI for this explicit purpose is to "patch" the partial charge set by a dedicated input file.

CPATCHFILE

If the polar potential is in use, this keyword can be used to provide the location and name of an input file that allows overriding some or all of the partial charge parameters CAMPARI obtains from the parameter file (see elsewhere). This can be required to match the exact standard given by a force field with a finer biotype parsing. Note that - by default - such corrections are error-prone and should only be used when absolutely needed. In any case, the user is recommended to use ELECREPORT for a detailed summary of final partial charges in the system.

DIPREPORT

This simple logical will - when turned on by the user - produce two summary files (see DIPOLE_GROUPS.vmd and MONOPOLES.vmd), which allow to graphically assess the automatically determined charge groups. The former will visualize all charge groups in the system (not just the net neutral ones) by highlighting all atoms belonging to each group. The second will visualize the "center" atom of all groups carrying a net charge (the meaning of this is defined by the value for POLTOL). Note that - naturally - this option is not available if SC_POLAR is zero.

NCPATCHFILE

If the polar potential is in use, CAMPARI automatically determines charge groups, i.e., groups of atoms within a residue that are topologically close and whose partial charges sum up to zero or to an integer net charge. If LREL_MD is 4 or 5 and/or LREL_MC is 1, 2, or 3, this information is used to flag residues as carrying ionic groups, which leads to the computation of additional interactions even if residues are not in each others' neighbor lists. A residue is flagged if it contains at least one charge group with a total, absolute charge greater than a tolerance that is zero by default (and increasing this tolerance affects the charge group partitioning in other ways, see also the corresponding section in Parameters).
This keyword allows the user to specify location and name of an optional input file that can perform two important tasks:

• It allows removal of the net charge flag for specific residues, thereby altering the overall interaction model (if the corresponding options for LREL_MD and/or LREL_MC are selected).
• It allows the manual specification of a set of target values for the total charges of charge groups to be identified. This is currently the only way to manually alter the charge group partitioning, and can be crucial when simulating unsupported residues and/or when dealing with charge sets that do not group naturally (such as those for nucleic acids in most common force fields).

The details of the input and an example application are described elsewhere.

CSPATCHFILE

If the polar potential is in use, CAMPARI automatically determines charge groups, i.e., groups of atoms within a residue that are topologically close and whose partial charges sum up to zero or (normally) to an integer net charge. This keyword allows a simple way to rescale charges and associated reference free energy of solvation (if SC_IMPSOLV is positive) for those groups carrying a net charge (not zero). This patch can be also be achieved by a (tedious) combination of a charge patch and a solvation group patch.
This patch is relevant irrespective of the long-range and short-range interaction models. It is applied after possible charge and solvation group patches but before the patch modifying the charge flag status of residues. As such, the value for POLTOL may matter. The scale factors in the corresponding input file are interpreted to scale the net energy accordingly, i.e., they use the square root of the values for partial charges, and the actual value for the reference free energies of solvation. This keyword should be used with utmost caution as the resultant systems effectively contain fractional charges and, often, an overall charge imbalance.

POLTOL

If the polar potential is in use, CAMPARI automatically determines charge groups, i.e., groups of atoms within a residue that are topologically close and whose partial charges sum up to zero or to an integer net charge. In this context, this keyword has two functions.
First, as described above, these net charge values can be patched. This may, for example, be used to obtain a grouping into approximately neutral groups for partial charge sets that include complex polarization patterns. In order to avoid having the resultant groups cause CAMPARI to flag the corresponding residue as carrying a net charge (i.e., they are treated like ions), this keyword allows the user to defined an increased tolerance for what is considered "approximately neutral". This is relevant because treatment of residues as ions can have substantial implications for the interaction model in particular in terms of computational efficiency (see LREL_MC and LREL_MD). Note that this keyword operates at the charge group level, whereas patches via NCPATCHFILE can (also) disable the ionic flag status of residues. Therefore, both offer different levels of control. The numerical value specified here (in units of e) is compared to the total charge of a given charge group.
As an example, consider a terminal nucleotide residue carrying a 5'-phosphate with an integer negative charge. Suppose that the partial charges on the phosphate linker to the next residue are such that - in addition to the terminal phosphate - this leaves a charge group with a small, fractional charge. In this case, the residue-level patch could only remove the net charge flag for the entire residue (probably undesirable), whereas the tolerance setting described here could specifically eliminate the group with the fractional charge from the list of ionic groups. The default tolerance is set to be zero within reasonable numerical precision. This first function is relevant only if LREL_MD is 4 or 5 and/or LREL_MC is 1, 2, or 3.
The second use of this keyword is in the charge group parser, which might be particularly important in a small molecule screen and for natively supported species that have partial charges that group poorly (most notably, nucleic acids in almost all common force fields). The tolerance is applied directly to the charge group identification, which is described in the corresponding section in Parameters and, for the small molecule screen, briefly for keyword MOL2POLMODE. This procedure has changed from V3 to V4, and for some special cases, a prior poor assignment in V3 is now improved, which has the side effect that polar energies are no longer the same at least as long as ELECMODEL is not 1 and/or a group-consistent screening model is in use for ABSINTH.

MOL2POLMODE

If a small molecule screen is performed and the Coulomb potential is in use, this keyword instructs CAMPARI how to deal with input charges in the mol2 input file. Options are as follows:

0. Leave them exactly as is. This implies potentially setting UNSAFE to 1 to override issues with lacking exact integer charges.
1. Correct them at the level of the entire molecule (the deviation from the nearest integer charge divided by the number of atoms with nonzero partial charge is substracted from all atoms with nonzero partial charge).
2. Correct them at the level of charge groups. Charge groups are determined in largely the same way as that described in the corresponding section in Parameters, the most important differences being that no hard-coded charge group targets exist (instead, they are inferred from a rough chemical fingerprint and the total charge), that no fractional charge targets are supported, and that the merging step is currently absent. Bad assignments are of course possible, in particular for delocalized ring systems. Some partial charge sets found in small molecule database have no regularization whatsoever (not even at the level of the entire molecule). Note that charge groups matter if ELECMODEL is 2 and/or if group-consistent screening models are used within the ABSINTH model. In addition monopole group assignments matter if LREL_MD is 4 or 5 and/or LREL_MC is 1, 2, or 3.

Note that options 1/2 alter the input charges. These altered values can be found in the main output file of the screen, which itself is a mol2 file and contains partial charge information.

FUDGE_ST_14

This keyword provides a flat 1-4 scaling factor for interatomic, non-bonded interactions of specific types. 1-4 interactions are defined according to the choice for MODE_14 and depend on the setting for INTERMODEL as well. The value for FUDGE_ST_14 is applied to all steric and dispersion potentials, i.e., the potentials turned on by SC_IPP, SC_ATTLJ, and SC_WCA. The only other 1-4-scaled interaction potential is the electrostatic one for which a separate 1-4-scaling factor is in use (see FUDGE_EL_14). All other pairwise, non-bonded potentials are never subjected to 1-4-corrections (see for example SC_TABUL or SC_DREST). Note that the value for FUDGE_ST_14 is applied in addition to corrections applied at the parameter level by providing 1-4-specific σ- and ε-parameters in the parameter file (see PARAMETERS).

FUDGE_EL_14

Similar to FUDGE_ST_14, this keyword specifies a scale factor for 1-4-interactions. Here, the provided value will be applied specifically to electrostatic interactions (see SC_POLAR) only. If ELECMODEL is set to 2, any charge group interaction will be scaled as a whole by this factor, as soon as any of the possible atom pairs fulfill the 1-4-criterion (see MODE_14).

MODE_14

This keyword's relevance is limited to the case in which INTERMODEL is 1. Then, this essentially defines what a 1-4-interaction is, specifically whether anything separated by exactly three bonds or by exactly one relevant rotatable bond should be considered 1-4:

1. Only two interacting atoms separated by exactly three bonds are treated as 1-4.
2. Two interacting atoms separated by exactly one relevant, freely rotatable bond are always treated as 1-4.

The difference only matters for rigid systems and is best illustrated in an example:
Take a phenylalanine residue and consider the CA-CB-CG-CD1 stretch (from C_α to one of the C_δ). This is exactly three bonds and the bond CB-CG is the only relevant rotatable one (CA-CB is also rotatable but irrelevant, since CA lies on the axis, while CG-CD1 is not rotatable). CA and CD1 are treated as 1-4 in both modes. Now consider the CA-CB-CG-CD1-CE1 stretch. These are four bonds and CA and CE1 are not considered 1-4 in mode 1. However, there is still only one relevant rotatable bond in between (CB-CG, since CG-CD1 is rigid), so CA and CE1 are in fact treated as 1-4 in mode 2.
Note that CAMPARI allows specific modifications of 1-4-interactions, either through the use of fudge factors (see FUDGE_ST_14 and FUDGE_EL_14) or through specific parameters provided in the parameter file. If neither of those indicates a deviation from normal interaction rules, then this keyword becomes irrelevant as well.

ELECREPORT

If the polar potential is in use, this simple logical allows the user to request a summary for the close-range electrostatic interactions in the system. Similarly to INTERREPORT, this keyword mostly serves debugging purposes and should only be needed/required to understand the details of the short-range interaction setup.

SC_IMPSOLV

This keyword serves two functions. First, as a logical it enables the ABSINTH implicit solvent model, i.e., it will compute the direct mean-field interaction (DMFI) of each solute with the continuum and enable screening of polar interactions (if turned on → SC_POLAR). For the former (the DMFI) it simultaneously serves as the linear scaling factor. Note that the amount of screening of polar interactions is not dependent on this keyword and solely determined by other parameters (in particular IMPDIEL). The DMFI is defined as:

E_DMFI = c_DMFI·Σ_k ΔG_FES,k [Σ_i ζ_i^k·υ_i^k]

Here, υ_i^k is the solvation state of the i^th atom in the k^th solvation group and ζ_i^k is its weight factor. The solvation states are computed by CAMPARI and vary throughout the simulation whereas the weight factors are constant. The reference free energies of solvation for each solvation group (ΔG_FES,k) are provided through the parameter file and are constant as well (for the latter see PARAMETERS). Note that the computation of the DMFI given the υ_i^k is a computation of negligible cost and that CAMPARI obtains the υ_i^k while computing short-range non-bonded interactions at a moderate additional cost. This implies that the ABSINTH implicit solvation model is speed-limited almost exclusively by the complications incurred by the screening of polar interactions. The user is referred to Vitalis and Pappu for further details (reference).
To employ the ABSINTH implicit solvent model as published use:

FMCSC_FOSFUNC 1
FMCSC_FOSMID 0.1
FMCSC_FOSTAU 0.25
FMCSC_SCRFUNC 1
FMCSC_SCRMID 0.9
FMCSC_SCRTAU 0.5
FMCSC_SAVMODE 1
FMCSC_SAVPROBE 2.5
FMCSC_IMPDIEL 78.2
FMCSC_SCRMODEL 2 # (or 1)

In simulations relying on gradient-based propagation, it is a disadvantage that the original published creates force discontinuities at 3 levels:

• Cutoffs (these are usually of the least concern, especially given that the effective cutoff distances in CAMPARI are often significantly larger than the chosen value due to the reliance on residue-based lists)
• Linear approximation to the calculation of sphere overlap volumes
• Truncation of mapping function from solvent-accessible volume fractions to solvation states at assumed theoretical limits

To address these issues, we recommend the following deviations from the original model:

FMCSC_FOSFUNC 3 # rather than 1
FMCSC_SCRFUNC 3 # rather than 1
FMCSC_SAVMODE 2 # rather than 1
FMCSC_LREL_MC 3 # rather than 1
FMCSC_LREL_MD 4 # rather than 5

The changes to the cutoff treatments are necessary to keep simulations of large systems computationally feasible since an explicit enumeration of all monopole-dipole interactions at atomic resolution is prohibitively slow for, for example, larger proteins.
Note that the more rigorous screening model (option 1) has not only been used in a highly-cited work on arginine-rich peptides (Mao et al.) but also shown to be quantitatively superior in predicting the binding free energies between small molecules and proteins (see Marchand et al.). In addition, it is known, at least at the community level, that a conjunction of atom-based screening with cutoff treatments that neglect monopole-dipole interactions (see LREL_MC and LREL_MD for details), can lead to artifacts when simulating charged species, especially charged polymers with a blocky charge pattern. These arise because atom-based screening effectively creates tiny effective monopoles from dipole groups because the atoms in a net neutral charge group are not all screened by the same factor. If there are also strong monopoles around, especially distally but on the same polymer, these interactions become numerous enough that they have a measurable influence on the conformational properties of this polymers. Many other screening models are fully implemented but without any published data available (as of 04/2016). Similarly, and as mentioned above, it is possible to switch the functional forms for mapping from solvent-accessible volume fractions to solvation states using keywords FOSFUNC and SCRFUNC and to change the way overlap volumes are computed (→ SAVMODE). In both cases, conservative options are available that simply remove force discontinuities from the model. Finally, note that the DMFI can be made temperature-dependent by additions to the parameter file and use of keyword FOSMODE.

SAVPATCHFILE

This keyword can be used to provide the location and name of an input file that allows overriding the default, topology-derived values for the maximum fractions of the solvent-accessible volume, η_i,max. Because values depend on hard-coded parameters (geometry) and user-level settings (choice of parameters and keyword FMCSC_SAVPROBE), CAMPARI (re)computes these values at the beginning of each run. This utilizes the default local geometries (not input structures) and works by decomposing the molecule into suitably small model compound units. The patch prints a summary of all successful changes, and results can also be assessed via column 4 in output file SAV_BY_ATOM.dat. Note that these values rely on other patchable quantities, most notably atomic radii. Patches follow a hierarchy, and a patched value for the η_i,max overrides values derived from radii that could be patched themselves (here, RPATCHFILE overrides indirect reassignment via LJPATCHFILE) without touching the atomic radii. This means that it possible for the patched values of η_i,max to be grossly inconsistent with the underlying set of radii.

ASRPATCHFILE

This keyword can be used to provide the location and name of an input file that allows overriding the default, topology-derived values for the pairwise reduction factor for atomic volumes used in most computations using the atomic volume, most prominently the ABSINTH implicit solvation model. Reduction factors are needed, because the exclusion volumes of covalently bound atoms overlap. The reduction factors are computed in linear approximation, and - by default - the overlap volume is subtracted evenly from the remaining atomic volume of each partner. These values depend on various parameters (parameters and hard-coded geometry), and CAMPARI (re)computes them at the beginning of each run. The patch prints a summary of all successful changes, and results can also be assessed via column 7 in output file SAV_BY_ATOM.dat. See SAVPATCHFILE for remarks on the hierarchy of patches of atomic parameters.

FOSPATCHFILE

Since there is no external way to control details of the solvation group assignments relevant to the computation of the DMFI (→ SC_IMPSOLV) through the parameter file, CAMPARI offers users to alter the default group partitioning and to control reference free energies of solvation on a per-moiety basis through a dedicated input file. This also supports alterations to transfer enthalpies and heat capacities at the patch level if a temperature-dependent DMFI is in use. This keyword is used to provide the location and name of this input file. There are some underlying restrictions to the freedom of choices, but in principle it is possible to completely redesign the underlying DMFI model using this facility. Restrictions and formatting are explained elsewhere. The applied patch implies that CAMPARI will keep the built-in default partitioning along with the default reference values from the parameter file (see elsewhere) for unpatched residues and molecules. As with other force field patches, these corrections are error-prone and CAMPARI output should always be double-checked against the intended input. For this purpose, keyword FOSREPORT and associated output file FOS_GROUPS.vmd will be of particular use.

FOSMODE

Simulation temperature is used frequently in biomolecular sampling both to explicitly probe temperature-dependent behavior and to enhance sampling. For the former, the correctness of fixed force field parameters becomes questionable. If the DMFI of the ABSINTH implicit solvation model is in use, this keyword allows the user to make some of the parameters of the model temperature-dependent themselves. There are currently two options:

0. All values for ΔG_FES in the equation above are fixed to the reference values specified in the parameter file independent of temperature or any other environmental parameters. This is the default.
1. CAMPARI tries to extract values for temperature-independent enthalpies and heat capacities of the transfer process of a given model compound from a fixed conformation in the gas phase into water from the parameter file. By default, all CAMPARI parameter files do not contain these parameters. The temperature-dependent values are computed as:
   
   ΔG_FES(T) = (ΔG_FES(T₀) - ΔH_FES)T/T₀ + ΔH_FES + ΔC_p,FES[T[1 - ln(T/T₀)] - T₀]
   
   Here, ΔH_FES and ΔC_p,FES are the aforementioned enthalpies and heat capacities of transfer, whereas T denotes the simulation temperature and T₀ denotes the reference temperature for the listed free energy value. T₀ is set by keyword FOSREFT.

Note that this keyword is irrelevant unless the parameter file actually contains entries at least for the solvation enthalpies. If no parameters are present, the values are adjusted such that ΔG_FES(T) equals ΔG_FES(T₀) for all temperatures. Furthermore, it is important to keep in mind that a temperature-dependent model may not be more meaningful if other parameters remain fixed. For the screened ABSINTH part, it is at least possible to adjust the reference dielectric for water in a temperature-dependent manner.

FOSREFT

If the DMFI of the ABSINTH implicit solvation model is in use, and if a temperature-dependent model has been requested, this keyword sets the assumed reference temperature for transfer free energies of solvation listed in the corresponding section of the parameter file. It defaults to 298K.

FOSREPORT

This simple logical allows the user to request CAMPARI to print a summary of the group-based reference free energies, enthalpies, and heat capacities of solvation read from the parameter file. The latter two terms are only relevant if a temperature-dependent model has been selected. In general, the reference free energies will correspond exactly to the terms ΔG_FES,k above. Note, however, that this initial output is not a summary of the system but rather of the parameters, i.e., it is more like VDWREPORT and unlike ELECREPORT or INTERREPORT. If some solvation group assignments and parameters are changed via a corresponding patch file, this keyword will also ensure that the applied patch is documented in detail in CAMPARI's log output. The actual group partitioning for the system at hand (but not the associated numerical parameters) is available from output file FOS_GROUPS.vmd.

SAVPROBE

This keyword is crucial for the ABSINTH implicit solvent model and specifies the size of the solvation shell around individual atoms. The input value is interpreted to be the radius in Å of a solvent sphere rolled around each atom and consequently twice the value of SAVPROBE will yield the thickness of the assumed first solvation layer. The resultant solvation shell volume is the starting point for determining solvent-accessible volume fractions (η_i) which are then mapped to yield atomic solvation states (υ_i) which are relevant for the DMFI and screened electrostatic interactions (→ SCRMODEL). In order to compute solvent-accessible volumes, overlap volumes of spheres need to be calculated or estimated, and how to do that is controlled by keyword SAVMODE. It is important to note that SAVPROBE is the only keyword other than SAVMODE directly controlling the η_i which are otherwise purely functions of atomic parameters (see PARAMETERS). Lastly, note that this keyword is still relevant for SAV analysis even though the implicit solvent model might not be used (→ SAVCALC).

SAVMODE

This keyword controls how CAMPARI calculates solvent-accessible volumes. The size of the solvation shell is defined by atomic radius and the setting for SAVPROBE. There are currently two options:

1. Linear approximations are used to calculate pairwise overlap volumes. Individual atomic volumes are scaled by reduction factors given by molecular topology.
2. Pairwise overlap volumes are calculated exactly (polynomial equation). Individual atomic volumes are scaled by reduction factors given by molecular topology.

Note that none of the supported options account for the fact that more than two spheres can overlap at once or that the use of volume reduction factors can become misleading for cases of fractional overlap. The relevant parameters underlying the calculation can all be patched (see RPATCHFILE, ASRPATCHFILE, and SAVPATCHFILE).

FOSFUNC

If the DMFI of the ABSINTH implicit solvation model is in use, this keyword controls which functional form is used to map the solvent-accessible volume to the DMFI solvation state.

1. The published smoothed and stretched sigmoidal function is used, which relies on 2 parameters, viz., χ_f and τ_f. The functional form is:
   υ_i,f ~ [ 1.0 + exp[ - (η_i-h(χ_f))/τ_f ] ^-1
   
   Here, υ_i,f is the DMFI solvation state for atom i, η_i is the solvent-accessible volume fraction for atom i, and h(...) is a linear function shifting the mid-point parameter χ_f (set by FOSMID) such that symmetry between the two natural limits of η_i is obtained. The normalizer is not shown in the equation. The function is smooth over the interval over which it applies.
2. A stair-stepped, stretched sigmoidal function is used, which relies on 5 parameters, viz., χ_f, τ_f, g_f, ζ_f, and FOSSHIFT. This is a piecewise-defined function. The width in solvent-accessible volume space is set directly by g_f starting from the lower natural limit. Within each piece, the fractional interval g_fζ_f is flat with values set by functional form 1 above (thus relying on χ_f and τ_f). If we term two neighboring plateau values as υ₁ and υ₂, then the functional form for the interval of width g_f(1-ζ_f) is:
   υ_i,f = 0.5(υ₂ - υ₁)·(1 - cos( (η_i - η₁)·π(1-ζ_f)^-1/Δη))
   Here, η₁ corresponds to the left boundary of the interval in question, and Δη is the equivalent of g_f in solvent-accessible volume fraction space. The position of the interpolation interval within the total interval of width Δη is defined by keyword FOSSHIFT. Note that functional form 1 is theoretically recovered if g_f approaches 0.0. Note also that FOSSHIFT becomes irrelevant as ζ_f approaches 0.0 and that the limit of ζ_f reaching 1 (true step function) is numerically forbidden. Note that these additional parameters are not independent and that the coarse shape of the default (smooth) function is preserved, especially if FOSGRANULE is small (left near the default).
3. The published smoothed and stretched sigmoidal function is used, using the same parameters, except for a small interval for solvent-accessible volume fractions close to the maximum defined by the initial or reference bond topology. The width of this interval is set by keyword FOSTAPER. If η_i,max - η_min defines the width between minimally and maximally achievable solvent-accessible volume fractions (the maxima can be patched, see SAVPATCHFILE), then the relevant interval is from η_i,max - FOSTAPER(η_i,max - η_min) to η_i,max. Within this interval, cubic Hermite interpolation is performed using the analytical gradient and value of the standard function at η_i,max - FOSTAPER(η_i,max - η_min) as anchor points to gether with η_i,max and a desired derivative of 0.0 at that point. Thus, the resulting piecewise function has continuous gradients and avoids the force discontinuity at solvent-accessible volume ratios approaching or exceeding the maximum. While this is unlikely to happen in polymers, it can happen in small molecules, especially those corresponding to a single solvation group (model compound) that have intrinsic flexibility. The difference this choice causes relative to option 1 is generally expected to be small, in particular if τ_f is small.

The sister keyword used to define the function mapping solvent-accessible volume fractions to the solvation states employed in the (de-)screening of polar interactions is SCRFUNC.

FOSTAU

The atomic solvent-accessible volumes, η_i, are mapped to solvation states by two different sets of parameters, the first being responsible for obtaining υ_i,f which are the solvation states describing the change in DMFI with changes in conformation (the second set is responsible for obtaining υ_i,s which describe the change in dielectric response with change in conformation). The details of the mapping function are complicated by the requirement to normalize the υ_i,f to the well-defined interval [0:1] but in essence it holds:

υ_i,f ~ [ 1.0 + exp[ - (η_i-h(χ_f))/τ_f ] ^-1

Here, τ_f is the parameter determining the steepness of the sigmoidal interpolation and this is the parameter determined by this keyword. Large values will yield an approximately linear re-mapping between the natural limits of η_i which are derived from closest packing of spheres (lower limit) and model compound topology (upper limit). This case is not obvious from the above equation but is obtained via τ_f-dependent re-scaling to match the target interval. Conversely, very small values yield a step-function like interpolation. h(x) is a linear function shifting the mid-point parameter χ_f (set by FOSMID) such that symmetry between the two natural limits of η_i is obtained.

FOSMID

As explained for FOSTAU, the mapping from solvent-accessible volumes η_i to solvation states υ_i,f relies on a mid-point parameter, χ_f. In the functional form given above, the mid-point of the sigmoidal function (i.e., the point of maximal slope) can be shifted toward either one of the natural limits of η_i by varying this keyword between zero and unity. Since the sigmoidal nature of the interpolation disappears in the limit of large values chosen for FOSTAU, FOSMID is only relevant for sufficiently small values of FOSTAU and its impact deteriorates progressively with growing FOSTAU. Note that the default is 0.5 but that it is easily possible to generate fairly asymmetric interpolation functions in the process (i.e., at values close to zero atoms are considered solvated at almost all times while at values close to unity the opposite is true). There is a Matlab script in the tools-directory (sigmainterpol.m) that helps assess the effect FOSTAU and FOSMID have given values for the natural limits of η_i.

FOSGRANULE

As explained above, this keyword applies only to the case of a stair-stepped interpolation function from solvent-accessible volume fraction to DMFI solvation state. It sets the volume increment to assume for each step (in ų). The solvation shell volume of each atom is then discretized by this increment and a step-like function is applied to each resulting interval in η-space. The default is set to the volume available to a single water molecule when assuming liquid water with a density of 1g/cm³.

FOSTIGHT

As explained above, this keyword applies only to the case of a stair-stepped interpolation function from solvent-accessible volume fraction to DMFI solvation state. It sets the narrowness of the cosine-based step interpolation within each interval defined by FOSGRANULE and FOSTIGHT. A value of 0.0 gives a smooth piecewise function without any plateau regions whereas smaller values intersperse plateau regions by making the transition narrower (function remains smooth, however). The theoretical limit of 1.0 gives a true step function, but this is numerically forbidden.

FOSSHIFT

As explained above, this keyword applies only to the case of a stair-stepped interpolation function from solvent-accessible volume fraction to DMFI solvation state. It sets the position of the step interpolation within an interval defined by FOSGRANULE and FOSTIGHT, and values from 0.0 (left) to 1.0 (right) are possible. The keyword is irrelevant if FOSTIGHT (ζ_f above) is zero.

FOSTAPER

As explained above, this keyword applies only to the case of a tapered interpolation function meant to remove the force discontinuity at large solvent-accessible volume fractions. If η_i,max is the maximum solvent-accessible volume fraction for atom i and η_min is the minimal value defined by spherical close-packing, then the taper interval is from η_i,max - FOSTAPER(η_i,max - η_min) to η_i,max. The allowed values are positive values up to a limit of 0.5. Values close to 0.0 should be avoided since this would introduce strong gradient curvature over a very small range of solvent-accessible volume fractions. The default is 0.05.

MOL2FOSLIBFILE

This file provides a library of abstract solvation groups indexed by integers. It is, at the moment, only relevant in the context of a small molecule screen where it provides the database of solvation groups available to parameterize the ABSINTH DMFI for the small molecules.
The groups are simply specified line-by-line with no names or chemical information beyond two specifications of numbers of atoms. No file of this type is provided with CAMPARI, and the process of preparing a mol2 input file so that it utilizes the information in the solvation group library has to be performed independently of CAMPARI. Formatting details are given elsewhere.

IMPDIEL

This keyword lets the user set the assumed continuum dielectric. Primarily, this is used in the ABSINTH solvation model to treat the screening of electrostatic interactions. The dielectric constant enters the equation for the modified Coulomb sum in different ways depending on the choice for SCRMODEL. In general, the solvent-accessible volumes, η_i will be mapped to yield solvation states υ_i,s for dielectric screening. The mapping process is equivalent to the one described for the DMFI but relies on a separate set of parameters (see SCRFUNC). In the published ABSINTH model, the screening factor for the polar interaction is given as:

s_ij = [ 1 - aυ_i,s ]·[ 1 - aυ_j,s ]
a = (1 - ε_r^-1/2)

Here, ε_r is the relative dielectric constant set by this keyword. The above equation corresponds rigorously only to using screening model 2. Note how the functional form ensures an interpolation between the vacuum (υ_i,j = 0.0 → ε_eff = 1.0) and the fully screened cases (υ_i,j = 1.0 → ε_eff = ε_r).
In a completely different context, this keyword also sets the assumed continuum dielectric outside the cutoff sphere when treating electrostatics interactions with reaction-field methods (→ LREL_MD). For this latter purpose, it may be advantageous to set a very large value.

SCRMODEL

This keyword has several options which allow the user to control how dielectric screening of charges is done, specifically what functional form is used for the pairwise screening factor s_ij for a pair of interacting atoms i and j. The electrostatic framework within ABSINTH aims specifically at ensuring that only moieties with well-defined net charges interact (this is discussed in a different context for ELECMODEL). This means that for every base functional form of s_ij there will be two variants, one in which the υ_i,s are used directly (atom-based) and one in which a charge group-based υ_k,s is pre-computed for each group k out of its constituent atoms' solvation states υ_i,s^k. Only the latter ensures rigorously that two formally neutral charge groups interacting will not create effective charge imbalances by atom-specific screening. The downside of those models (and the reason we generally do not recommend using them) is the higher computational cost associated and the dependence on the local neutrality in the partial charge set (i.e., should the base parameters not yield any locally neutral subgroups within a residue, the relevant charge group may be as large as an entire polynucleotide residue and dielectric responses of fairly distant moieties may become coupled which suggests a length scale to the solvent response vastly inconsistent with the setting for SAVPROBE). In the latter case, it may be necessary to attempt to patch the charge groups so that an approximate grouping is obtained (for details on the charge group identification, please refer to the corresponding section in Parameters).

1. For every charge group, the solvation states for the individual sites are averaged in charge-weighted fashion (group-based → see above). The resultant group solvation state υ_k,s is used to screen all the charges belonging to this group:
   s_ij = [ 1 - aυ_k,s ]·[ 1 - aυ_l,s ]
   a = (1 - ε_r^-1/2)
   Here, we assume atom i is part of the k^th charge group and atom j is part of the l^th charge group. ε_r is provided by IMPDIEL.
2. This is the published atom-based model and explained above (→ IMPDIEL). The atom-specific screening via atomic solvation states υ_i,s will break the neutral paradigm somewhat but localizes and strengthens specific interactions.
3. Since electrostatic interactions tend to be somewhat weak with the aforementioned options, this model extends the default model (1) by an important change. If the distance of atoms i and j, r_ij approaches the length-scale of the first solvation shell, the dielectric is augmented by a distance-dependent contribution intended to strengthen specific interactions. This yields a very complicated (although computationally not much more expensive) model:
   s_ij = s_env,ij if r_ij ≥ (r_0,ij+d_W) or s_env,ij > [ ε_c·r_0,ij ]^-1
   s_ij = [ 1 - f_MIX·[1 - d_w^-1(r_ij-r_0,ij)] ]·s_env,ij + f_MIX·[1 - d_w^-1(r_ij-r_0,ij)]·[ ε_c·r_0,ij ]^-1 if r_ij < (r_0,ij+d_W) and r_ij > r_0,ij
   s_ij = (1 - f_MIX)·s_env,ij + f_MIX·[ ε_c·r_0,ij ]^-1 if r_ij < r_0,ij
   s_env,ij = [ 1 - aυ_k,s ]·[ 1 - aυ_l,s ]
   a = (1 - ε_r^-1/2)
   Here, d_W is the thickness of the solvation shell (2·SAVPROBE) and r_0,ij is given by the sum of the atomic radii of atoms i and j. f_MIX is the impact of the distance-dependent contribution and set by keyword SCRMIX. ε_c is set by CONTACTDIEL (compare model 4). Note that the distance-dependence is achieved by the interpolation performed in the distance regime r_0,ij < r_ij < (r_0,ij+d_W) but that no explicit distance-dependence is introduced otherwise. Furthermore, the contact dielectric ε_c·r_0,ij is generally overridden if the environmental dielectric s_env,ij would lead to a stronger interaction (less screening). Importantly, model 3 operates on the group-consistent solvation states (as model 1 does). The atom-specific modification corresponds to model 9. It should be noted that these models are largely untested and were part of initial calibration studies with the ABSINTH implicit solvent model. They are fully supported by CAMPARI, however.
4. This model implements a (more or less) pure distance-dependent dielectric:
   s_ij = [ ε_c·r_ij ]^-1 if r_ij > r_0,ij
   s_ij = [ ε_c·r_0,ij ]^-1 else
   Here, ε_c is the strength of the distance increase of the dielectric constant and r_0,ij is the contact distance below which no further distance dependence to s_ij is applied. The resultant effective dielectric constant is ε_c·r_0,ij which should never be less than unity. ε_c is set by CONTACTDIEL and r_0,ij is defined by the sum of the atomic radii of atoms i and j. This means that the derivative of the potential is discontinuous at the contact point. Note that distance-dependent dielectric models break for a variety of limiting cases, in particular for anything involving net charged species. They also rely on a cutoff criterion since they otherwise do not converge upon a meaningful limiting dielectric. In this way, distance-dependent dielectrics may be seen as somewhat analogous to reaction-field treatments (see LREL_MD).
5. This model is a group-based variant and therefore similar to option 1). It attempts to take a different route toward computing an effective dielectric. Whereas models 1, 2, 3, and 9 use an effective charge approach, this model (just like models 6, 7, and 8) employs an effective dielectric approach. The former implies that the solvation state enters the potential energy for Coulombic interactions as υ_i,s·υ_j,s, i.e., E_POLAR will scale with changes in the υ_i,s differently than the DMFI. Consequently, screening model 5 implies:
   s_ij = M( [1 - a·υ_k,s], [1 - a·υ_l,s] )
   a = (1 - ε_r^-1)
   Here, we assume atom i is part of the k^th charge group and atom j is part of the l^th charge group and M is a function corresponding to a generalized mean whose exact form is determined by the choice for ISQM. The latter will be able to give rise to fundamentally different scaling behavior of E_POLAR with the υ_i,s illustrated for example by taking the arithmetic mean. This can more closely approximate the behavior seen for the DMFI and may allow using much more similar parameter sets τ_s and χ_s compared to τ_f and χ_f than is the case with models 1 or 2.
6. This model is the atom-based variant of model 5:
   s_ij = M( [ 1 - a·υ_i,s], [ 1 - a·υ_j,s] )
   a = (1 - ε_r^-1)
   
7. This model is an equivalent modification to model 5 as model 3 is to model 1.
8. This model is an equivalent modification to model 6 as model 3 is to model 1.
9. This model is an equivalent modification to model 2 as model 3 is to model 1.

CONTACTDIEL

For certain screening models, (SCRMODEL = 3, 4, 7, 8, or 9) a value for the effective dielectric at an interatomic distance matching the sum of the two atomic radii exactly is postulated to have the limiting value of ε_c·r_0,ij (see equations above). This keyword provides the value for the parameter ε_c.

SCRFUNC

If the ABSINTH implicit solvation model is in use and Coulombic interactions are enabled, this keyword controls which functional form is used to map the solvent-accessible volume to the solvation state for charge screening (υ_i,s for atom i above). As explained before (see IMPDIEL), the ABSINTH implicit solvent model employs two sets of solvation states, υ_i,f and υ_i,s. The υ_i,s determine the effective dielectric acting between polar atoms (see equations above).
The text below is basically the same as that for keyword FOSFUNC.

1. The published smoothed and stretched sigmoidal function is used, which relies on 2 parameters, viz., χ_s and τ_s. The functional form is:
   υ_i,s ~ [ 1.0 + exp[ - (η_i-h(χ_s))/τ_s ] ^-1
   
   Here, υ_i,s is the charge screening solvation state for atom i, η_i is the solvent-accessible volume fraction for atom i, and h(...) is a linear function shifting the mid-point parameter χ_s (set by SCRMID) such that symmetry between the two natural limits of η_i is obtained. The normalizer is not shown in the equation. The function is smooth over the interval over which it applies.
2. A stair-stepped, stretched sigmoidal function is used, which relies on 5 parameters, viz., χ_s, τ_s, g_s, ζ_s, and SCRSHIFT. This is a piecewise-defined function. The width in solvent-accessible volume space is set directly by g_s starting from the lower natural limit. Within each piece, the fractional interval g_sζ_s is flat with values set by functional form 1 above (thus relying on χ_s and τ_s). If we term two neighboring plateau values as υ₁ and υ₂, then the functional form for the interval of width g_s(1-ζ_s) is:
   υ_i,s = 0.5(υ₂ - υ₁)·(1 - cos( (η_i - η₁)·π(1-ζ_s)^-1/Δη))
   Here, η₁ corresponds to the left boundary of the interval in question, and Δη is the equivalent of g_s in solvent-accessible volume fraction space. The position of the interpolation interval within the total interval of width Δη is defined by keyword SCRSHIFT. Note that functional form 1 is theoretically recovered if g_s approaches 0.0. Note also that SCRSHIFT becomes irrelevant as ζ_s approaches 0.0 and that the limit of ζ_s reaching 1 (true step function) is numerically forbidden. Note that these additional parameters for the second functional form are not independent and that the coarse shape of the default function is preserved, especially if SCRGRANULE is small (left near the default).
3. The published smoothed and stretched sigmoidal function is used, using the same parameters, except for a small interval for solvent-accessible volume fractions close to the maximum defined by the initial or reference bond topology. The width of this interval is set by keyword SCRTAPER. If η_i,max - η_min defines the width between minimally and maximally achievable solvent-accessible volume fractions (the maxima can be patched, see SAVPATCHFILE), then the relevant interval is from η_i,max - SCRTAPER(η_i,max - η_min) to η_i,max. Within this interval, cubic Hermite interpolation is performed using the analytical gradient and value of the standard function at η_i,max - SCRTAPER(η_i,max - η_min) as anchor points to gether with η_i,max and a desired derivative of 0.0 at that point. Thus, the resulting piecewise function has continuous gradients and avoids the force discontinuity at solvent-accessible volume ratios approaching or exceeding the maximum. While this is unlikely to happen in polymers, it can happen in small molecules, especially those corresponding to a single solvation group (model compound) that have intrinsic flexibility. The difference this choice causes relative to option 1 is generally expected to be small, in particular if τ_s is small.

The sister keyword used to define the function mapping solvent-accessible volume fractions to the solvation states employed in the ABSINTH direct mean-field interaction is FOSFUNC.

SCRTAU

This is the specification analogous to FOSTAU for the charge screening solvation state and provides τ_s rather than τ_f.

SCRMID

This is the specification analogous to FOSMID for the charge screening solvation state and provides χ_s rather than χ_f.

SCRGRANULE

This is the specification analogous to FOSGRANULE for the charge screening solvation state and provides g_s rather than g_f.

SCRTIGHT

This is the specification analogous to FOSTIGHT for the charge screening solvation state and provides ζ_s rather than ζ_f.

SCRSHIFT

This is the specification analogous to FOSSHIFT.

SCRTAPER

This is the specification analogous to FOSTAPER.

SCRMIX

Several of the screening models (choice of 3, 7, 8, or 9 for SCRMODEL) splice a distance-dependent term into the environmental charge-screening over a well-defined length scale. The impact of this contribution is set by this keyword which corresponds to the parameter f_MIX in the equations above. If set to values close to zero, the model approaches its unmodified base model, e.g. model 3 essentially converges to model 1. Conversely, a value close to 1.0 would yield maximum impact and let - for example - model 3 approximate model 4 for distances close to the contact distance r_0,ij. The choice here is naturally tightly coupled to that for CONTACTDIEL.

ISQM

In those screening models postulating an effective dielectric rather than effective charges, the generalized mean function M(x,y) was introduced (see equations above). This can be an integer from -10 to 10, but large absolute values slow down the computation drastically and are not recommended. The specification here defines the order m for the generalized mean:

M(x,y) = [0.5·( x^m + y^m ) ]^1/m if m ≠ 0

With the limiting case of:

M(x,y) = (x·y)^1/2 if m = 0

Common cases aside from the geometric (m=0) are the arithmetic (m=1) or the harmonic (m=-1) mean. Any m>1 will favor large values in an asymmetric pair, i.e., let both participating atoms appear desolvated leading to stronger interactions, while any m<1 will favor small values in an asymmetric pair, i.e., let both participating atoms appear solvated and weaken such interactions (it is the derived screening factors and not the solvation states that enter the mean). The former scenario (m>1) would rarely seem desirable as it means that - for instance in solutions of small, polar molecules - the cooperativity for converting between fully dissociated and fully associated states becomes overly pronounced on account of the positive coupling between adding more and more species to a growing cluster and the enthalpic benefit offered by that process.

SC_TOR

This keyword specifies the linear scaling factor controlling the "outside" scaling of torsional bias terms, V_TOR. Such a potential allows to either harmonically restrain virtually all freely rotatable dihedral angles to specific target values or to softly bias them toward such target values. The setup for these is handled through an input file (details of the format are described elsewhere). Note that a particularly useful application of E_TOR is to apply torsional restraints according to structural input which is useful for equilibrating molecules meant to remain in a specific, internal arrangement. Notably, torsional bias terms are respected during almost all stages of any possible structural randomization happening during the setup stage of a simulation task. This means that they can be used to generate starting configurations of polymers that are in compliance with a particular secondary structure pattern.

TORFILE

This keyword specifies the location and name (absolute paths preferable) of the input file for individual backbone torsional bias potentials, V_TOR (see elsewhere for description).

TORREPORT

This is a simple logical allowing the user to instruct CAMPARI to write out a complete summary of the torsional bias terms contributing to V_TOR (naturally parsed by residue) in the system. In addition to the annotated log-output, this will also create the output file SAMPLE_TORFILE.dat, which is a rewriting of the current input specifications to a fully explicit and residue-based version. This is useful primarily in preserving input to the definition of torsional bias potentials that comes from structural input. It is recommended to utilize this option.

SC_ZSEC

This keyword gives the linear scaling factor for a global secondary structure bias term. For values larger than zero, a harmonic bias is applied on two order parameters, f_α and f_β which measure the secondary structure content of the chain. f_α and f_β are calculated as the sequence-averaged (excluded termini) values of a mapping function defined for each residue:
z_α = e^{-τ_α·(d_α-r_α)2} if d_α < r_α
z_α = 1.0 else
The radius of the (spherical) α-region, r_α, is provided by ZS_RAD_A and its center φ/ψ-position by keyword ZS_POS_A. The distance d_α is taken from the center of the circle and corrected for periodic wraparounds in φ/ψ-space. z_β is defined analogously. This function represents a smooth "top hat" function which is continuous and differentiable. By tuning the parameter τ_α through keywords ZS_STP_A and ZS_STP_B, the Gaussian decay beyond the limits of the spherical plateau region can be turned from very shallow to step function-like. The default definitions (all of which can be overridden) are:
α
Center: φ/ψ=(-60.0,-50.0)°; r_α = 35.0°; 1.0/τ_α^1/2 ≅22.36°
β
Center: φ/ψ=(-155.0,160.0)°; r_β = 35.0°; 1.0/τ_β^1/2 ≅ 22.36°

The global values (if there are multiple polypeptide chains in the system, the average is over all of them) are then restrained:

V_ZSEC = c_ZSEC·(k_α·(f_α - f_α⁰)² + k_β·(f_β - f_β⁰)²)

Here, c_ZSEC is the linear scaling factor specified by this keyword. The other parameters are explained below. Note that it may not be a good idea to use such a residue-based restraint potential for very short sequences. Here, the net content idea breaks down and (for typical choices of τ_α/β) the chain will have access only to values in the vicinity of those given by a discrete residue content. This may lead to a specific sampling of the ring regions around the plateaus to satisfy intermediate target values which runs counterintuitive to the intent of the potential.
When CAMPARI's shared memory (OpenMP) parallelization is in use, the calculation of V_ZSEC is currently executed by a single thread, possibly in concurrence with another thread addressing the complementary DSSP term but not with anything else. This is a scaling limitation, and a corresponding warning is produced.

ZS_FR_A

This keyword specifies the target α-content for the global secondary structure bias (f_α⁰) potential (values [0.0:1.0]).

ZS_FR_B

This keyword specifies the target β-content for the global secondary structure bias (f_β⁰) potential (values [0.0:1.0]). Note that the sum of f_β⁰ and f_α⁰ (see ZS_FR_B) should usually not exceed unity, especially in conjunction with stiff spring constants. Doing so would generate a frustrated system for which results will often be irrelevant.

ZS_FR_KA

Through this keyword, (twice) the spring constant (in kcal/mol) operating on f_α is provided (k_α) if the global secondary structure bias potential is in use.

ZS_FR_KB

Analogous to ZS_FR_KA, this keyword lets the user specify the spring constant (in kcal/mol) operating on f_β (k_β) if the global secondary structure bias potential is in use. If both parameters are meant to be restrained, it usually would not seem meaningful to choose very different values for the two spring constants. In doing so, one would essentially create a primary bias (stiffer term) and a secondary bias (softer term) operating "within" the primary restraint.

ZS_POS_A

This is one of the few keywords that requires two floating point numbers as input. It allows the user to override the default location of the α-basin (see SC_ZSEC). The two numbers are interpreted to be the φ- and ψ-values (in degrees) for the center of the (spherical) basin. The setting is relevant for the corresponding restraint potential and the output in ZSEC_HIST.dat, ZAB_2DHIST.dat, and ZBETA_RG.dat.

ZS_POS_B

See ZS_POS_A, only for the β-basin.

ZS_RAD_A

This keyword requires one floating point number to be specified. It allows overriding the default radius of the α-basin (see SC_ZSEC) and is assumed to be given in degrees. The setting is relevant for the corresponding restraint potential and the output in ZSEC_HIST.dat, ZAB_2DHIST.dat, and ZBETA_RG.dat.

ZS_RAD_B

See ZS_RAD_A, only for the β-basin.

ZS_STP_A

This keyword requires one floating point number. It allows overriding the default steepness of the decay (τ_α) of the order parameter value beyond the spherical plateau region defining the α-basin (see SC_ZSEC). It is assumed to be provided in inverse degrees squared. The setting is relevant for the corresponding restraint potential and the output in ZSEC_HIST.dat, ZAB_2DHIST.dat, and ZBETA_RG.dat.

ZS_STP_B

See ZS_STP_A, only for the β-basin.

SC_DSSP

This keyword provides the outside scaling factor, c_DSSP, on biasing potential acting on order parameters derived from the secondary structure annotation of polypeptides in the simulation system using the DSSP alogrithm. In essence, this allows to bias the system to populate more and stronger hydrogen bonds characteristic for either α-helices (H) or β-sheets - whether parallel, antiparallel, multi-pleated or hairpins (E). Since secondary structure annotation is essentially a discretized and on/off variable, it may seem surprising that a restraint potential can be applied in meaningful fashion.

V_DSSP = c_DSSP·(k_H·(f_H - f_H⁰)² + k_E·(f_E - f_E⁰)²)

Here, the k_H and k_E are (twice) the spring constants for the harmonic restraints applied to the secondary structure scores, f_H and f_E. The spring constants are set by keywords DSSP_HSC_K and DSSP_ESC_K for H-score and E-score, respectively. f_H and f_E are exactly identical to the H-score and E-score defined below and rely on the same base parameters (→ DSSP_MODE). Essentially, they correspond to a multiplicative function of the assignment and the quality of the hydrogen bonds giving rise to the assignment. They can - depending on system and DSSP settings - be continuous and approximately smooth order parameters over a large part of the accessible regime. The target values f_H⁰ and f_E⁰ are set via keywords DSSP_HSC and DSSP_ESC. There are a few noteworthy peculiarities which the user should keep in mind:

1. DSSP E-assignments can rely both on intra- and intermolecular hydrogen bonds rendering the DSSP term a true system-wide potential. Currently, CAMPARI only allows restraining global E- and H-scores which may make calculations with multiple polypeptides more difficult to interpret.
2. In the limit of no hydrogen bonds, the order parameters will always be discontinuous since the discrete assignment score has to be non-zero for the quality score to matter.
3. Due to the potential discontinuities, dynamics calculations utilizing the DSSP biasing potential may suffer from substantial noise, in particular for stiff restraints and small systems.
4. Again, due to the functional form, there is no direct driving force to form new hydrogen bonds of the right type. The potential relies on random encounters and the cooperativity of secondary structure elements.
5. Lastly, in case some proper hydrogen bonds are formed, the resultant energy landscape is often very rugged and sampling may be severely hampered by the presence of the restraints. It is therefore advisable - at the very least - to perform multiple independent simulations when using DSSP restraints.

As mentioned above, the parameters determining criteria for hydrogen bonds are explained further below (see DSSP_MODE). It is easy to see that these types of restraints complement the ones introduced above (→ SC_ZSEC).
When CAMPARI's shared memory (OpenMP) parallelization is in use, the DSSP restraint potential is currently calculated by a single thread, possibly in concurrence with another thread addressing the complementary ZSEC term but not with anything else. This is a scaling limitation, and a corresponding warning is produced.

DSSP_HSC

In case DSSP restraints are used (→ SC_DSSP), this keyword allows the user to set the target H-score (α-content, f_H⁰ above). Its value is limited to the interval from zero to unity. A large value will steer the system toward forming many i→i+4 hydrogen bonds.

DSSP_ESC

In case DSSP restraints are used (→ SC_DSSP), this keyword lets the user set the target E-score (β-content, f_E⁰ above). Just like for DSSP_HSC, values are restricted to the interval [0.0:1.0]. A large value will bias the system toward forming characteristic β-hydrogen bonds but does not distinguish between parallel or anti-parallel arrangements. Note that the sum of DSSP_HSC and DSSP_ESC should probably never approach unity. Also note that the E-score can never be exactly unity for a monomeric, finite length polypeptide even when discarding termini (turn requirement).

DSSP_HSC_K

If DSSP restraints are in use (→ SC_DSSP), this keyword sets (twice) the spring constant (in kcal/mol) operating on the DSSP H-score, i.e., it sets the value of k_H above.

DSSP_ESC_K

If DSSP restraints are in use (→ SC_DSSP), this keyword sets (twice) the spring constant (in kcal/mol) operating on the DSSP E-score, i.e., it sets the value of k_E above.

SC_POLY

In studies of generic polymers coarse descriptors like size and shape of the macromolecule may be more relevant than structural characteristics tailored specifically to polypeptides. CAMPARI supports restraint potentials on such coarse descriptors, specifically the parameters t and δ (see description of output file POLYAVG.dat) which measure size and shape asymmetry, respectively. Two-dimensional histograms of these quantities can be computed and written by CAMPARI (see output file RDHIST.dat). These molecule-based restraint potentials yield a bias term to the total potential energy, V_POLY, and this keyword provides its "outside" scaling factor c_POLY. Note that with the exception of the scaling factor, requests are generally handled through a dedicated input file (see elsewhere for details). As mentioned above, when CAMPARI's shared memory (OpenMP) parallelization is in use, all threads contribute to calculating V_POLY synchronously.

POLYFILE

This keyword should point to the location of the input file for individual molecular polymeric biasing potentials (→ elsewhere for description).

POLYREPORT

Like other report flags, this keyword is a simple logical which allows the user to obtain a complete summary of the polymeric bias terms (by molecule) in the system. It is only meaningful if polymeric biasing terms are in use (→ SC_POLY).

SC_TABUL

CAMPARI has an extensive facility to supply tabulated non-bonded potentials which are then applied to the system. This keyword specifies the "outside" linear scaling factor c_TABUL according to:

E_TABUL = c_TABUL ·ΣΣ_i,j I(V_ij^k,V_ij^k+1,m_ij^k,m_ij^k+1,d_ij)

Here, the sum runs over all atom pairs i,j which have a tabulated potential specified for them, V_ij^k is the k^th tabulated value of the acting potential and d_ij is the interatomic distance. d_ij is located uniquely within the interval given by the k^th and k+1^th tabulated value. I(...) is the interpolation function, and CAMPARI currently performs only cubic interpolation with cubic Hermite splines:

I(V_ij^k,V_ij^k+1,m_ij^k,m_ij^k+1,d_ij) = (2t³ - 3t² + 1)·V_ij^k + (3t² - 2t³)·V_ij^k+1 + (d_k+1-d_k)·[(t³ - 2t² + t)·m_ij^k + (t³ - t²)·m_ij^k+1]
t = (d_ij - d_k)/(d_k+1-d_k)

Here, t is the relative position in the interval from k to k+1 normalized to unit length. The m_ij^k are the tangents to (slopes at) the control points (tabulated values) of the potentials. The spline is set up to recover both values and tangents at the control points. This means that the resultant function is continuously differentiable regardless of the values used for the tangents. Tangents are either read from file (without error checks → description of dedicated input file) or estimated numerically via finite differences from the potential input (see description of dedicated input file). In the latter case, some options are available to tune the spline (see TABIBIAS and TABITIGHT).
There are a few additional characteristics of the implementation of tabulated potentials in CAMPARI:

1. Aside from Coulombic terms, these potentials are the only ones captured by the longer of the non-bonded cutoffs in MC runs (→ ELCUTOFF).
2. When used concurrently with other non-bonded potentials, a lot of wasteful distance calculation may be performed. This is since tabulated potentials have to use their own data structure to be able to function efficiently both for cases with universal use and for very sparse use.
3. Atom pairs that are in close proximity and are excluded from all other non-bonded potentials are not excluded from tabulated potentials.

All further implementation details are provided in the description of the corresponding input files (index input, potential input, and optional tangent input). As an example for the utility of this facility, consider knowledge-based (effective) potentials acting on solutes in an implicit solvent. The potentials themselves may have been derived from binned distance distributions and are practically defined in the form of tabulated potentials. The possibilities are such that - in theory - each individual atom pair could interact via its own unique potential.

TABCODEFILE

This keyword provides the index input file which determines which tabulated potential to use for which atom pair (see elsewhere for format description). Naturally, this is only relevant if the tabulated potential is in use.

TABPOTFILE

This keyword should give the name and location of the actual input file for the tabulated potentials (see elsewhere for format description). Naturally, this is only relevant if the tabulated potential is in use.

TABTANGFILE

This keyword should give the name and location of the optional input file for providing derivatives of the tabulated potentials specified via another keyword. If this file is not provided, the derivatives are estimated numerically to generate the necessary tangents for the cubic interpolation scheme. If the file is provided, however, no checks are performed on the supplied values (see elsewhere for format description). Naturally, this is only relevant if the tabulated potential is in use.

TABITIGHT

If tabulated potentials are in use, and if the input file providing derivatives of the potentials is either missing or incomplete, the cubic interpolation scheme applied to the discrete input data (using cubic Hermite splines) utilizes numerical estimates of the tangents (slopes) at the nodes (control points). The shape and nature of the resulting spline can be varied somewhat with two control parameters, the first controlling the "tightness", and the second (see below) controlling a left/right-sided bias with respect to the control points. The control parameters are used in the construction of the tangents as follows:

m_ij^k = [ (1-t_t)·(1+t_b)·(V_ij^k - V_ij^k-1) + (1-t_t)·(1-t_b)·(V_ij^k+1 - V_ij^k) ] / (d_k+1 - d_k-1)

This is essentially a simplified Kochanek-Bartels spline scheme skipping the discontinuity parameter and assuming identical distance spacings. The V_j are the potential values at the specified distances, d_k, supplied via the required input file. t_t is the tightness parameter controlled by this keyword, and t_b is the bias parameter controlled by TABIBIAS. For both parameters being zero, the well-known Catmull-Rom spline is obtained. Regardless of the choices for t_t and t_b (allowed values span the interval from -1 to 1), the resultant interpolation scheme will yield a function that is continuous and smooth (i.e., continuously differentiable). However, unless the control points are very sparse with respect to the features of the potentials, any non-zero settings for t_t and/or t_b will most likely lead to undesirable effects, in particular at the level of derivatives.

TABIBIAS

If tabulated potentials are in use, and if the input file providing derivatives of the potentials is either missing or incomplete, the cubic interpolation scheme applied to the discrete input data (using cubic Hermite splines) utilizes numerical estimates of the tangents (slopes) at the nodes (control points). The shape of the resulting spline utilizes a bias parameter, t_b, that is specified by this keyword. Its exact interpretation is explained above. Simply speaking, positive values lead to a lag (along the distance axis) in the interpolated, piecewise polynomial compared to the control points, whereas negative values do the opposite.

TABREPORT

If tabulated potentials are in use (see SC_TABUL), this keyword lets the user instruct CAMPARI to print out a report of all the tabulated interactions in the system. This output can be quite large and is written to a separate output file (see TABULATED_POT.idx).

SC_DREST

This keyword controls the "outside" scaling factor for quadratic potentials acting on either interatomic distances between any pair of selected atoms or on absolute coordinates of individual atoms. Such requests are handled and processed through a dedicated input file (see FMCSC_DRESTFILE). Details regarding functional forms and available choices and parameters are in the input file documentation. SC_DREST simply controls the "outside" scaling factor c_DREST for the individual V_DREST terms, i.e., E_DREST = c_DREST·Σ_mV_DREST(m). A summary of the requested terms can be obtained with keyword DRESTREPORT.
One prominent role of using such restraints would be to allow a restrained relaxation of parts of a system (e.g., it is common to restrain protein atoms and relax water molecules in the presence of these restraints before starting a simulation of a protein in a crystallographic conformation in explicit solvent). A second important role lies in the fact that several experimental techniques (in particular NMR or FRET) can derive distance restraints on the relative position of two sites in a biomolecule. Hence, computational techniques are able to utilize this experimental information as restraints (prominent for example in the computational determination of protein structures via NMR).
CAMPARI offers the simple facility to harmonically restrain atoms which otherwise need not have any particular relationship. These restraints can be made one-sided, i.e. they can also restrain a distance to simply be within or beyond a certain threshold, which is usually a more appropriate treatment for incorporating experimental results. Nevertheless, both distance and position restraints are harmonic potentials acting on variables constrained only by the box size. Thus, a starting structure that is not compliant with a selected set of restraints will suffer from large energies/forces. Because of the stiffness of these terms, CAMPARI tries to respect distance and position restraints during structure randomization. This will frequently be imperfect, in particular since it is easily possible to set up sets of restraints that are mutually inconsistent or inconsistent with molecular topology and/or other interaction potentials.
As mentioned elsewhere, when CAMPARI's shared memory (OpenMP) parallelization is in use, all threads contribute to calculating E_DREST synchronously. Note that there is no incremental treatment of this term in Monte Carlo calculations, which is a limitation.

DRESTFILE

This keyword should give the location and name of the input file containing specific requests for specific interatomic distance and/or specific atom position restraints (see elsewhere for format description). Naturally, this is only relevant if custom distance/position restraints are in use. In a small molecule screen, if CAMPARI was instructed to create some automatic position/distance restraint terms, this file can be missing. In all other cases, the potential will be disable if this file cannot be found or parsed.

DRESTREPORT

If distance or absolute position restraint potentials are in use (see SC_DREST), this keyword allows the user to request a summary of the active restraint terms in the system. Note that this will not reflect terms added via MOL2DRESTMODE.

MOL2DRESTMODE

In a small molecule screen, CAMPARI offers to create some position/distance restraint terms as follows.

0. No terms are added. This is the default.
1. The data for the reference molecule are analyzed. This is either the first molecule in the mol2 input file or the molecule contained in the file supplied for keyword MOL2_REFMOL. The coordinates of specially indicated atoms are extracted and stored. They are used to set the minimum positions for position restraints in all three dimensions, These position restraints are then applied to all molecules using a matching scheme described elsewhere (see input documentation and keyword MOL2ASSIMILAR). This option makes sense only if the reference molecule is in a meaningful position relative to the fixed part of the system (in ligand binding terms, it is "properly docked"). Molecules for which the matching fails will have fewer or even no position restraints added.
2. Similar to the previous option, the data for the reference molecule are analyzed. The coordinates of all heavy atoms atoms are extracted and stored. They are used to define a generous envelope used to set upper and lower bounds for position restraints in all three dimensions (flat-bottom potentials), These position restraints are then applied to the heavy atoms in all subsequent molecules. As for the previous option, this option makes sense only if the reference molecule is in a meaningful position relative to the fixed part of the system (in ligand binding terms, it is "properly docked"). The number of restraints added will be proportional to the number of heavy atoms of every screened molecule. Similar restraints applied to all atoms can also be defined manually via the normal input file.

Note that for values other than 0 to work correctly, keyword SC_DREST must be set to a positive value. In all cases, the added restraints have a default force constant (k_m) of SC_DREST·1.0kcalmol^-1Å^-2. This means that the absolute strength of custom and automatic restraints can be regulated independently (by making concerted changes to SC_DREST and the force constant values in the custom input file). For both options, keyword MOL2DRESTBUF is available to add leniency to the position restraints by adding (mode 1) or extended (mode 2) flat bottoms. This is very important since in the majority of cases the information extracted from the reference molecule cannot be applicable to all screened molecules perfectly (due to differences in size, geometry of the selected substructure, etc).
Note that pose randomization can be used in conjunction with these restraints but that it is usually relatively meaningless to destroy an alignment, especially if mode 1 has been selected (it might make some sense for mode 2 in case the tethering to the reference molecule is primarily meant to create a binding site volume (rather than a specific chemotype match).

MOL2DRESTBUF

In a small molecule screen, if CAMPARI was instructed to create some automatic position/distance restraint terms, this keyword sets a buffer value in Å for position restraints. If these automatic restraints are atom-specific (mode 1 for MOL2DRESTMODE), the reference positions extracted from the tagged substructure in the reference molecule are not extended by a flat bottom of the width prescribed by this keyword. In other words, specifying a positive value for MOL2DRESTBUF will switch the position restraint from a simple harmonic potential to a potential consisting of two harmonic arms interspersed by a flat region of zero penalty that is MOL2DRESTBUF Å wide. If instead the restraints are on the envelope prescribed by the entire reference molecule (mode 2 for MOL2DRESTMODE), the potentials already have a flat bottom, and MOL2DRESTBUF can be used to extend it. This is useful if the screened molecules would not fit into the envelope of the reference molecule, which is a common problem. Note that this extension is always applied symmetrically to all heavy atoms and all coordinate axes.

SC_OSMO

This keyword controls the outside scaling factor of a simple bias potential that allows the separation of the simulation container (irrespective of shape) into two or more compartments and to apply a compartment-specific restraint potential to specific residues in the system. In essence, this creates a set of soft, semi- or impermeable membranes. The use of the method in conjunction with umbrella sampling on position restraints to calculate transfer free energies is explained in the reference publication.
Specifically, keyword OSMO_MODE selects the number of planar boundaries to be introduced. Each boundary is parallel to one of the cardinal axes of the system and passes through the simulation container's geometric center. The first boundary to be added is that orthogonal to the z-axis (xy-plane) followed by the xz- and yz-planes. Once an assignment of residues to compartments has been made (via a mandatory input file → OSMOFILE), the boundaries required to define the compartment exert a restoring force if atoms in a residue assigned to it tries to leave the compartment:

V_OSMO = c_OSMOk_BND·d_i,BND

Here, c_OSMO is the outside scaling factor defined by SC_OSMO, k_BND is the rigidity of the compartmental membrane (controlled by SOFTWALL), and d_i,BND is a shorthand notation for the effective distance of atom i from the boundary, which is always 0.0 inside the compartment. This treatment is exactly the same as that for an atom-based soft-wall boundary condition. Note that in finite systems with external boundaries, the relative strengths of inner compartment and external boundaries can be made different by choosing a value for SC_OSMO different from 1.0. The compartmental boundaries that do not coincide with an external boundary are a little more tricky to understand in periodic systems. For example, in a 3D periodic box with a single inner boundary in the yz-plane passing through the origin, an additional boundary is required at the xy-border of the box to avoid connecting the compartments via periodic images. This boundary is felt differently by particles assigned to different compartments. Periodic dimensions that are not parallel to an added inner boundary are not (and must not be) corrected in the same way.
With the help of keyword OSMOREPORT, CAMPARI will report the expected bulk densities per compartment. Because the boundaries are soft they respond to the internal pressure of each compartment. Thus, choosing compartments with dramatically different internal pressures will tend to change the effective volumes and densities per partition. In general, it is of course difficult to assert how meaningful a compartmentalization of this type can be if the compartments contain non-mixing phases (e.g. an hydrophobic gas vs liquid water or two immiscible liquids). In many cases, results from such a simulation will not be straightforwardly interpretable.

OSMO_MODE

If compartmentalization potentials are in use (see SC_OSMO), this keyword specifies the number and type of inner compartment boundaries to be added. Currently, the available options are:

1. A single planar boundary is added in the xy-plane and passing through the origin of the system (split in z). This creates exactly 2 compartments.
2. Two planar boundaries are added: one in the xy-plane and one in the xz-plane, and both passing through the origin of the system (split in y and z). This creates exactly 4 compartments.
3. Three planar boundaries are added: one in the xy-plane, one in the xz-plane, and one in the yz-plane, and all are passing through the origin of the system (split in x, y and z). This creates exactly 8 compartments.

There are currently no options to induce multiple splits in a single cardinal direction, to have planes that are not orthogonal to a cardinal direction, or to change the relative sizes of the partitions. The added boundaries are the same irrespective of the shape of the simulation container. Note that the compartmentalization potential is observed during initial structure randomization.

OSMOFILE

If compartmentalization potentials are in use (see SC_OSMO), this keyword should give the location and name of the input file containing the assignment of residues to individual compartments. Different input modes exist (by residue, by molecule, or by molecule type). This is a mandatory input file for this bias potential. The user is referred elsewhere for a detailed description of the input format. The details of the assignment can be printed to log-output by means of keyword OSMOREPORT.

OSMOREPORT

If compartmentalization potentials are in use (see SC_OSMO), this keyword allows the user to request a summary of the assignment of all residues in the system to compartments. The report will also list the formal bulk densities for the individual compartments.

SC_EMICRO

This keyword sets the global scaling factor for a spatial density restraint potential. The method was introduced recently (Vitalis and Caflisch), and the user is referred there for additional details. The potential relies on reading and quantitatively interpreting an input density map. The interpreted density for a given lattice cell with indices l, m, and n is denoted Ξ_lmn and is meant to correspond to some atomic property such as mass (→ EMPROPERTY). The potential itself is as follows:

E_EMICRO = f_EMICRO Σ_ijk (ρ_ijk - Ξ_ijk )²

The value of f_EMICRO is set by this keyword. The potential is extensive with the number of grid cells. If it is the dominant contribution in terms of CPU time to energy evaluations, the use of Monte Carlo sampling is currently quite wasteful since the values for ΔE_EMICRO are not actually incremental. The sum implied in the above equation is over all lattice cells of an evaluation grid reduced in resolution to exactly that of the input density map. Note that the dimensions of the evaluation grid are controlled by system size and shape, and that its formal resolution is either assumed to be that of the input map or set explicitly by keyword EMDELTAS (although the resultant lattice is required to have cell boundaries that align exactly with those of the input map). If the resolution of the evaluation grid is finer, the values for its cells are summed up to give the coarser resolution. Furthermore, the evaluation grid may extend beyond the input map, and in such a case the summation also includes (coarse) cells where the input is assumed to be exactly the background density. Taken together, these caveats mean that it is rarely useful not to match the input lattice exactly. That said, it also fundamentally importnat, in aperiodic boundary conditions, to avoid solutes leave the evaluation grid. When this happens, the behavior is undefined (meaning that forces and energies can be wrong or misleading). The correct workaround is provided by keyword EMBUFFER, and its value must be set considering at least also temperature and the harmonic spring constant of the boundary.
Importantly, the spatial density restraint provides an absolute reference in space, which means that it is most likely incorrect to use drift removal techniques. Another unusual aspect about this potential is that it only applies to physically present molecules in simulations in ensembles with fluctuating particle numbers. This is despite it not being a pairwise interaction term, and distinguishes it from potentials affecting the bath particles as well (such as bonded potentials). Because the potential is strictly a penalty term, this creates an effective mismatch that must be lumped manually into the excess chemical potential. This is neither pretty nor clean meaning that concurrent use of this techniques should be accompanied by the appropriate skepticism.
Depending on the choice for EMMODE, E_EMICRO can also be written using an average of the simulation density that is typically not equivalent to the canonical ensemble average:

E_EMICRO = f_EMICRO Σ_ijk ( ⟨ ρ_ijk ⟩ - Ξ_ijk )²

Here, the angular brackets indicate an average that depends on keyword EMIWEIGHT and is explained there. Further details as to why the canonical average is not used are below. Note that the potential utilizing this average no longer corresponds to a unique Hamiltonian, i.e., every time the average is updated the energy landscape changes. This means that the ensembles generated are no longer straightforward to interpret. The obvious benefits of using an ensemble-averaged restraint are twofold. First, explicit heterogeneity can explain data that would be inconsistent with a unique structure. Second, sampling is aided by the fact that "stuck" conformations will tend to become unstable in terms of E_EMICRO over time. As a final remark, users should keep in mind that the actual ensemble average generated may not agree with input given that this quantity was never actually restrained during the simulation.
As mentioned above, when CAMPARI's shared memory (OpenMP) parallelization is in use, all threads contribute to calculating E_EMICRO synchronously. However, the parallel efficiency is generally poor if either the lattices are large (in number of grid cells) relative to the number of atoms or if the solutes in a dilute system change absolute positions rapidly.

EMMODE

If the density restraint potential is in use, this keyword allows the user to choose between two options. Setting this keyword to 1 computes the restraint term by comparing the instantaneous simulation density to the input density map, whereas a choice of 2 computes the restraint term by comparing an ensemble-averaged simulation density to the input density map.
While the first option is straightforward, the second one requires some additional considerations as follows. Irrespective of whether a run is in parallel or not, the ensemble average is currently obtained over the previous sampling history (beyond equilibration) of the exact trajectory in question. Note that any average is created in terms of numbers of steps, which may cause inconsistencies in hybrid sampling runs due to the different average phase space increments. Choosing an appropriate type of average is not trivial (see, e.g., this reference), because the naive approach of including the entire sampling history leads to a continuously decreasing impact of the restraint term. There are currently two ways to address this. First, the accumulation frequency for the ensemble average can be reduced by keyword EMCALC. This slows down the reduction in impact and effectively gives the system more time to explore, because it results in concatenated runs of length EMCALC, during which the potential is in fact constant. Second, CAMPARI uses a fixed weight for the instantaneous component of the average while evaluating the potential. This fixed weight is set by keyword EMIWEIGHT and provides a way to utilize the entire history without degrading the impact of the restraint potential. A third route would be to use an appropriate kernel function in the time averaging, but this is inconvenient and potentially inefficient for spatial density analysis due to the large number of terms that would have to be stored and processed to recompute the kernel-based average.
A third option for this keyword may be added in the future that allows a lateral ensemble average to be restrained in MPI averaging calculations.

EMIWEIGHT

If the density restraint potential is in use, and if the potential acts on some ensemble-averaged simulation density, this keyword allows the user to set a fixed weight for the constructed average:

⟨ ρ_ijk ⟩ = (1-w_inst) N_steps^-1 Σ_i ρ_ijk(i) ) + w_inst ρ_ijk(current)

Here, the factor w_inst is set by this keyword and bound to the interval from 0 to 1. The ρ_ijk(i) are the N_steps values contributing to the running, canonical average of the density, and ρ_ijk(current) is the density produced by the current conformation at that given lattice cell. The limiting case of w_inst being 1.0 recovers the instantaneous treatment (→ EMMODE). The limiting case of w_inst being 0.0 does not, however, produce a meaningful restraint (since it is independent of the current conformation). Both limiting cases are therefore forbidden. Note that it is currently not possible to recover the naive approach of a restraint that continuously decreases in relevance.

EMMAPFILE

This keyword provides the location and name of the mandatory density input file when using the density restraint potential. The file format is described in detail elsewhere, and here it suffices to say that the external NetCDF library is needed, and that currently no other common density file formats (.ccp4, .mrc, ...) are read directly by CAMPARI. UCSF Chimera is able to convert between various density-based file formats, and does read and write NetCDF files.
The most common application is likely that of a simulation with 3D periodic boundary conditions and a rectangular cuboid simulation volume. Here, the cells of the input lattice should align exactly with those of the analysis and evaluation lattice CAMPARI uses, and generally it will be easiest to match both origin and dimensions exactly. By default, CAMPARI will obtain the lattice cell dimensions from the input map. For nonperiodic boundaries (including simulation systems with curved boundaries), it will be required, however, to deviate from such an exact match. Here, keyword EMBUFFER can be used to define the buffer in size for the evaluation grid at any nonperiodic boundaries. Furthermore, keyword EMDELTAS can always be used to request the analysis and evaluation lattice to have cells of a smaller size, which, with the restraint potential in place, has to yield the exact input cell size by integer multiplication for all three dimensions. Lastly, keyword EMREDUCE can be used to average the input map to a lower resolution by re-binning.
Assuming no further transformations are applied (→ keywords EMREDUCE, EMTRUNCATE, EMFLATTEN), the interpreted density based on the input file is as follows:

Ξ_ijk = ρ_sol + c(ω_ijk - ω_bg)

Here,the final density for a given lattice cell, Ξ_ijk, has units of physical density, c is a scale factor explained below, ω_ijk is the original input density for the same lattice cell, and ρ_sol and ω_bg are the assumed physical and input background signals, respectively. ρ_sol is set by keyword EMBGDENSITY, and ω_bg can be set by keyword EMBACKGROUND if the value determined automatically from the histogram of input densities is not appropriate. Factor c is given as follows:

c = [ M_M - ρ_sol Σ_ijk V_ijk H(ω_ijk-ω_t) ] · [Σ_ijk (ω_ijk-ω_bg)V_ijk H(ω_ijk-ω_t) ]^-1

Here, the first term in square brackets is a hypothetical excess signal (mass) using the apparent macromolecular volume (the sum of the volume of all lattice cells with signals exceeding the threshold, ω_t) and the assumed total mass. The V_ijk are the volumes of individual lattice cells and currently have to be all equal, and H(x) denotes the Heaviside step function. The second term in square brackets is the actual excess signal (mass) derived from the input map obtained by analogous summation. Factor c has units that convert optical density (input) to physical density. It is important to note the crucial impact of keywords EMTHRESHOLD and EMTOTMASS on the quantitative interpretation of the map. In particular, many combinations of values will be rejected by CAMPARI, because they cannot produce an excess signal larger than the background. The resultant interpreted map is written to a dedicated output file at the beginning of each run. Note that this includes all optional transformations controlled by keywords EMREDUCE, EMTRUNCATE, and EMFLATTEN.

EMREDUCE

If the density restraint potential is in use, this keyword can be used to change the formal resolution of the input density map. This is accomplished by simple re-binning, i.e., the target and original lattices are aligned at the origin, and the original signal for each cell is distributed to the target cells by simple overlap. Because the input is assumed to be a density, volume renormalization is performed. Note that it is generally meaningless to create a finer grid this way, because no new information is available, and CAMPARI distributes signal assuming a flat distribution inside each original input cell. Similar to keyword EMDELTAS, this keyword requires the specification of three floating point numbers that set the target lattice cell sizes of the re-binned input map in Å for the x, y, and z dimensions, respectively. Note that the exact values will generally be slightly different because of the requirement to have the outer dimensions of both grids align exactly. Finally, users should keep in mind that physical resolution and formal resolution of the lattice used to represent the data are two distinct quantities.

EMBACKGROUND

If the density restraint potential is in use, this optional keyword can be used to override the value determined to correspond to background in the input density map (ω_bg in the equation above). This value is commonly set by binning the densities in all cells, and identifying a well-resolved peak in the histogram. If the map does not encode much background signal, the histogram-based determination may be inappropriate, and this is when this keyword is useful. Note that values refer to the original input density map. The meaning of the background level for positive definite atomic properties like mass is that of an approximate lower bound. The meaning for other properties (where values for individual atoms can offset each other like charge) is typically more that of a median or mean. If more than one custom atomic properties are used, this keyword should have the corresponding number of entries, one for each property. Users are advised not to confuse this keyword with EMBGDENSITY, which sets the expected background level in physical units (see the first equation shown for EMMAPFILE).

EMTHRESHOLD

If the density restraint potential is in use, this important keyword controls the linear transform used to interpret the input density map in terms of a physical density of one or more atomic properties of interest. Specifically, it sets a threshold level in units and numbers of the (potentially re-binned) input that distinguishes signal from background. Since measurements often have low contrast, the threshold is not an obvious property of the input map. The threshold set here corresponds to parameter ω_t in the equation above. It is primarily responsible for the overall scaling factor, i.e., larger threshold values will generally produce interpreted maps with a wider spectrum of physical density values. Using the apparent molecular volume and the total integral, the chosen threshold directly determines the apparent physical density (reported in log-output). This quantity poses constraints on the chosen value, because the integrated signal must be yielding a density larger than the assumed physical background density. For atomic properties, for which values for individual atoms can offset each other, the threshold is compared to the absolute values of the input density. This absolute value is, however, applied to the difference of the actual value from the automatically determined or specified background level. If more than one custom atomic properties are used, this keyword should have the corresponding number of entries, one for each property.

EMTOTMASS

If the density restraint potential is in use, this keyword sets the net integral to be assumed for the selected atomic property or properties (units differ accordingly). This is basically the "total signal above noise" expected to be explained by the input density map, and it is consequently restricted to the lattice cells exceeding the chosen threshold. In general, for positive definite properties like atom or proton mass, this can be set to correspond exactly to the explicitly represented matter in the simulation (this is the default), but exceptions may desire an override, e.g., when simulating only a part of the system without wanting to distort the interpretation of the map. The parameter corresponds to M_M in the equation above. For other properties like partial charges, the value should be the sum of the absolute values of these properties. This is required to arrive at a meaningful interpretation of the map that is usable in a quantitative way for the density restraint potential. If more than one custom atomic properties are used, this keyword should have the corresponding number of entries, one for each property.

EMTRUNCATE

If the density restraint potential is in use, this keyword enables truncation of the input map below the chosen value as long as it is higher than the minimum and lower than the assumed threshold level (ω_t in the equation above). Truncation implies that the spectrum of values for the interpreted density is completed depleted below the specified level. For a positive definite property like mass, all values below the threshold level are simply assigned the background level, ω_bg. Conversely, for a property that can assume both positive and negative values, all values below the threshold level are simply assigned the threshold level itself. In the former scenario, this technique is commonly used to eliminate noise from the input that may hamper sampling (it flattens a noisy background). In the latter scenario, EMTRUNCATE is the exact complement to EMFLATTEN and can be used to remove spikes in the negative direction. In all cases the specified value or values refer to the density levels as found in the original input density map. If more than one custom atomic properties are used, this keyword should have the corresponding number of entries, one for each property.

EMFLATTEN

Depending on how a density map is generated, the signal may cover a wide spectrum of values. This is particularly true if the contrast to the background is generally low, and the lack of contrast is compensated for by averaging over similar, but heterogeneous conformations. In such cases, the ratio of peak to barely detectable signals may be impossible to describe by physical densities of instantaneous conformations. If the density restraint potential is in use, this keyword therefore allows the user to flatten an input density map at a given level specified by this keyword. The requirement is that the value be larger than the assumed threshold level. This keyword is complementary to EMTRUNCATE: in an exact manner for atomic properties that can take both negative and positive values (EMFLATTEN works only on the positive end) and in a qualitative manner for positive definite properties (where negative "spikes" are not realistic). Both keywords used concurrently can produce an interpreted map that is purely an envelope of a more or less fixed and homogeneous density. Finally, if more than one custom atomic properties are used, this keyword should have the corresponding number of entries, one for each property.

EMHEURISTIC

The evaluation of the density restraint potential involves the summation of contributions from all the grid cells. Each cell contributes a squared difference of the input density and the actual density for the current conformation of explicit matter in the system. If the formal resolution is high, the evaluation of the potential can be costly. Occasionally, it may be possible to save some CPU time by applying dedicated heuristics, and this is what is controlled by this keyword. Choices are as follows:

0. No heuristic is used. At each global evaluation of the density restraint potential, all grid cells are recomputed and summed up.
1. When spreading the atomic masses in the system onto the analysis and evaluation grid, CAMPARI keeps track of whether any given xz-slice of the input map actually received a contribution from any atom. If not, the cells constituting this xz-slice are not recomputed, but instead a precomputed value for the entire slice is used. This is possible because the simulation densities in all the cells of the slice will be equivalent to the assumed background density. Efficacy of this heuristic obviously depends on the details of the system.
2. This works identically to the previous option, except that x-lines are considered rather than xz-slices.
3. This works identically to the previous options, except that local rectangular supercells are used rather than xz-slices or x-lines. Here, the algorithm will try to combine existing grid cells to yield approximately 1000 supercells. This option is probably the most successful in general, because it can match arbitrary arrangements of explicit matter best.

Note that heuristics of the above type offer only moderate savings if on average the explicit matter does in fact cover the evaluation and analysis grid to a large fraction.

MOL2EMMODE

Not yet documented.

GHOST

This keyword is a simple logical that determines whether or not to (partially) "ghost" the interactions of selected particles (see FEGFILE) with the rest of the system (and eventually amongst themselves → FEG_MODE). Such scaling of interactions creates artificial systems which can be used to interpolate between two well-defined end states. The most common need for such an application arises in cases where the two end states are significantly different and one is interested in the free energy difference. For example, to calculate the aqueous free energy of solvation of a small molecule in water, one could scale the interactions of the small molecule with water from zero to their full value. Such growth-based calculations are usually complicated to set up and perform since i) trajectories evolved at a given Hamiltonian have to be evaluated (on-the-fly usually) assuming different Hamiltonians, and ii) it is difficult to maintain an internally consistent system of interactions such that all changes induced by the ghosting can be mapped to atomic parameters of the ghosted species. In CAMPARI, FEG (free energy growth/ghosting) calculations are therefore supported in conjunction with limited Hamiltonians only: the only potentials allowed are IPP, ATTLJ, POLAR, and the bonded interactions. In other cases, it may be possible to extract the same or related quantities through other techniques realizable in CAMPARI. As an example, the free energy of solvation for a flexible (single) solute immersed in the ABSINTH continuum solvation model can be obtained by simultaneously scaling the dielectric from 1.0 to 78.0 and the DMFI from 0.0 to 1.0. The default settings for the auxiliary keywords to GHOST are such that the molecules or residues listed in FEGFILE will be completely ghosted (i.e., invisible to the system).

FEG_MODE

In FEG calculations interactions (see GHOST) are always scaled between the ghosted species and the rest of the system. A natural question arises as to what happens to interactions between or within ghosted species (if any are present)? If they are not scaled but instead use the background Hamiltonian it will be impossible to map the effect of the scaling to a change in atomic parameters which is desirable from the viewpoint of rigor. As an example, consider polar interactions between a single ghosted butane molecule and a bath of non-ghosted water. A scaling of the atomic charges on the ghost butane by a factor f would give rise to interactions with the bath scaled by f and self-interactions scaled by f². This type of scaling is enforced in CAMPARI if a method requires it such as treating electrostatics with the reaction-field method (see LREL_MD). In general, however, it is impossible to find a unique mapping while leaving the background Hamiltonian intact. It is therefore left to the user to determine which of two options to choose:
 1) Interactions between/within ghosted species use the full background Hamiltonian.
 2) Interactions between/within ghosted species use the scaled Hamiltonian.
The choice made here is important only if such interactions are present in the system. If so, however, the raw results will usually depend strongly on it and corrections may have to be applied. As an example, consider the butane-water example from above. The fact that intramolecular interactions are scaled will contribute toward the apparent free energy obtained when interpolating between the fully ghosted and the fully present states. Hence, gas phase corrections have to be applied. They are obtained by repeating the calculation in the absence of water to compute the thermodynamic cycle which then allows isolating the free energy of solvation. Additional complications may arise if molecules are constrained (see FRZFILE).

FEG_IPP

This keyword specifies the "outside" scaling factor for the ghosted inverse power potential. Note that depending on the choice for FEG_LJMODE this is not as simple as SC_IPP and that additional parameters may determine the impact this keyword has. The setting here corresponds to the parameter s_gIPP below. Note as well that the inverse power potential supported in calculations with ghosted interactions always uses an exponent of 12 (i.e., setting IPPEXP to anything but the default of 12 will cause CAMPARI to abort). This keyword is only relevant if GHOST is true.

FEG_ATTLJ

This keyword is analogous to FEG_IPP but controls the "outside" scaling of the attractive r^-6 dispersive term. The setting here corresponds to the parameter s_gattLJ below. Note that scaling this up while FEG_IPP is set to zero (or - depending on the mode - even set to something smaller) will potentially lead to numerical instabilities.

FEG_LJMODE

The exact functional form of the scaled (ghosted) Lennard-Jones potential is as follows:

E_gLJ = 4.0·ΣΣ_i,j ε_ijf_1-4,ij·[ g(s_gIPP)·[α·h(s_gIPP) + (r_ij/σ_ij)⁶]^-2 - g(s_gattLJ)·[α·h(s_gattLJ) + (r_ij/σ_ij)⁶]^-1 ]

Here, the ε_ij and σ_ij are the standard pairwise Lennard-Jones parameters (see PARAMETERS), the f_1-4,ij are potential 1-4 fudge factors (see FUDGE_ST_14) that generally will be unity, g(s) and h(s) are auxiliary functions whose functional form depends on the choice for this keyword, and α is the so-called soft-core radius (unitless). The two scaling factors s_gIPP and s_gattLJ are provided by keywords FEG_IPP and FEG_ATTLJ). There are three possible choices determining g(s) and h(s):

1. g(s) = s
   h(s) = 0
2. g(s) = s^f₁
   h(s) = 1.0 - s^f₂
3. g(s) = (1.0 - e^-sf₁)/(1.0 - e^-f₁)
   h(s) = (1.0 - s)^f₂

Option 1 corresponds to a simple linear scaling which is unsuitable for most purposes since it does not remove the singularity at r_ij→0. Mode 2 is the most common workaround which introduces polynomial scaling via additional parameters f₁ (→ FEG_LJEXP) and f₂ (→ FEG_LJSCEXP). The non-zero values of h(s) will also make the soft-core radius α a relevant parameter. The latter is specified through keyword FEG_LJRAD. Essentially, interpolation between the singularity-containing native potential and a zero potential is obtained by successively ramping up a barrier proportional to (h(s)·α)^-1, which for tiny values of h(s) (s→1) approaches the singularity. Mode 3 is very similar but uses exponential rather than polynomial scaling for g(s) and a slightly different functional form for h(s). The parameters are reinterpreted accordingly. In all cases, setting s to zero will eliminate the potential entirely, while setting it to unity will recover the native Lennard-Jones potential. This keyword is only relevant if GHOST is true.

FEG_LJRAD

This keyword allows the user to specify the parameter α in the above equations (see FEG_LJMODE), i.e., the soft-core "radius" for the modified Lennard-Jones potential. It is generally of limited utility to set this to zero since in that case the scaled potential could as well be created by setting FEG_LJMODE to 1 in which case this parameters becomes meaningless. Conversely, for large soft-core radii, the potential is modified for large distances which generally represents unnecessary modification which may slow down convergence in free energy calculations relying on interpolation via ghosting. Generally speaking, values around 0.5 are recommended for either mode 2 or 3. This keyword is only relevant if GHOST is true.

FEG_LJEXP

This keyword sets the parameter f₁ in the above equations (see FEG_LJMODE). It represents a way to - in a simple way - alter the weight of change experienced by the system depending on the choices of FEG_IPP and FEG_ATTLJ. In that sense, it is very closely tied to the design of the interpolation schedule (i.e., both address the exact same issue). There are no gold standard rules for picking this and the user is referred to the literature for further details. In case of free energy calculations, it will be best to inspect the schedule empirically by metrics such as the statistical precision of the pairwise estimates or overlap metrics such as (theoretical) swap probabilities and to then refine either the schedule itself or the global settings accordingly. This keyword is only relevant if GHOST is true.

FEG_LJSCEXP

This keyword sets the parameter f₂ in the above equations (see FEG_LJMODE). Much of the same discussion applies here as already mentioned for keywords FEG_LJRAD and FEG_LJEXP. This keyword is only relevant if GHOST is true.

FEG_POLAR

The only other non-bonded potential besides Lennard-Jones supported in FEG calculations is the polar potential (see SC_POLAR). This keyword provides a scaling factor (s_gPOLAR) for the soft-core Coulomb potential. Much similar to the case for scaled LJ interactions (see above), this may involve three additional parameters (see FEG_CBMODE). Note that it would be most common to only scale this up while FEG_IPP is set to unity so as to avoid potential numerical instabilities.

FEG_CBMODE

In analogy to FEG_LJMODE, this keyword determines what exact functional form CAMPARI uses for the scaled (ghosted) Coulomb potential with the "outside" scaling factor s_gPOLAR set by\ FEG_POLAR):

E_gLJ = (4.0πε₀)^-1·ΣΣ_i,j g(s_POLAR)·q_iq_j·f_1-4,C,ij·[α_C·h(s_gPOLAR) + r_ij]^-1

Here, the atomic partial charges are represented as q_i,j, ε₀ is the vacuum permittivity, and r_ij is the interatomic distance. f_1-4,C,ij denotes potential fudge factors acting on 1-4-separated atom pairs (see FUDGE_EL_14) but will generally assume a value of unity. g(s) and h(s) are the same auxiliary functions defined above for the Lennard-Jones potential (→ FEG_LJMODE) and α_C is the soft-core radius (unitless) specific to the Coulomb potential (controlled by keyword FEG_CBRAD). For completeness the options are listed again in detail:

1. g(s) = s
   h(s) = 0
2. g(s) = s^f_C,1
   h(s) = 1.0 - s^f_C,2

The "outside" scaling factor s_POLAR is controlled through keyword FEG_POLAR. Additional parameters in mode 2 are f_C,1 (→ FEG_CBEXP) and f_C,2 (→ FEG_CBSCEXP).

FEG_CBRAD

This keyword is analogous to FEG_LJRAD and allows the user to choose the value for the soft-core radius specific to the Coulomb potential (α_C in the equations under FEG_CBMODE). The specification is meaningless if FEG_CBMODE is set to 1.

FEG_CBEXP

This keyword is analogous to FEG_LJEXP and allows the user to choose the value for the polynomial scaling exponent to the Coulomb potential (f_C,1 in the equations under FEG_CBMODE). The specification is meaningless if FEG_CBMODE is set to 1.

FEG_CBSCEXP

This keyword is analogous to FEG_LJSCEXP and allows the user to choose the value for the soft-core scaling exponent to the Coulomb potential (f_C,2 in the equations under FEG_CBMODE). The specification is meaningless if FEG_CBMODE is set to 1.

FEG_BONDED_B

Non-bonded interactions provide a straightforward interpretation for parsing the energetics of the system into solute-solvent, solute-solute, and solute-solvent contributions. This is used in a thermodynamic cycle argument when computing - for instance - the free energy of solvation of a solute in solvent via FEG methods. Sometimes (as alluded to under FEG_MODE), it may be desirable to scale intramolecular non-bonded interactions as well. But what about intramolecular bonded interactions? This keyword allows the FEG-like scaling of bonded terms associated with a ghosted species but not of those associated with non-ghosted particles. Beyond that this keyword operates just like SC_BONDED_B. Note that this almost certainly creates a pathological situation if bond length potentials are allowed to approach zero and naturally relies on bond lengths being allowed to vary (see CARTINT) to be meaningful. Note that for all bonded parameters the assignment of terms to individual residues in a multi-residue molecule is somewhat arbitrary if atoms from two different residues participate.

FEG_BONDED_A

This is analogous to FEG_BONDED_B only for bond angle potentials. Note that this may lead to a pathological simulation if bond angle potentials are allowed to approach 0° or 180° and - again - relies on bond angles actually being varied throughout the simulation to be meaningful.

FEG_BONDED_I

This is analogous to FEG_BONDED_B only for improper dihedral angle potentials. Note that this may lead to a pathological simulation if improper dihedral angle potentials are allowed to approach zero and - again - relies on these degrees of freedom actually being varied throughout the simulation to be meaningful.

FEG_BONDED_T

This is analogous to FEG_BONDED_B only for proper dihedral angle potentials. Note that this relies on torsional angles actually being varied throughout the simulation to be meaningful (there may be subsets).

FEGREPORT

This simple logical keyword lets the user instruct CAMPARI to write out a summary of the ghosted particles (residues or molecules) in free energy growth/ghosting calculations.

SCULPT

The accelerated molecular dynamics method of Hamelberg et al. offers a general (parameter-dependent) way to modify the potential energy landscape or individual terms thereof (torsional potentials and 1-4 interactions have been used most often). The idea is that a controlled modification of the landscape that leads to reduced barrier heights is capable of massively accelerating the effective dynamics without reducing the ensemble overlap dramatically. CAMPARI offers a generalization of this approach as follows:

E_ELS = Σi E_i + ΔE_i,ELS

ΔEi,ELS =	0	if Vif < Ei < Vis
	(Vif - Ei)2/(Vif - Ei + αif)	if Vif > Ei
	(Vis - Ei)2/(Vis - Ei - αis)	if Ei > Vis

Here, the sum runs over all active terms of the Hamiltonian. These are generally the terms CAMPARI offers a global scaling factor for, e.g., the total DMFI of the ABSINTH model, E_DMFI, the total sum of improper torsional potentials, E_{BONDED_I}, etc. Limitations are discussed below. By default, the threshold energy parameters for every energy term, V_i^f and V_i^s, are initialized such that E_i,ELS is always zero, i.e., no sculpting occurs. They can be modified with the auxiliary keywords ELS_FILLS and ELS_SHAVES. Naturally, V_i^f must always be less than or equal to V_i^s. The parameters α_i^f and α_i^s must always be greater than or equal to zero. They serve as buffer parameters. The modified energy landscape for a given term has two possible modifications. First, its low energy states (local minima) can be filled up. Using α_i^f as zero flattens all low energy states to the specified threshold, V_i^f. Larger values for α_i^f preserve the unbiased shape of the landscape more and more, and the limit of α_i^f reaching infinity recovers the unbiased potential exactly. Second, its high energy states (barrier regions) can be shaved off and the use of α_i^s as zero flattens all barrier regions to the value of V_i^s exactly. The effect of larger values is exactly analogous. Note, however, that potentials allowing for large positive energy values must be treated with caution (notably inverse power potentials). The value of ΔE_i,ELS for large negative values of (V_i^s - E_i) obviously approaches (V_i^s - E_i) itself, which means that the barriers are more or less completely eliminated. This can be dangerous in conjunction with attractive nonbonded interactions (numerically speaking) and also lead to poor behavior during reweighting (see below).
This keyword (SCULPT) allows the user to specify one or more terms to be sculpted (list of integers). The choices available correspond exactly to the columns of output file ENERGY.dat (click the link for a list). It includes the total energy (choice 2), which is mutually exclusive with any other term. There are further limitations as follows:

• In gradient-based simulations (including hybrid runs), nonbonded interactions can only be controlled as a single joint term (sum), viz., the sum of all active short-range steric interactions (see SC_IPP, SC_ATTLJ, and SC_WCA) as well as polar and tabulated interactions (see SC_POLAR and SC_TABUL). The correct code to use for this joint term is 15.
• The use of the (quasi-obsolete) correction potential is not supported when using any energy landscape sculpting.

These caveats apply to the specific sculpting of nonbonded energy terms in gradient-based simulations. Note that the standard nonbonded potentials diverge at small distances, which means that the energy range is unbound. This will result in vanishing weights for the majority of conformations even for very small systems. Similarly, while the total energy (option 2) can always be sculpted (but must be the only term as mentioned above), this is rarely useful for anything but toy models for exactly the same reason. Extensions in the future may allow the specific targeting of small subsets of nonbonded and bonded interactions to circumvent this problem. Note that any energy term will be completely disabled by choosing both buffer parameters as zero (keywords ELS_ALPHA_F and ELS_ALPHA_S) and by setting the threshold energies to the same value (keywords ELS_FILLS and ELS_SHAVES). Lastly, note that the energy output in ENERGY.dat will continue to report unperturbed energies, whereas all other files with energies (e.g., ENSEMBLE.dat) will give the sculpted values.

ELS_FILLS

If the energy landscape sculpting method is in use, this keyword supplies the parameters V_i^f described above. Values are to be provided in kcal/mol. For example, if the choices for SCULPT are "20 22", then a choice for ELS_FILLS of "5.0 5.0" would provide lower threshold energies of kcal/mol each to both proper dihedral angle potentials and to CMAP potentials. It is not possible to skip values, i.e., the length of the list supplied here should be identical to that for SCULPT. To disable the basin filling aspect of sculpting, it is generally safe to supply a very large negative energy here.

ELS_SHAVES

If the energy landscape sculpting method is in use, this keyword supplies the parameters V_i^s described above. Values are to be provided in kcal/mol. The interpretation is identical to keyword ELS_FILLS above. To disable the barrier shaving aspect of sculpting, it is generally safe to supply a very large positive energy here.

ELS_ALPHA_F

If the energy landscape sculpting method is in use, this keyword supplies the parameters α_i^f described above. Values are to be provided in kcal/mol and must be zero or positive. Note that a choice of zero inevitably leads to force discontinuities. In addition, the absence of any force (flat surface) will lead to the natural shape of the landscape being completely forgotten, which can deteriorate the statistical significance of the reweighted results.

ELS_ALPHA_S

If the energy landscape sculpting method is in use, this keyword supplies the parameters α_i^s described above. Values are to be provided in kcal/mol and must be zero or positive. The keyword is interpreted identically to ELS_ALPHA_F above and applies to the barrier shaving aspect.

ELS_PRINT_WEIGHTS

If the energy landscape sculpting method is in use, this keyword controls the output frequency for output file ELS_WFRAMES.dat, which contains the corresponding simulation step numbers (that will of course increase in steps of ELS_PRINT_WEIGHTS) and the associated weights. These weights are derived from knowledge of the applied net sculpting potential for each snapshot as w_i = exp(β E_ELS). They can be used in a trajectory analysis run with user-supplied frame weights. Note that large positive values of the sculpting potential will make the reweighting susceptible to shot-like noise (due to few conformations receiving very large weights).

EWALD

CAMPARI supports using the Ewald decomposition technique to compute long-range electrostatic interactions in periodic systems (see LREL_MD). There are two supported approaches to computing the reciprocal space sums in the Ewald formalism:

1. Particle-Mesh Ewald (PME): This elegant and vastly popular method introduced by Darden et al. uses discrete Fourier transforms (DFFTs) and cardinal B-splines to simplify the computation of the reciprocal space sum. Due to the DFFTs, CAMPARI needs to be linked against the free open source-library FFTW for this option to be available. Briefly, PME reciprocal space sums have different scaling components, i) the number of charges; ii) the number of grid-points; iii) the interpolation order for the cardinal B-splines. It depends strongly on the system which of these components is the speed-limiting factor, in particular since the accuracy of the reciprocal sum depends on the simultaneous optimization of the spline order (see BSPLINE) and the grid-size (EWFSPAC) given that the real-space part co-determines the Ewald parameter (EWPRM). Note, however, that the fundamental scaling with the number of charges is O(N). The performance of PME is only partially controlled by CAMPARI as the library calls can be (and often are) the bottleneck. Coarser grids, higher spline orders, and higher number densities of partial charges decrease the relative workload of the DFFTs. The general performance of the DFFTs can sometimes be improved by providing or computing a better "plan". This is supported by keywords EWFFTPLANNER and EWWISDOMFILE. If the shared memory (OpenMP) parallelization of CAMPARI is in use, this also triggers calling the threaded FFTW library. The performance of this call is tricky to predict, however, because it is spawned from a multi-threaded execution region to begin with (inside an OpenMP MASTER construct). This causes additional thread generation and destruction operations that are a cost factor, both directly and indirectly (through the kernel having to manage a temporarily oversubscribed machine). It implies that the performance results become strongly dependent on the thread affinity model and respond to environment variables such as OMP_PROC_BIND. Keyword THREADS_TEST allows a quick way to test parallel FFTW performance for the system at hand. Irrespective of these complications, PME is the recommended (since fastest) implementation of Ewald sums.
   
2. Standard Ewald: A straightforward computation of the reciprocal part of the original decomposition introduced by Ewald is supported by CAMPARI as well. This method is slow and scales poorly (K³) with the (linear) cutoff size in the reciprocal dimension. Much like PME, the reciprocal sum fundamentally scales as O(N) with the number of charges, however. Standard Ewald might occasionally be a reasonably efficient alternative should tight cutoffs in reciprocal space be permissible (or should PME be slowed down due to a dominant cost imposed by DFFTs such as in very dilute systems using big boxes). If the shared memory (OpenMP) parallelization of CAMPARI is in use, the standard Ewald sum is expected to scale well as long as the number of residues is reasonably large.

Note that any Ewald method is only accessible in dynamics calculations using specialized loops at the moment. This is due to the underlying assumptions (the real-space part uses a functional form that is different from simple Coulomb summation) as well as due to the lack of decomposability of the algorithm for the purpose of MC calculations (→ LREL_MD for details). The real-space part relies on the error function, which can be approximated by a tabulation with controllable accuracy.

EWERFTOL

If the Ewald method is used for treating long-range electrostatic interactions, this keyword can be used to set an accuracy tolerance for the tabulated computation of the (complementary) error function (and its derivative). This uses additional tricks to save operations (details omitted). Because the tabulated values can be a significant amount, the performance of this implementation is usually cache- rather than FLOP-limited. The tabulation can be disabled at the compilation stage by passing the variable "DISABLE_ERFTAB" (see installation instructions) as many modern compilers offer support for fast math libraries occasionally also with controllable precision.

BSPLINE

When using the PME method (see LREL_MD and EWALD), this keyword determines the order of the cardinal B-splines to be used. The order can be increased at a moderate cost, such that it is sometimes advantageous to choose a higher interpolation order coupled to a relatively coarse mesh (see EWFSPAC) instead of a lower interpolation order coupled to a finer mesh. The default order is 6, and currently only even numbers are permitted (uneven numbers are adjusted to the default automatically). For various reasons, it is not recommended to use orders below 4. In any case, it can be useful to try different settings and study the predicted accuracy and initial energies that are reported at the beginning (summary of the calculation written to log-output).

EWFSPAC

When using the PME method (see LREL_MD and EWALD), this keyword determines the grid spacing for the mesh in Å. A smaller value yields a finer mesh which in turn yields more accuracy. The cost associated with finer grids easily becomes substantial (K³-scaling), though, even when using the DFFTs provided by FFTW. The code will occasionally adjust too coarse a value since the interpolation order (BSPLINE) requires a certain minimum for the number of available mesh points in each dimension. When using the standard Ewald method, keyword EWFSPAC determines the reciprocal space cutoffs to either side directly as the ratio of half the box side length and itself. In any case, it can be useful to try different settings and study the predicted accuracy and initial energies that are reported at the beginning (summary of the calculation written to log-output).

EWPRM

When using the Ewald method (see LREL_MD and EWALD), this can be used to overwrite the automatically determined value for the Ewald parameter. The Ewald parameter is given in units of Å^-1 (but can just as well be defined as a dimensionless parameter). It determines the relative weight of the real-space and the reciprocal sum in determining the total electrostatic energy of the system. The larger EWPRM is the more weight shifts to the reciprocal sum. Note that the accuracy of the Ewald method is highly sensitive to this parameter in conjunction with the real-space and reciprocal space cutoffs and that a catastrophic lack of accuracy can easily be realized. Therefore, the code tries to determine a reasonable value for the Ewald parameter based on the (hard) settings for the real-space cutoff (NBCUTOFF) as well as EWFSPAC and - in the case of the PME method - BSPLINE. Unfortunately, the accuracy predictor formulas in use are currently somewhat flawed (they are based on the mean force error estimates presented by Petersen). They should be more accurate for the standard Ewald method than for PME since in the latter certain error contributions from the spline-based interpolation are missing. Hence, the automatically chosen parameter should by no means considered an optimal one, merely one which - given the cutoff settings - provides comparatively small errors in forces and energies. Should the procedure be deemed inadequate or should there be an independent estimate of the error this keyword comes into play. In any case, it can be useful to try different settings and study the predicted accuracy and initial energies that are reported at the beginning (summary of the calculation written to log-output).

EWFFTPLANNER

This keyword is only relevant if the particle-mesh Ewald is used (see LREL_MD and EWALD). It can then be used to control how hard the linked FFTW library will try to compute an efficient plan for the involved DFFTs before the start of the simulation. The options are as follows:

1. A heuristic and practically cost-free estimate is used. For simple cases and geometries, this is often appropriate enough (corresponds to FFTW_ESTIMATE).
2. Explicit measurements are performed to pick a reasonable plan but the algorithmic space explored is limited (this is the default and corresponds to FFTW_MEASURE).
3. Explicit measurements are performed to pick a reasonable plan and the algorithmic space is widened relative to the previous option (corresponds to FFTW_PATIENT).
4. Many explicit measurements are performed across a wide algorithmic space to determine the best plan (this is very expensive and corresponds to FFTW_EXHAUSTIVE).
5. A previously determined plan is read in in the form of a "wisdom file" (see EWWISDOMFILE).

Since all options except 1 and 5 rely on explicit measurements, the cost of finding a plan can be significant in these cases. Options 3 and 4 are really meant for unusual, for example very large, cases. If many simulations are to be performed on the same system, it can be useful to reuse the planning information (option 5). For this, keywords EWWISDOMFILE and EWSAVEWISDOM required.

EWSAVEWISDOM

This keyword is only relevant if the particle-mesh Ewald is used (see LREL_MD and EWALD). It instructs CAMPARI to save a DFFT plan generated by the FFTW library in the form of a wisdom file. For this, the value for EWFFTPLANNER has to be 1-4. Note that wisdom files are not compatible between the threaded and serial FFTW libraries. The former is evoked automatically if the shared memory (OpenMP) parallelization of CAMPARI is in use. The name for the wisdom file is chosen by keyword EWWISDOMFILE.

EWWISDOMFILE

This keyword is only relevant if the particle-mesh Ewald is used (see LREL_MD and EWALD). It provides the name for a FFTW wisdom file to be either read in (if EWFFTPLANNER is 5) or written (if EWFFTPLANNER is not 5). Note that the wisdom file is an autonomous output file of the FFTW library and not documented further either here or in the dedicated documentation. Users can find more information elsewhere (links out).

RFMODE

When using the Reaction-Field method (see LREL_MD), this keyword determines whether the corrections include a continuum electrolyte assumption (generalized reaction field) or not:

1. The generalized reaction-field correction is used. The code determines the concentration of net charges (including those which are part of macromolecules) and derives an effective ionic strength. This bulk electrolyte concentration is used to model the dielectric response outside of the cutoff sphere for an individual charge in a Poisson-Boltzmann sense.
2. The standard reaction-field correction is used. Irrespective of the existence of free, net charges in the system, the dielectric response is simply an approximate solution to the Poisson equation.

Note that for a system void of net charges (purely polar), the two methods are identical. Also note that the bulk dielectric of the dipolar medium outside of the cutoff sphere is set by IMPDIEL. The reaction field method produces a force discontinuity at the outer cutoff distance for all assumed dielectric constants smaller than infinity. The use of the method in conjunction with twin-range cutoffs (inner cutoff distance is less than outer cutoff distance and the neighbor list update frequency is larger than one) is explicitly disallowed due to unpredictable and generally poor stability.

Cutoff Settings:

---

(back to top)

CUTOFFMODE

If nonbonded interactions dependent on interatomic distances are in use (IPP, ATTLJ, WCA, IMPSOLV, TABUL, and POLAR), it is often necessary to truncate these interactions. Historically, there have been a large number of implementations to achieve this, both in how to to effectively determine the interactions to compute and how to deal with the force discontinuity and truncation. CAMPARI does not implement empirical switching functions. The WCA and IMPSOLV potentials have exact cutoffs by virtue of their functional forms. IPP, ATTLJ, and TABUL can only be truncated. Long-range electrostatics options are supported (LREL_MC and LREL_MD). Keyword CUTOFFMODE controls whether to apply truncation at all and how to search for nearby interaction partners. This is (currently) always done using residue-based, buffered neighbor lists. The neighbor lists are in general not post-processed to achieve exact truncation at the chosen distance, which means that the effective range of interactions is larger (dependent on the buffer size, which are computed from residue radii).
All cutoff implementations are responsive to the shared memory (OpenMP) parallelization although some particular combinations of samplers, cutoffs, and Hamiltonians may not be supported. In general, the parallel efficiency of the neighbor lists calculations is acceptable. The major performance-limiting factor is that relatively complex and large data structures are used in relation to relatively low number of floating point operations, which can expose weaknesses in cache management.
The following modes are available:

1. If - for whatever reason - cutoffs are undesirable, the code will assume that all residues are spatial neighbors and compute all interactions at every step. Note that not all combinations of samplers and Hamiltonians might support this option since optimized loops relying on neighbor lists are often employed (and/or the method may rely in its formulation on a cutoff). Limited support (or performance) may also exist if the shared memory (OpenMP) parallelization is in use. It implies that most other keywords in this section become meaningless (e.g., NBCUTOFF, LREL_MD, etc.).
2. This option is obsolete.
3. This option instructs CAMPARI to employ grid-based cutoffs. The grid-association is governed at the residue level by the position of the residues' reference atoms. All grid-based methods (with a uniform mesh) are difficult/inefficient for systems with very asymmetric density (such as a single very long extended chain in a large periodic box) since those systems would either require too large grids (inefficient and memory-consuming) or are so coarse that no efficient pre-screening can occur. Grid-based cutoffs are a good choice for systems with homogeneous density and many small (few atoms) residues. They are absolutely indispensable for simulations of large explicit water systems as any other cutoff mode supported by CAMPARI will critically slow down simulations in such scenarios. Like all cutoffs in CAMPARI, the grid is used with a buffer size dependent on residue radii (in addition to the actual interaction cutoffs, viz., NBCUTOFF and ELCUTOFF). The parameters of the grid are controlled using a number of keywords: GRIDDIM, GRIDMAXGPNB, and GRIDMAXRSNB. If the shared memory (OpenMP) parallelization is used, the performance of grid-based cutoffs is hampered if residues are reassigned frequently, which happens in many Monte Carlo calculations (all trial moves matter, not just the accepted ones). This is because the global copy of the grid association must be kept in sync.
   
4. The last available option instructs CAMPARI to employ topology-assisted cutoffs, which is currently the default. Here, interatomic distances are simply pre-screened by a master value for the two reference atoms of residue pairs. This takes advantage of molecular topology to simplify the generation of spatial neighbor lists since only residues which pass the pre-screen are assumed to be spatial neighbors. Note that the program will compare the distance between the two reference atoms to the sum of the cutoff and the effective radii of the two residues in questions. These radii are currently hard-coded. This mode is the method of choice for systems with heterogeneous density and/or large (many atoms) but relatively few (<1000) residues. Note that in the presence of non-bonded interactions method 3 reduces the scaling of CPU time with system size from N² to something considerably faster (where N is the number of atoms). Method 4 does not change the scaling behavior but reduces the constant factor for this cost dramatically (by experience, for a water box of ~1000 molecules, mode 4 is still slightly faster). This option should generally perform well in conjunction with the shared memory (OpenMP) parallelization of CAMPARI.

Note that the structure of neighbor lists differs. In gradient-based calculations (→ DYNAMICS), they are residue-based. In Monte Carlo calculations they reflect the incremental energy calculation necessary and are explicit pair lists. There is always an overhead in managing interaction lists when the shared memory (OpenMP) parallelization is in use.

NBCUTOFF

If cutoffs of nonbonded interactions have been requested, this keyword sets the interaction range for a part of the nonbonded interactions. It is interpreted differently dependent on the type of calculation:

1. For Monte Carlo calculations (see DYNAMICS), it simply sets the non-bonded (IPP, ATTLJ, WCA, and IMPSOLV) cutoff in Å. Neighbor lists are populated based on this value, and exact truncation is performed unless keyword MCCUTMODE is set differently from the default value of 1. All the potentials governed by NBCUTOFF should conceptually be short-range in nature. For WCA and the calculation of solvent-accessible volumes for the ABSINTH DMFI, users should choose values that are guaranteed to comply with the intrinsic cutoffs of these methods, which are parameter-dependent (see parameter file and keyword WCA_CUT). For ATTLJ, it must be noted that the properties of systems of heterogeneous density can depend significantly on the truncation of 6^th power dispersive term. This affects, for example, simulations of polymers in implicit solvent. In these cases, both the cutoff value and the choice for MCCUTMODE are important parameters of the Hamiltonian.
2. For gradient-based calculations, NBCUTOFF defines the short-range regime, within which all interactions and forces are guaranteed to be computed at every time step. This is complementary to the choice for ELCUTOFF. If these two cutoffs are not the same, they form a twin-range pair with some interactions being recomputed only every NBL_UP steps. It is important to realize that the neighbor lists underlying these types of cutoffs are residue-based. They are buffered in order to fulfil the aforementioned guarantee, and the buffer values depend on residue size. This means that the true interaction range can be considerably larger than the value specified (unless the simulation involves only monoatomic molecules). For certain Hamiltonians, CAMPARI supports having the same exact truncation scheme that is the default for Monte Carlo runs (see MCCUTMODE). In this framework, excluding simulations of single atoms, any usefulness of a twin-range approach to the cutoffs is largely eliminated, and this is because of the buffering.

Note that because of the differences in interpretation, hybrid MC/MD calculations (→ DYNAMICS) are mutually consistent only with a subset of possible choices, i.e., by setting NBCUTOFF and ELCUTOFF to the same value. Furthermore, MCCUTMODE has to be 2 in dynamics runs and for certain Hamiltonians (standard gas-phase Hamiltonians and variants) because of limitations of some of the specialized inner loop codes.

ELCUTOFF

If cutoffs of nonbonded interaction have been requested, this keyword sets the interaction range for the remainder of the nonbonded interactions (not covered by keyword NBCUTOFF). It is interpreted differently depending on the type of calculation:

1. For MC calculations (see DYNAMICS), it simply sets the second nonbonded (TABUL and POLAR) cutoff in Å. All the potentials governed by ELCUTOFF are potentially long-range in nature. It is up to the user to ensure that tabulated potentials can be truncated safely in the distance regime set by ELCUTOFF. Importantly, the terms supported in a Monte Carlo run and governed by this cutoff are never truncated exactly at the cutoff distance. Such an exact truncation leads to severe cutoff artifacts due to imbalances in evaluating dipole-dipole interactions between groups of partial charges as part of Coulomb terms. This is also the reason why CAMPARI will complain if the partial charges in a residue do not add up to an integer value. Note that even interactions beyond the buffered second cutoff may be computed: Coulomb terms involving moieties flagged as carrying a net charge may not be subjected to any cutoffs based on the chosen setting for LREL_MC.
2. For gradient-based calculations, it defines the mid-range regime, within which all interactions and forces are computed accurately, but only every n^th time step, i.e., at a lower frequency which is set by the neighbor list update frequency (see keyword NBL_UP). As for the Monte Carlo case above, exact truncation does not happen with one prominent exception, i.e., Coulomb terms in conjunction with a reaction-field treatment where the truncation is necessary. Other options for LREL_MD may, like for LREL_MC, lead to interactions being computed even when they are not in the neighbor lists based upon the value of ELCUTOFF. If the values for NBCUTOFF and ELCUTOFF are not the same, the twin-range terms are assumed to be approximately constant for the number of steps between neighbor list updates. Twin-range cutoffs are explicitly disallowed for the Ewald and reaction-field methods. If CAMPARI computes additional interactions, i.e., if LREL_MD is either 4 or 5, these interactions are subjected to the same assumption for forces and energies (residues pairs with distances beyond the buffered cutoff).

Note that because of the differences in interpretation, hybrid calculations (→ DYNAMICS) are mutually consistent only with a subset of possible choices, i.e., by setting ELCUTOFF to the same value as NBCUTOFF. For clarity, it is emphasized again here that the long-range interactions covered by this keyword are never truncated exactly (with the exception of the reaction-field method available in dynamics) but rely on a residue-level parsing (buffered neighbor lists), i.e., there is no equivalent of keyword MCCUTMODE for these interactions. This ensures that cutoff artifacts due to breaking neutral groups (→ POLTOL) are avoided, but it does increase the effective interaction range (based on the buffer sizes, which are calculated from the effective residue radii).

MCCUTMODE

When using nonbonded interaction potentials in conjunction with cutoffs, Monte Carlo calculations typically truncate short-range interactions (IPP, ATTLJ, WCA, and solvent-accessible volume calculations for the ABSINTH DMFI) exactly at the cutoff distance. The latter two terms have intrinsic cutoffs, and the choice for NBCUTOFF should be consistent with these intrinsic limits. This is not true for IPP and ATTLJ. In particular for the latter, if the system has inhomogeneous density, the properties of the system can depend significantly on the truncation scheme. In gradient-based calculations, the cutoff on short-range terms is, by default, always used exclusively to populate the corresponding neighbor lists. This means that no exact truncation occurs. Clearly, these two settings are not identical except for pairs of single atom residues. Because of this, keyword MCCUTMODE offers the following two options:

1. Favor exact truncation. This is the default and will apply, without limitations to pure Monte Carlo calculations. For other choices for keyword DYNAMICS, only limited supported is available. A hybrid sampler with the Hamiltonian where exact truncation cannot be achieved (due to code-internal reasons), will terminate CAMPARI with an error. A pure gradient-based calculation may see the choice for MCCUTMODE be changed (a warning is printed).
2. Avoid exact truncation. This is the more general setting and is supported for all Hamiltonians. By choosing a pure residue-level exclusion approach, many more interactions tend to be computed for the biopolymers supported in CAMPARI. This is because of the large buffer radii in use. This option can be used to safely achieve exactly the same Hamiltonian in hybrid MC/MD calculations or for gradient testing.

User should keep in mind that the choice for MCCUTMODE can be (but need not be) important. For example, in a dense, homogeneous fluid, the exact truncation scheme for the dispersion term is known to be largely irrelevant for solution structure.

NBL_UP

This keyword provides the update frequency for neighbor lists in gradient-based calculations. Every NBL_UP^th step, it is recalculated which residues are within a distance of NBCUTOFF Å (short-range) and which ones are within a distance of ELCUTOFF Å (mid-range). Interactions with the former are computed at every time step explicitly and those with the latter are computed only every NBL_UP^th step explicitly. For interactions outside of either cutoff, truncation occurs unless the electrostatic model chosen provides a long-range term (see LREL_MD). These latter interactions will then be recomputed at the same frequency as the mid-range ones (with the exception of the reciprocal space sum in Ewald methods which is always computed at every step). Note that this keyword is irrelevant if CUTOFFMODE is set to 1, a setting useful only for debugging purposes.
The assumptions made by this keyword are rather aggressive, and it is therefore recommended to use it with caution. Specifically, the neighbor lists here should not be thought of as "buffered" in any way. The integrator noise accumulating by setting this to something large can be quite substantial, and should probably be offset by a large choice for the outer cutoff distance (→ ELCUTOFF). Conversely, the use of residue-level neighbor list with large effective radii tends to bloat the effective cutoff radius, which creates something akin to an effective buffer zone. This implementation may be changed in the future.

LREL_MC

This keyword determines CAMPARI's method of handling long-range electrostatic interactions in MC calculations. There are currently several options for this with more being added in the future. A general problem is hidden in the fact that MC calculations have to be able to compute relative energies of drastically different configurations at every step such that similarity assumptions cannot be used to speed up the calculations as is the case in MD/LD/BD.

1. All monopole-dipole and monopole-monopole interactions are computed explicitly (at full atomic resolution). By default, the governing factor is the parser for the partial charge sets which determines the individual charge groups (see option 2 for ELECMODEL and output files DIPOLE_GROUPS.vmd and MONOPOLES.vmd). Those with a total charge exceeding a threshold (usually zero) are considered "net charges", and those without are considered "dipoles". The flagging is at the residue level, and can be overwritten by a dedicated patch facility. Interactions between dipole groups are skipped even if one or both of the participating residues are flagged. For large systems, the number of interactions can grow dramatically of course. Using this option also requires allocation of a potentially large matrix if grid-based cutoffs are in use, which can hamper parallel performance.
2. All monopole-monopole interactions are computed explicitly (at full atomic resolution). As in the option above, the flagging is at the residue level, and here both residues are required to be flagged. Dipole-dipole and dipole-monopole interactions are skipped even if both of the participating residues are flagged. For plasmas or ionic liquids or concentrated ionic solutions, the number of interactions can become prohibitively large of course. It also requires allocation of a potentially large matrix if grid-based cutoffs is in use, which can hamper parallel performance.
3. This is identical to the previous option except that monopole-monopole terms are computed at a reduced resolution, viz., polyatomic monopole groups are represented by collapsing the total charge onto a single atom, which is nearest to the true monopole center. This choice is currently the default. The same caveats as for option 2 apply.
4. No additional interactions are computed (rigorous truncation).

Note that for systems having no residues that are flagged as carrying a net charge this keyword is irrelevant. Note also that none of the approaches is rigorously feasible for a system in which the dielectric response of the system is primarily described by explicitly represented dipolar units (such as a calculation in explicit water) if charges are present. The reason is that dipole-dipole terms and in particular monopole-dipole terms are crucial in modelling the dielectric response, and options like 2 or 3 above will hence generate a dielectric mismatch outside of the second cutoff. For straight truncation (option 4), drastic artifacts are observed in which density of like-charged species accumulates just outside of the second cutoff (ELCUTOFF). Conversely, for 1), 2) or 3) above, inverted artifacts are observed in which like-charged species accumulate inside the cutoff sphere and form favorable long-range interactions with other quasi-macroions (charge separation occurs). Such problems usually disappear if there is no dipolar fluid exerting a dielectric response (such as in a plasma) or if the dielectric response is exerted through a continuum.
Note that periodic boundary conditions are mutually inconsistent with any of the above treatments with the exception of truncation. This is because in PBC the largest effective cutoff value for nonbonded interactions must not exceed half of the smallest linear dimension of the box. In case of a hybrid sampler, the values for LREL_MC and LREL_MD should be matched to achieve a consistent Hamiltonian. Compatible values are 1/5 and 3/4, and 4/1 (LREL_MC/LREL_MD).

LREL_MD

Much like LREL_MC, this keyword controls how CAMPARI handles long-range electrostatic interactions in gradient-based calculations calculations. There are currently several options for this which are generally different from those available for Monte Carlo runs since two core assumptions are true for dynamics calculations; i) only global energy/force evaluations are needed; and ii) the system remains self-similar through several integration steps. The options are as follows:

1. No additional interactions are computed, i.e., everything beyond the mid-range cutoff is discarded. This setting can be used along with LREL_MC set to 4 and ELCUTOFF being equal to NBCUTOFF to create an exact match between dynamics and MC Hamiltonians which may be relevant for hybrid calculations (→ DYNAMICS).
2. Ewald summation is used, which relies on periodic boundary conditions,and (currently) cubic boxes (→ BOUNDARY and SHAPE). This technique relies on the decomposition of an infinite sum over all periodic images into two quickly convergent contributions, a real-space and a reciprocal space part. The real-space part involves a modified Coulomb interaction, which therefore requires separate loops. Hence, support for Ewald sums is currently limited to "gas-phase"-type calculations with nonbonded interactions corresponding to Lennard-Jones and polar interactions only. Even though possible in theory, there is currently no support for the ghosting of interactions, which is used in the context of free energy calculations. The reciprocal space part can be solved in a number of different ways (see EWALD and associated keywords). Note that the two cutoffs are collapsed into the shorter one (there is no mid-range regime) when using Ewald techniques. Both the real-space and the reciprocal sums are recomputed at every step. Ewald summation replaces the standard Coulomb term and is relevant for all polar interactions even in the absence of full charges. It always requires the error function and a tabulated approximation exists in case the built-in variant is too slow (see installation instructions → DISABLE_ERFTAB and keyword EWERFTOL).
3. The (generalized) reaction-field correction is used. The mode is picked with keyword RFMODE. This involves a modified Coulomb sum and relies on the assumption that truncation can be dealt with by assuming that a low dielectric cutoff sphere is embedded in a high dielectric medium, which gives rise to a reaction-field correction, which lets the force on a charge vanish at the cutoff distance if the difference in dielectric constants is large. The high dielectric is set with keyword IMPDIEL, and the size of the cutoff sphere is given by ELCUTOFF. This method requires modified Coulomb interactions and support for the type of nonbonded interactions is limited similar to Ewald sums except that the ghosting of interactions is supported for net neutral solutes. Note that reaction-field corrections assume dielectric homogeneity, i.e., the underlying theory breaks down if the effective dielectric inside or outside the cutoff sphere might become inhomogeneous. The latter is always the case, if, for example, a large enough macromolecule is present or if the system is non-periodic. Note that algorithmically this is not a long-range correction and that (G)RF-corrected terms are computed with the same frequency as short- and mid-range terms are (see NBCUTOFF and ELCUTOFF). Due to stability issues, twin-range cutoffs are not allowed for reaction-field methods. Even then, the force discontinuity at the cutoff distance (vanishes only if the dielectric is assumed to be infinite) may cause more noise than a simple truncation scheme (option 1). The reaction-field solution replaces the standard Coulomb term, i.e., it is relevant for all polar interactions even in the absence of full charges.
4. The same option as 3) in LREL_MC. The same rules and caveats apply. By matching the methods this way and setting the two cutoff criteria equal to one another, this allows a consistent choice of Hamiltonian in hybrid runs (→ DYNAMICS). This option is currently the default choice.
5. The same option as 1) in LREL_MC. The same rules and caveats apply. By matching the methods this way and setting the two cutoff criteria equal to one another, this allows a consistent choice of Hamiltonian in hybrid runs (→ DYNAMICS).

Note that periodic boundary conditions are mutually inconsistent with the above options 4 and 5 because in PBC the largest effective cutoff value for nonbonded interactions must not exceed half of the smallest linear dimension of the box.

GRIDDIM

If grid-based cutoffs are in use (→ CUTOFFMODE), this keyword allows the user to specify the three integers determining the x,y,z dimensions for the rectangular cutoff grid. The origin and the size of the grid are determined by the box parameters (see BOUNDARY and SHAPE). In a droplet boundary condition, the grid cannot be aligned with the simulation container exactly, and parts of it are wasteful. The extra buffer space is computed automatically, and this may lead to crashes of CAMPARI complaining that a part of the system is "off the grid". This most often occurs with an unstable (exploding) simulation but can also happen if a residue-based boundary condition is used in conjunction with bulky residues or if the restraining force is very small.
The total number of grid points should not be so large that operations scaling linearly with this number become a contribution of significant computational cost. Setting the size of the grid cells equal to the cutoff is typically not an effective strategy due to the requirement of having large margins. The latter are a result of the residue-based grid association CAMPARI uses which requires accounting for the effective residue radii in determining spatial neighbor relationships via the grid.

GRIDMAXRSNB

If grid-based cutoffs are in use (→ CUTOFFMODE), this keyword allows the user to specify an initial limit for the maximum number of residues associated with a single grid point. Arrays are dynamically re-sized during the simulation but if the initial setup fails already, an error is returned (see also GRIDMAXGPNB). This keyword is required mostly so CAMPARI has a realistic estimate of the required memory at the beginning.

GRIDMAXGPNB

If grid-based cutoffs are in use (→ CUTOFFMODE), static grid-point neighbor lists are set up initially and used to simplify the generation of neighbor-lists using the grid. This keyword specifies the maximum number of grid-point neighbors each grid-point may possess. If the number is too small, the program will fail during the initial setup. This is again to avoid inadvertent memory emergencies (as for GRIDMAXRSNB).
It can be annoying to find an acceptable value for this keyword as the distance range depends on the system and the grid. For a big system, it may be advisable to use a temporary sequence file with just the largest residue present to speed up the remainder of the initial setup. Once a proper value has been found for GRIDMAXGPNB, the real sequence can be restored and GRIDMAXRSNB can be calculated relatively easily.

GRIDREPORT

If grid-based cutoffs are in use (→ CUTOFFMODE), this simple logical instructs CAMPARI to write out a summary of the initial grid occupation statistics.

CHECKFREQ

This keyword is interpreted differently dependent on the type of calculation. In pure gradient-based simulations, CHECKFREQ simply sets the interval for how often to report global ensemble variables to log output. This can be useful to track simulation progress and make sure that no unexpected behavior (instability) occurs. This output overlaps with output file ENSEMBLE.dat. There is no significant cost incurred by this reporting as the relevant numbers have been computed anyway. In trajectory analysis runs, CHECKFREQ is ignored. For monitoring the progress of processing large input data sets, keyword FLUSHTIME can be used instead.
CHECKFREQ takes on a more important role in Monte Carlo calculations or the MC stretches of hybrid sampling runs. Here, it specifies the interval (in elementary steps) how often to recompute the total energy globally. This number is compared to the incremental energy obtained from the energy updates for individual MC moves (which do not compute the global nonbonded energy). The global value supersedes the incremental one (i.e., it is a reset). The numerical drift error from the incremental calculations is usually very small. Thus, the reference energy can be chosen to be either the same as what propagates the Markov chain (affected by keyword CUTOFFMODE and all associated choices) or it can be chosen as the N² sum assuming a lack of cutoffs. This is controlled by keyword N2LOOP. The choice of reference energy has no implications for the Markov chain but can (and usually does) affect absolute energy values. This may be relevant for certain free energy calculations, for comparisons of simulation results obtained with different cutoff lengths, etc. Whenever absolute energies need to be comparable, it is best that that N2LOOP is set to zero. If it is not zero and the cutoff-assisted and N² energies differ, the cutoff-sensitive values reported to output file ENERGY.dat will begin to deviate within each interval of CHECKFREQ steps. In this case, consistent output to ENERGY.dat is achievable only if ENOUT is a multiple of CHECKFREQ. The drifting inconsistency in each interval is precisely what was the original motivation of the output, i.e., to understand the magnitude of cutoff effects and to be able to diagnose the correctness of incremental energy calculations. As an additional function, if cutoffs are turned on and N2LOOP has not been set to zero, a sanity check is performed as well, i.e. given the current structure, are the derived interactions in fact complete given the chosen maximum cutoff distance set by ELCUTOFF? If not, this would most likely mean that the parameters used for deriving the list of relevant interactions (specifically, the maximum residue radii) are inappropriate (this can happen for simulations of unsupported residues).
Because both the N² energy evaluation and the cutoff check can be extremely slow for large systems, low frequencies are highly recommended for these cases especially if N2LOOP is not zero.

N2LOOP

This keyword is a simple logical which allows the user control over whether or not to compute the full N²-loop of non-bonded interactions (on by default) as a reference. In pure gradient-based simulations, this number is reported initially only for information purposes but serves no other function. Setting N2LOOP to zero disables this initial calculation, which can be very slow for large systems, in particular as it does not benefit from the OpenMP parallelization. In restarted calculations of this type, N2LOOP never comes into play. In trajectory analysis runs, N2LOOP has no effect even if energies only are calculated (DYNAMICS is 1).
The primary use of N2LOOP is to choose the reference energy in Monte Carlo calculations (see CHECKFREQ). When turned on (default), MC simulations will continuously reset the total energy to the cutoff-free value. When it is turned off (zero), they will reset the total energy to the user-selected cutoff scheme (which can be the same of course → CUTOFFMODE). This happens at regular intervals of CHECKFREQ steps. If N2LOOP is set to zero, it will additionally suppress the sanity check procedure for cutoffs. Note that the Markov chain of MC calculations is unaffected by this keyword (it corresponds to a shift of the arbitrary zero point). In particular in hybrid samplers, N2LOOP should probably be 0 to avoid confusion. It is important to keep in mind that, whatever the context, the N² sum of nonbonded energies may not be a useful reference state, especially in periodic boundary conditions.

USESCREEN

This logical keyword applies to all Monte Carlo elementary moves (except particle deletion moves). The normal sequence of events in CAMPARI is:

1. Perturb configuration.
2. Compute short-range terms for moving parts for new conformation.
3. Compute corresponding long-range terms.
4. Restore original conformation.
5. Compute short-range terms for moving parts for original conformation.
6. Compute corresponding long-range terms.
7. Evaluate Metropolis criterion.
8. Process acceptance or rejection.

Often it will be possible to detect already after step 2 that the new conformation produces a steric clash. Therefore, when USESCREEN is turned on, CAMPARI will build in an energy screen after step 2, which can serve to quickly eliminate those conformations (acceptance probability will often be numerically too small to even be representable in floating-point format). This premature termination of the sequence above is sought to shorten the overall runtime. The height of the screen is set by keyword BARRIER. Note that the above sequence of events is incomplete for certain types of concerted rotation moves.
From the above, it is clear that at step 2 we do not yet have access to a difference in energies (which is only available after step 5). Consequently, this quantity is simply compared to the net value of the short-range energy terms (→ SC_IPP, SC_ATTLJ, SC_WCA, boundary interactions, SC_BONDED_B, SC_BONDED_A, SC_BONDED_I, SC_BONDED_T, SC_EXTRA), and certain bias terms (→ SC_ZSEC, SC_POLY, SC_DSSP, SC_EMICRO, SC_DREST). With the exception of SC_ATTLJ, SC_WCA, SC_BONDED_T, and SC_BONDED_I, these are all strictly penalty terms that can only yield positive contributions to the total energy. Because of the above, the screen is most useful if SC_IPP is used. Inverse power potentials diverge for small distance and can yield arbitrarily large values, which allow meaningful choices for the associated keyword BARRIER. If all aforementioned terms are either zero or negative, the screen will not have any effect. Harmonic potentials (as used in most of the bias terms) can also yield very large values, but the likelihood of this happening during simple MC moves is very small except for SC_DREST, SC_BONDED_B, and SC_BONDED_A (for the latter two terms, this only holds in the presence of soft crosslinks). Therefore, the difficult cases are those, for which the penalty terms are generally high, but do not necessarily vary quickly or strongly upon MC moves. It may then become impossible to use a simplification of this type, i.e., if the chosen screen height is too small, the Markov chain will be corrupted, and if it is made larger, the screen no longer has any effect. To buffer against incorrect use of the method, there is an additional criterion that the incremental energy must exceed twice the total system energy (for typical interaction potentials and an equilibrated system, the latter is often a negative number, and this condition becomes trivially fulfilled).
Note that this technique assumes that the Markov chain remains unperturbed even though the actual acceptance criterion is circumvented. Depending on the setting for BARRIER, this will often be rigorously true for a finite-length simulation. Because the same threshold is used for all types of moves, the efficacy of the screen is likely move type-dependent. Finally, simulations using the Wang-Landau acceptance criterion may not be able to use this technique (a warning is printed in any case).

BARRIER

This keyword is used in two different contexts. First, Monte Carlo moves can take advantage of a cutoff-like screen eliminating proposed conformations after only a partial evaluation of the relevant energy terms. (this is enabled with USESCREEN). Then, BARRIER sets the energy threshold (screen height, cutoff value, barrier) in kcal/mol.
Second, the value of BARRIER in kcal/mol is used as the hard-sphere penetration penalty in the hard-sphere excluded-volume implementation (enabled by setting IPPEXP to a sufficiently large value).

Parallel Settings: MPI (Multi-Copy) Parallelism (Replica exchange (REX), PIGS, and MPI Averaging) and OpenMP Parallelism (Task Decomposition):

---

(back to top)

Preamble (this is not a keyword)

Most biomolecular simulation software packages allow a form of parallelization which one may refer to as domain decomposition. Here, the system is partitioned into a number of subsystems corresponding to the number of processor cores available to the parallel computation. Each core then - more or less - computes only interactions of its own subsystem. The main requirements for an efficient implementation are to keep the communication load as small as possible and the workload even. While for specific classes of systems (dense, truncated interactions, etc.) this method is undoubtedly superior, CAMPARI does not currently implement it. Instead, it offers a general-purpose shared memory parallelization relying on OpenMP. A shared memory parallelization has the advantage of replacing communication calls with conceptually simpler synchronization calls. The shared memory parallelization in CAMPARI is primarily a way to speed up simulation and analysis tasks within the confines of a single machine. Current (2016) compute nodes in supercomputers offer tens of CPU cores, and significant gains can be made for many practically relevant applications. While the OpenMP parallelization is the inner layer of parallelism of CAMPARI, there is also an outer layer that implements sparse communication algorithms such as replica exchange. Like most simulation software, CAMPARI uses the MPI standard for handling the communication requirements of this outer parallelization layer. The resultant hybrid OpenMP/MPI code is particularly well-suited to multi-copy (replica exchange, PIGS) simulations of medium-sized systems.

---

NRTHREADS

This keyword controls the number of threads that the workload of the calculation is distributed across. The actual value is respected only if the pure OpenMP-enabled version of CAMPARI is used (campari_threads). For the hybrid MPI/OpenMP executable (campari_mpi_threads), the number of threads cannot be set this way in CAMPARI (because it must be known during creation of the MPI universe). Instead, the environment variable OMP_NUM_THREADS should be defined accordingly. The threads parallelization as described next is the same in both cases, so the documentation here is relevant in both cases.
The OpenMP parallelization of CAMPARI is not a domain decomposition in the vein of almost all MPI-parallel decompositions found in molecular dynamics codes. CAMPARI is meant to cover a diverse set of simulations (including those using different samplers or those in implicit solvent). Spatial domain decompositions work well for systems with homogeneous density undergoing global and continuous evolution (which creates workloads that are all large enough and remain comparable across many simulation steps). Conversely, a single Monte Carlo move of a small molecule in a dilute solution of biopolymers and small molecules is not meaningfully addressable by spatial decomposition techniques. Task-based parallelizations are conceptually simpler but offer less scalability (communication/cache/memory issues). Here, the necessary calculations are simply divided at all cost-intensive stages across processes, which usually requires that all parallel processes “see” the entire system. This is suitable for a shared memory (OpenMP) decomposition (although cache and memory issues remain). As in any other parallel implementation, Amdahl's law holds. This is critical if the decomposable workload is very low to begin with as in those cases any nonparallel task will become a bottleneck (performance tapers off). Additionally, synchronization costs increase with increasing number of threads. Consequently, performance reversal will occur for systems with unfavorable size or properties. This is particularly tricky on modern many-core architectures where memory management (cache), task pinning, etc. are all nontrivial or sometimes impossible to analyze and control. The systems that parallelize best in general are those that have high floating point operations (FLOP) counts and can take advantage of blocky memory layouts.
The main “modes” or tasks covered by the shared memory parallelization in CAMPARI are as follows:

1. Global force and energy evaluations. This is the most cost-intensive step in any gradient-based technique implemented in CAMPARI. In general, forces and energies are grouped into terms even though this leads to partial redundancy. For the nonbonded terms, which in general have costs that are conformation-dependent (cutoffs), and a specific group of bonded and other terms loads are balanced dynamically. The limits are usually subsets of atoms, residues, molecules, or residue-residue interactions. Some bias terms have an inner parallelization that is independent of these types of limits, specifically the spatial density potential, the polymeric biasing potential, and custom distance/position restraints.. This is in contrast to other bias and bonded terms, which are occasionally evaluated asynchronously by individual threads.
2. Incremental energy evaluations. Incremental energy calculations account for the bulk of the cost of most Monte Carlo simulations and can differ dramatically in extent from step to step. This is why CAMPARI will compute an explicit distribution of work load onto threads every time. No dynamic balancing occurs. The workload can easily be so low that the scaling limit is reached. To avoid adverse effects for larger numbers of threads, the number of synchronization operations per step is kept small. The fact that no forces need to be computed simplifies both the required synchronization operations and the required data structures considerably. The second point can lessen the negative impact of cache management on performance.
3. Determination of neighbor/interaction lists. Irrespective of the sampler, any scalable simulation on a system of appreciable size featuring nonbonded interactions will require truncation or transformation of these interactions (→ CUTOFFMODE), which in turn necessitates algorithms to identify nearby species efficiently. These algorithms are all parallelized with generally good efficiency.
4. Managing complex constraints.If holonomic constraints are in use, CAMPARI identifies all groups that can be solved independently. This may offer a trivial parallelization across threads. If one or few groups are expected to dominate the cost, CAMPARI evaluates whether these groups are large enough. If so, each of these groups is solved in parallel by all threads, which requires a number of synchronizations proportional to the number of actual SHAKE iterations (only SHAKE is supported for this). Note that with this and similar decompositions, it is currently not supported to use just a subset of the requested threads to define an optimal setting. Instead, either 1 or all threads have to work on such a constraint group. This means that this type of parallelization is sometimes inactivated upon increasing the number of threads further as it is no longer deemed efficient, which can be a limitation. In a similar vein, if Cartesian or internal coordinate space is used in conjunction with a gradient-based sampler, atom-based forces must be redistributed to these degrees of freedom and their effective masses need to be computed. Both of these happen in recursive loops for complex molecules. CAMPARI will again detect whether the sizes of molecules are large enough to warrant "internal" parallelizaiton. If so, each of the eligible molecules is solved in parallel by all threads, which requires synchronization operations proportional to the longest continuous branch in the molecule in question.
5. Coordinate operations for large molecules.When sampling in Cartesian or internal coordinate space with methods that propagate many or all degrees of freedom simultaneously, it will be necessary to globally reconstruct the Cartesian coordinates of the system based on the altered values. This conversion (Z matrix to Cartesian coordinates) scales lienarly with the number of atoms but requires a large number of trigonometric functions and has very high data dependency because it is strictly hierarchical. If required at every step, it can thus become a significant cost factor when the remainder of the rate-limiting computations are parallelized efficiently. Thus, for each molecule deemed large enough, CAMPARI analyzes automatically the hierarchy and creates a parallel procedure for solving this problem with a fixed number of threads that can be less than the total available number. As such, this is one of only two fully supported feature that can require nested OpenMP parallelism. As a result, performance is harder to control (see comments below for FFTW). Conversely, other coordinate operations such as the simple propagation in Cartesian dynamics, or simple translations by a single vector are straightforwardly parallelized.
6. Threaded computation of fast Fourier transforms with FFTW.Unlike all other libraries linked by CAMPARI (e.g., NetCDF or HSL), the code looks for and uses explicitly the threaded implementation of the FFTW library. Because of the way the interface works, this involves creating a new team of threads from the parallel CAMPARI execution, i.e., it entails nested parallelism. Because the other threads of the original team are idle during FFTW calls (but not destroyed), performance is harder to control and predict, i.e., it depends on the way the kernel, compiler, and custom runtime environment end up distributing threads onto the available resources. This is why keyword THREADS_TEST also enables a performance test for threaded FFTW execution (if available and in use). This can be used to understand better the influence of environment variables like "OMP_WAIT_POLICY" or "OMP_PROC_BIND" on FFTW performance inside CAMPARI.
7. A number of required utility operations required at every step of a calculation. Especially in gradient-based calculations, there are a number of simple tasks to complete that depend on atomic coordinates of the entire system. These include the actual coordinate propagation (whether Cartesian or internal), the correction of drift velocities, the calculation of total kinetic energies, or the management of polymeric descriptors and reference frames (center of mass, etc.). The overall cost of all of these is linear with the total number of atoms. Synchronization requirements occur if a molecular property like the center of mass needs to be computed by multiple threads (the necessity to do so is detected automatically) but they are generally low. In Monte Carlo calculations, quaternion-based parallelizations of pivot-type moves occur in many move types along with repeated copy operations on coordinate arrays. Most of these operations for any sampler have a low cost to begin with and are thus limited in scalability unless the systems get larger. They differ from the holonomic constraint handler or the coordinate operations in that they should simply plateau in parallel performance with increasing numbers of threads (rather than become slower again). This is because of the low (but nonzero) synchronization requirements.
8. Simple analysis tasks. At every step of any run (exceptions caused by the use of FRAMESFILE aside), CAMPARI evokes a high-level routine that goes over all possible analysis tasks, evaluates whether they need to be performed at that step (depending on the output and calculation frequencies listed elsewhere), and executes the identified ones. The majority of tasks are not worthwhile to be handled by multiple threads at once, so CAMPARI uses a task parallelization using a large "SECTIONS" construct. This means that it is beneficial for the parallel efficiency of these analyses if the calculation/output frequencies are matched with each other. Conversely, it is inefficient to enter the function with multiple threads with only a single simple task to be performed.
9. Specific analysis tasks. Some analysis tasks, which are inherently expensive, have been parallelized specifically to be handled by all threads at once. This includes the calculation of spatial densities, overlap metrics in hybrid MPI/OpenMP multi-copy simulations (as they rely on global energy evaluations), and a number of tasks that are part of the structural clustering utility evoked during post-processing. Specifically, the tree-based clustering, the approximate progress index, and iterative algorithms in graph processing (see CADDLINKMODE, CREWEIGHT, and CMSMCFEP) have been OpenMP-parallelized. Other tasks could, due to their unfavorable scaling with system size, benefit from this type of parallelization, and they may be implemented in the future, e.g., parallel contact, DSSP, or scattering analyses.

A few more comments are needed. First, the OpenMP parallelization does not extend to all parts of CAMPARI. In particular, the initial setup and final clean-up are completely serial with no thread awareness whatsoever (the only exception to this rule is the force-based relaxation procedure). This comment extends to the (highly repetitive) setup work required over and over again in a small molecule screen. Some of the procedures performed during setup, for example, initial structure randomization, can be time-consuming, and it is a limitation that they cannot be accelerated. Second, it is always recommended to get a quick estimate of parallel efficiency by timing the code (keyword FLUSHTIME can be used to force frequent production rate estimates). Note that some calculations have inherently heterogeneous production rates, e.g., hybrid dynamics/Monte Carlo calculations. Third, task decomposition by threads generally changes the order in which individual summands are combined to yield net properties like the total force acting on an atom. Because floating point math is not associative, this leads to a generally lower level of exact reproducibility compared to multiple executions of 100% serial code. For large sums, a multi-threaded calculation will generally be more precise. The loss in reproducibility is generally smaller than the loss of reproducibility across architectures and, especially, compilers (which often has fundamentally the same reasons).

THREADS_DLB_FREQ

If the shared memory (OpenMP) parallelization of CAMPARI is in use, this keyword determines after how many steps dynamic load balancing is periodically enabled. Dynamic load balancing conservatively shifts bounds on internal entities of representation (such as atoms, molecules, degrees of freedom) between adjacent threads to improve the balance of times spent per thread. It is important to realize that embedded synchronization requirements destroy the ability to meaningfully measure load balance, which means that dynamic balancing is only performed for synchronization-free subtasks (of which there are several, e.g., evaluation of nonbonded forces or neighbor list generation). It does so for at most THREADS_DLB_STOP elementary simulation steps after the start of each interval.
In detail, this means that every THREADS_DLB_FREQ steps a new data collection and balancing interval is started and continued for up to THREADS_DLB_STOP elementary steps. The information used for balancing can be pre-averaged across multiple steps using keyword THREADS_DLB_EXT. For each block, if satisfactory balance is achieved, the balancing will stop until the next interval is encountered. For small systems in particular, some subtasks will not be able to achieve a satisfactory balance (insufficient granularity). If in these cases THREADS_DLB_STOP is equal to or larger than THREADS_DLB_FREQ, continuous load balancing is obtained. This is not recommended because the measurements themselves are not completely cost-free, and because a continuous adjustment of bounds is likely to yield inferior cache performance.
There are two notes of caution. First, the idea of dynamic load balancing implies that the load does not change dramatically from step to step. This may be violated in trajectory analysis runs where OpenMP is used to compute energies. Splitting the trajectories and running an MPI-parallel analysisis likely to be a superior strategy here. Second, dynamic load balancing expects threads to have the same "computing power" available to them at every step. This is not necessarily the case in oversubscribed systems (more threads than CPU cores) where system-induced waiting times occur. It can also happen in undersubscribed (less threads than CPU cores) cases on multi-CPU systems where threads are not pinned to specific cores. This is because the available cache differs depending on how many threads reside on a CPU (socket). These issues are (at least theoretically) controllable at the level of the operating system, for example using environment variables such as OMP_PROC_BIND. In practice, it is very hard to predict performance accurately, and some amount of trial-and-error (benchmarking) is usually needed. In particular, native hyper-threading for Intel chips should be tested as, possibly contrary to expectation, it has proven beneficial in many applications (most likely due to better cache use).

THREADS_DLB_STOP

If the shared memory (OpenMP) parallelization of CAMPARI is in use, this keyword determines the maximum length of each periodic data collection interval for dynamic load balancing. The interval frequency is set by keyword THREADS_DLB_FREQ. Data collection and bounds adjustment is stopped as soon as the load imbalance is satisfactorily small or as soon as the number of elementary passed since the beginning of each interval is equivalent to THREADS_DLB_STOP. Note that generally it is recommended that the chosen value be small in relation to that chosen for THREADS_DLB_FREQ as repeated measurement cycles and bounds adjustments can themselves adversely affect performance.

THREADS_DLB_EXT

If the shared memory (OpenMP) parallelization of CAMPARI is in use, this keyword determines the number of elementary steps over which the execution times per thread are averaged in dynamic load balancing. Choosing a value different from 1, which is the default, can violate the requirement that has to be balanced in every step for performance to be optimal. However, for small systems and certain execution blocks, the measured times can be so small (and noisy) that averaging may be required to balance them effectively. This is the role of this keyword. Note that choosing larger values also limits the rate of convergence for load balance.

THREADS_VERBOSE

If the shared memory (OpenMP) parallelization of CAMPARI is in use, this keyword controls the level of diagnostic output written to a dedicated output file, viz., THREADS.log. Options are as follows:

0. No output is provided.
1. Only timing information (performance and expected time to finish) is written at intervals controlled by keyword FLUSHTIME. This is the default and recommended option for normal usage.
2. In addition to all output produced by the previous options, CAMPARI periodically reports updated bounds resulting from dynamic load balancing in case a reasonable balance is achieved. This is available for different categories. No output is written if the balancing approach fails to find a satisfactory solution after the requested of steps for the current interval. The bounds specify the chunk processed by each threads and can refer to different representation constructs (atoms, residues, dihedral angles, and so on).
3. In addition to all output produced by the previous options, CAMPARI initially reports fixed bounds for operations with predictable cost. These bounds are used in various places, and the information will not be of much use for regular users.
4. In addition to all output produced by the previous options, CAMPARI frequently reports load imbalance measures for any tasks that undergo dynamic load balancing. It is not recommended to use this option outside of specific debugging or optimization tasks as the amount of data written gets very large very quickly. Note also that the significant file I/O can interfere with external performance measurements. The output can highlight aspects of the calculation that fail to become balanced.

Note that the timing information described for option 1 above is written directly to log-output if OpenMP is not in use.

THREADS_TEST

This keyword is primarily for developer use. It instructs CAMPARI to not perform the actual simulation or analysis but to instead test a subset of relevant threaded execution routines relative to their serial counterparts. These tests use the actual system specified by the key-file. The output of the tests is mostly self-explanatory but understanding all of the reported deviations may require some insight into algorithm structure. If the particle-mesh Ewald method is in use, the correctness tests are followed by a scaling test for the linked FFTW library in threaded execution mode. This is a point of concern because the library does not allow an existing parallel region to access it. More details are given elsewhere.

REMC

This logical keyword - when set to 1 - instructs CAMPARI to perform a calculation employing and evolving a number of copies of the system. Unlike for the mutually exclusive keyword MPIAVG, here it is allowed that each replica is evolving under a different condition (e.g., temperature). This covers the replica exchange (RE) method for standard simulations, the dynamic splitting of an input library for a small molecule screen, and parallel analysis runs yielding as many results as there are trajectories. Like all multi-copy (or multi-replica) methods in CAMPARI, the communication between copies is handled by MPI, and it is therefore necessary to use an MPI-enabled executable. The shared memory (OpenMP) parallelization of CAMPARI can be used simultaneously as this inner parallelization layer does not deal with the exchange of information between copies. In hybrid MPI/OpenMP mode, the number of threads is no longer settable by NRTHREADS but has to use an environment variable (OMP_NUM_THREADS) at the system level instead.
For a simulation task, REMC activates the replica exchange method employing REPLICAS separate conditions (processes). The conditions differ in one or more parameters (→ REDIM), and there is a dedicated input file FMCSC_REFILE to specify them. Note that the order of conditions may matter (→ RENBMODE). Irrespective of whether the underlying propagator is pure Monte Carlo (see DYNAMICS), a dynamics-based method, or any hybrid method, restrictions apply in that the sampled ensemble must be the canonical (NVT) one (see ENSEMBLE). This can either be achieved by running constant particle number MC, Newtonian dynamics with a proper thermostat (see TSTAT), or stochastic (Langevin) dynamics (which inherently tempers the ensemble). In the RE method, structures (or conditions) are exchanged periodically between replicas using a well-defined acceptance criterion. This is controlled by keyword REFREQ and includes the case of disabling these exchanges altogether. The exchanges are generally meant to improve sampling by allowing excursions into conditions or Hamiltonians in which (enthalpic) barriers are reduced. The evaluation of the acceptance probability implies that energies of current structures must be computed for different conditions. Independently of any exchanges, this functionality is useful in free energy calculations (perturbations) as the exponential average of the work required to change condition (energy difference) is directly related to the free energy difference between those conditions (→ REOLCALC). Parameters of the method are the exchange frequency (REFREQ) the scope for possible exchange partners (RENBMODE), the number of exchange attempts in a single exchange cycle (RESWAPS), and for dynamics propagators the way of dealing with velocities upon a successful exchange (RE_VELMODE).
In CAMPARI, each replica and its output will correspond to both instantaneous and averaged information from the associated condition, i.e., the underlying trajectory is no longer continuous in conformational terms. The typical assumption is that, depending on the settings for the parameters of the method and given a suitable arrangement of replicas in the RE input file, it can be achieved that the resultant ensemble averages and distributions are, for finite samples, indistinguishable within error from a correct reference simulation for the same condition that does not utilize exchange moves. This issue is not trivial, however, and the more general and precise approach to the analysis of replica exchange data is to reweight all samples to a given target condition that should either have been part of the original replica space or that can be obtained by interpolation. This reweighting is technically possible in CAMPARI (→ FRAMESFILE) for almost all analysis features in trajectory analysis mode, but the weights have to be determined externally (e.g.,, by the weighted histogram analysis method, WHAM).
If a RE run contains Monte Carlo moves, and is combined with the Wang-Landau acceptance criterion, there is a necessary note of caution. Specifically, if WL_MODE is set to 1, this may result in identical copies of Wang-Landau runs if the exchanged parameters do not alter the Hamiltonian (since environmental conditions are irrelevant to the Wang-Landau sampler in such a case). In any case, the Wang-Landau iterations will proceed independently for each replica. This implies that it may yield results that are difficult to interpret if replica-exchange swap moves are allowed (because those - currently - always follow a Boltzmann criterion).
In a small molecule screen, the difference in replicas is no longer a difference in Hamiltonian or temperature but a difference in the molecule being sampled. In this mode, exchanges are not allowed, the replica exchange input file is not required, and the above comments regarding ensembles, reweighting, etc. do not apply. Importantly, unless keyword MOL2ISSPLIT is turned on, the master process of this MPI setup does not perform any actual calculations; instead, it simply reads the mol2 input file and distributes the molecules in it to the remaining MPI processes. The only exception to this is the (nonsensical) case of there being only a single replica. There is some communication overhead to this procedure, but this is not expected to play a significant role for reasonable ratios of the number of molecules to the number of replicas. It is rare for the cost of the calculation for a single molecule to be so small that the read-in and the distribution of the information from the mol2 file become a significant cost factor. In those cases where it may be significant, CAMPARI also supports the alternative approach of having all MPI processes perform calculations on separate input files (by turning keyword MOL2ISSPLIT on). The downside of this is the loss of automatic load balancing.
If an analysis run is performed, the meaning of keyword REMC changes compared to the case of simulation tasks described above. For analysis, REMC instructs CAMPARI to perform trajectory analysis in parallel while keeping the data from all replicas separate (for parallel analysis runs combining data, see keyword MPIAVG). Example applications are to speed up expensive analyses of large data sets, to compute free energy differences between ensembles, or to obtain data suitable for error estimates via block averaging. Keywords REFILE, REPLICAS, and REDIM are required. All other RE simulation-related keywords are ignored. For the RE setup, analysis keywords REOLCALC, REOLINST, and REOLALL are respected. As alluded to, this can be useful in post-processing simulation data for free energy growth or related calculations requiring "foreign" energies. There is another complication with RE data and that is the question how to evaluate a possible sampling benefit. Users should always keep in mind that a RE trajectory with swaps inherently averages over data from several coupled trajectories. A simple consequence of this is that data tend to look smoother and better converged if the number of replicas is increased. An assessment of the actual purpose of the method, i.e., increased barrier crossing rates by excursions into conditions amenable to barrier crossing, is more feasibly obtained by unscrambling trajectories, i.e., by looking at trajectories continuous in conformation (and not in condition). This is why CAMPARI allows the user to supply an input file with the swap history of a set of trajectories with the goal of transcribing the set of trajectories to a new set that are all continuous in conformation. The input file needs to be similar in format to the analogous output file created by CAMPARI during RE simulations. If this option is enabled, auxiliary keywords RE_TRAJSKIP and RE_TRAJOUT may become relevant.
Technically, parallel trajectory analysis requires that the REPLICAS individual trajectories are systematically named and numbered in a fashion similar to how CAMPARI writes trajectories in RE simulations. This means that every file is prefixed with "N_XXX_", where XXX gives the replica number (started from "000"). Since there is only a single key-file, the input trajectory name specified should not include this prefix (it will be added automatically). An example is given elsewhere. Frame-specific analyses (and thereby frame weights) are not yet supported in parallel trajectory analysis runs.

REFREQ

For any multi-replica simulation that supports structure transfer between replicas, this keyword sets a fixed interval for attempting these structure transfers. It is an important parameter of both the replica exchange method and the PIGS method. Unlike frequencies supplied to define Monte Carlo move sets described above, this parameter is a deterministic interval, i.e., a setting of 10⁴ will imply that possible exchanges are attempted exactly every 10⁴ elementary steps. This is because, in general, the communication requirement will mandate that all replicas remain synchronized regardless. For replica exchange, a swap cycle counts as a single (Monte Carlo) step in the trajectory. For PIGS, the reseeding does not count as a step. Instead, it is performed exactly between the steps corresponding to multiples of REFREQ and the respective next ones (see elsewhere for details).
All structure exchange is implemented in peer-to-peer mode. For generality reasons, the head node is always involved in decision making for structure exchange. This imposes an unfavorable (centralized) communication structure for some data (e.g., reassignment maps).
For replica exchange runs, structure transfer is realized as swaps between conditions. Viewed as a Monte Carlo move, such a swap attempt is defined in the context of a multicanonical ensemble. This means that any analysis should consider the entire set of simulation data and employ appropriate reweighting protocols to obtain canonical averages corresponding to the individual or even interpolated conditions. It is not immediately clear how justified it is to assume that the individual replicas in a replica exchange run can be analyzed as if they satisfied the canonical distribution for each condition individually. For a large fraction of published replica exchange simulations, swap attempts are restricted to the immediate neighbors along a one-dimensional temperature coordinate, and the data coming from replicas are treated independently. Keyword RENBMODE allows the user to choose between neighbor-only and global swap protocols. We emphasize again that CAMPARI does support the computation of reweighted averages and distributions by adding floating-point weights to a frames file.
It is difficult to provide guidelines for useful settings for this keyword. In replica exchange, very small values for this exchange attempt interval can lead to relaxation problems. With dynamics samplers, the treatment of velocities becomes an important consideration (see RE_VELMODE). There is a considerable body of literature on this subject (some of it is cited in this reference).

RESWAPS

If the replica exchange method is in use, this keyword specifies the number of swaps within a swap cycle. Each time a step is encountered that is a multiple of REFREQ CAMPARI will collect the data from all replicas, construct the required energy matrix, and randomly pick pairs of eligible replicas (see RENBMODE) for which the swap move Boltzmann acceptance criterion is evaluated. This process is repeated RESWAPS times and the map matrix (structure to condition) is upated after every successful swap. This means that it is possible for no pairs of replicas to effectively swap structures despite the presence of accepted moves. This stochastic implementation differs from that seen in other software and requires a careful choice for this keyword. For exchanges between all replicas (see RENBMODE), this should probably be at least N_rep·(N_rep-1)/2, where N_rep is the number of replicas in the simulation. For neighbor swaps only, it should be N_rep-1. The reason for choosing a number proportional to or larger than the unique possible exchanges is that the computational cost of computing necessary cross-energies (in Hamiltonian replica exchange) and of communicating the information required for the aforementioned matrix is, in our implementation, independent of the final number of accepted swaps. This means that the cost of a swap cycle would be largely wasted by exchanging just a single pair chosen from a much larger number of replicas. For neighbor swaps, the set of possible swaps is limited because the required energy matrix is only a tridiagonal band matrix. This means that "secondary" swaps may be rejected due to lack of information rather than the Boltzmann criterion, which can introduce biases.
Note that the acceptance rates become very small once there is hardly any overlap between different replicas (in turn, the acceptance is always strictly unity if the conditions are the same - regardless of the two structures). A large number of attempted swaps in conjunction with all-against-all exchange corresponds to an equilibration of current structures across conditions. In the limit of tiny acceptance rates, the impact of the replica exchange method is no longer felt, and it reduces to a set of independent canonical simulations at different conditions (the same limit is achieved explicitly by setting REFREQ to be very large). Because of this, a reasonable swap acceptance rate is often taken as the primary diagnostic toolfor the choice of conditions (see output file for swap probabilities).

REFILE

This keyword defines location and name of the file containing the specifications for the replica exchange method (see elsewhere for details).

RENBMODE

As alluded to above, the replica exchange method represents a rigorous sampling technique if one considers the multicanonical ensemble it defines. This can cause problems in the interpretation of data obtained for an individual condition. Moreover, the energetic overlap between distant conditions is often small leading to negligible swap likelihood for all but the replicas most similar in condition. This is the typical scenario for temperature replica exchange calculations in explicit solvent. Here, it is very common to restrict swap attempts to the (at most) two neighboring replicas for a series of conditions. In Hamiltonian replica exchange, the same idea might actually be more useful as it also restricts the computation of the energy matrix to neighboring conditions. Recomputing energy values for many different conditions can be costly. Therefore, the available options are:

1. Swaps are attempted with all available replicas
2. Only the (at most two) neighboring replicas are eligible for swap moves, and neighbor relationships are determined by the sequence of conditions as they appear in the input file (this is the default).

The replica exchange moves can be seen as attempts to stochastically distribute structures across conditions according to their energies and a Boltzmann criterion. This attempt is conditional upon the spectrum of energies available. The spectrum of energies is changed exclusively by the base sampler and associated with a relexation time scale. This creates a possible race condition with the setting for REFREQ. The exchange pattern defined by RENBMODE influences this rate of structure exchange. Choosing neighbor-only exchange often gives quantifiable biases in the terminal replicas. Beyond that, it is the simpler and computationally more efficient choice that is also more compliant with standard literature practice.
Note that almost all exchange-related problems naturally disappear in the limit of few attempted swaps (→ REFREQ) or in the limit of poor overlap and consequently few accepted swaps. This limit is very easily reached for large, condensed-phase system with typical interaction potentials (fluctuations decrease with increasing size).

REPLICAS

This keyword sets the number of subprocesses intended to be created by a multi-copy simulation. For replica exchange calculations, this has to rigorously correspond to the number of processes granted by the system. A large enough number of different conditions in the corresponding input file (→ FMCSC_REFILE) has to be present. For MPI averaging calculations, which includes PIGS runs and parallel Wang-Landau runs, this keyword will actually be overridden by the actual processor number granted by the system. Note that if the shared memory (OpenMP) parallelization of CAMPARI is also used (hybrid OpenMP/MPI), the management of access to hardware resources (compute cores) by both MPI processes and their spawned OpenMP threads is not trivial on modern many-core CPUs. For example, a machine with two sockets with a 12-core CPU each can host a calculation with 4 MPI processes using 6 OpenMP threads each in many different ways including nonsensical mappings like running everything on a single core. While this mapping can often be controlled by the user at both levels, it should really be managed automatically by the operating environment whenever possible.

REDIM

If the replica exchange method is in use (→ REMC), this keyword sets the number of dimensions specifying the conditions to be expected in the dedicated input file (→ FMCSC_REFILE). Note that replica exchange calculations may rely on neighbor relations (see RENBMODE), and that those may be difficult to define if multiple dimensions are used to specify each condition.

REMC_DOXYZ

For any multi-replica simulation that uses pure MC sampling and supports structure transfer between replicas, this simple logical keyword lets the user choose to use Cartesian rather than torsional/rigid-body coordinates to be transferred. The keyword is ignored if the propagator is fully or partially reliant on a dynamics method. This keyword can be useful if internal degrees of freedom not sampled by MC diverge in any node-specific input files (for example, through rare scenarios when trying to restart an MC run from (modified) restart files produced by MD).

RE_VELMODE

This keyword selects how to deal with velocities for any multi-replica calculation allowing structural transfer between replicas. As such, it is relevant for replica-exchange molecular dynamics runs and for PIGS runs using a molecular dynamics propagator (see DYNAMICS). One of the complications of theses types of calculations arises in the necessity to pass on or re-assign velocities upon any successful structure change. The options for handling this difficulty are as follows:

1. All velocities are always randomly re-assigned upon receiving a new structure. This is equivalent to an instantaneous, global action of an Andersen-type thermostat (see TSTAT). It might be the safest option to use for pure Hamiltonian replica-exchange, especially if the Andersen thermostat is used in conjunction with Newtonian dynamics. It is also the required option for PIGS runs with propagators lacking a stochastic component.
2. Velocities are re-scaled by a factor equivalent to (T_i/T_j)^1/2 where T_i is the temperature of the current node, and T_j the temperature of the node the received structure originated from. Note that this does not scale the instantaneous temperature to a specific value, but rather by a specific factor. Unlike the first option, it preserves directions and relative magnitudes of all velocities. This mode relaxes to the third option if temperature is not one of the replica exchange dimensions, or if the run is using the PIGS protocol instead of replica exchange.
3. Velocities are taken directly from the node the incoming structure originated from, i.e., always remain associated with "their" structure. This will almost certainly lead to small artifacts for replica exchange calculations with temperature as one of its dimensions. It is the preferred choice for PIGS runs with stochastic propagators.

RETRACE

This keyword is only relevant in MPI replica exchange or in MPI PIGS (or PIGS analysis) calculations with swaps or reseedings performed. It requests that an instantaneous integer trace is written that allows the user to recapitulate the complete history of structure transfer between replicas. For replica exchange, the trace indicates which condition is (after each swap or reseeding cycle) associated with which initial starting conformation (see N_000_REXTRACE.dat). For PIGS, the trace indicates every reseeding event in an even simpler form (see N_000_PIGSTRACE.dat). For replica exchange, these data can be used to reconstruct trajectories continuous in geometric variables rather than continuous in exchange condition (the latter being the CAMPARI default). This is useful to be able to estimate the sampling enhancement provided by replica exchange in terms of conformational decorrelation or similar metrics. For MPI PIGS calculations, the trace can be read in by CAMPARI to recover the structural connectivity of configurations in graph-related analyses.

MPIAVG

This logical keyword - when set to 1 - instructs CAMPARI to perform a calculation employing and evolving a number of copies of the system. Unlike for the mutually exclusive keyword REMC, here it is assumed that each replica is evolving under exactly the same condition. Note that keyword REPLICAS is no longer used to set the number of copies (the value is taken directly from the MPI environment instead). Like all multi-copy (or multi-replica) methods in CAMPARI, the communication between copies is handled by MPI, and it is therefore necessary to use an MPI-enabled executable. The shared memory (OpenMP) parallelization of CAMPARI can be used simultaneously as this inner parallelization layer does not deal with the exchange of information between copies. In hybrid MPI/OpenMP mode, the number of threads is no longer settable by NRTHREADS but has to use an environment variable (OMP_NUM_THREADS) at the system level instead.
Additional keywords can activate specific multi-copy methods that utilize a similar framework, viz., parallel Wang-Landau runs (via MC_ACCEPT) and the PIGS protocol (via MPI_PIGS). In detail, the possible tasks are:
MPI averaging
This is the mode achieved without any additional keywords. Here, The individual copies (replicas) are strictly independent (no communication requirement) until the very end when on-the-fly analysis data are automatically collected and processed by the head node (see documentation of output files for details). Some analysis functions or simulation algorithms may not be supported. This is primarily a mode to save time for the user since it essentially reproduces a common mode of running molecular simulations, i.e., running multiple trajectories in parallel and analyzing the results to together. Starting conditions (see RANDOMIZE and PDBFILE) and stochasticity of the propagator are important here to avoid multiple replicas diverging only on account of numerical drift.
Parallel Wang-Landau runs
If the simulation is a pure Monte Carlo simulation , and if the Wang-Landau acceptance criterion is used, the behavior changes. Wang-Landau runs are essentially iterative, and in such a case keyword MPIAVG will create a parallel version of the Wang-Landau scheme. At an interval set by WL_FLATCHECK, the histograms are recombined over the individual nodes. The combined histogram is then what determines the move acceptance and what is used to evaluate whether to update the convergence parameter or not. The value of the convergence parameter and all other relevant settings remain synchronized throughout. In between update steps, the individual replicas evolve according to the last global histogram that was since incremented locally. This means that the value chosen for WL_FLATCHECK is a delicate quantity since both too small and too large values may impede convergence. While the former may remove the bias for an individual replica to traverse phase space faster than a canonical simulation, the latter may result in several replicas exploring the same area of phase space, thereby amplifying a lack of global convergence. Note that the communication routines used in the parallel Wang-Landau implementation can be fine-tuned using keywords MPICOLLS and MPIGRANULESZ.
PIGS runs
PIGS runs are explained in detail below. Here, CAMPARI collects information from all replicas over a specified interval. Rather than biasing the potential energy surface, this information is used to make decisions on whether to truncate some of the trajectories and to restart them from more interesting points corresponding to the current states of other replicas. PIGS stands for Progress Index-Guided Sampling and utilizes information from a method described elsewhere (please refer also to the published articles: progress index; PIGS).
Parallel analysis runs
It is possible to let CAMPARI analyze several trajectories in parallel using either the MPI replica exchange setup or the MPI averaging setup. This is enabled by setting MPI_PIGS to 0 (the default) and PDBANALYZE to 1. For an analysis run in the MPI averaging setup, the behavior is exactly as in an MPI averaging calculation, i.e., data are collected and analyzed by each MPI process and pooled at the end. The results from such a calculation should be the same as the result from a serial analysis of a single long trajectory obtained by concatenating the individual trajectories. Technically, parallel trajectory analysis requires that the REPLICAS individual trajectories are systematically named and numbered in a fashion similar to how CAMPARI writes trajectories in RE simulations. This means that every file is prefixed with "N_XXX_", where XXX gives the replica number (started from "000"). Since there is only a single key-file, the input trajectory name specified should not include this prefix (it will be added automatically). An example is given elsewhere. Frame-specific analyses (and thereby frame weights) are not yet supported in any parallel trajectory analysis runs of this type. For parallel analysis runs using the replica exchange setup, please see above.
Parallel analysis runs emulating a PIGS stretch
This option is identical to the previous one with the single exception that structural clustering and related analyses are not available in their standard form. Instead, CAMPARI will emulate the behavior of the PIGS reseeding heuristic and print out a line of the PIGS trace file. This respects input for keywords MPI_GOODPIGS, RE_TRAJTOTAL, RE_TRAJOUT, and all the required keywords for computing the progress index (starting with CCOLLECT). For details, please consult the documentation on the PIGS simulation method. This mode is enabled by setting MPI_PIGS to 1 and PDBANALYZE to 1.

MPI_PIGS

If a multi-replica simulation is requested via keyword MPIAVG, this keyword allows the user to enable the PIGS enhanced sampling scheme. We refer the user to the literature for a detailed overview. Technically, PIGS utilizes parts of the infrastructure of both replica-based parallel simulation protocols (keywords MPIAVG and REMC as described below). Briefly, PIGS works as follows:
Each of the REPLICAS processes running in parallel propagates a copy of the same system. After an interval of REFREQ steps has elapsed, the algorithm evaluates a heuristic that is used to selectively terminate some of the trajectories and to reseed them from the current states of other replicas. To avoid bit-identical trajectories, the propagator must have a stochastic component to it, e.g., Langevin dynamics, Monte Carlo, or Newtonian molecular dynamics with suitable thermostats. Unlike in replica exchange, the conditions associated with each replica are identical, and swaps would be redundant. The termination and reseeding of trajectories implies a loss of information and is justified only if the reseeding point ultimately leads to better sampling. The notion of "better" is not general. For PIGS, it consists of the desire to diversify individual replicas, e.g., to prevent sampling of overlapping regions of phase space. The truncation and selective reseeding of simulations is used in many methods such as distributed computing or transition path sampling.
To evaluate the heuristic, PIGS collects data from every trajectory over every interval of size REFREQ. To remain scalable, it is a memory-free algorithm, i.e., the slice of data determining the reseeding is always of the same size. From the composite data slice, the so-called progress index is constructed (see option 4 to CMODE). The size of the data slice is therefore set by the combination of keywords REFREQ, CCOLLECT, and REPLICAS (or the actual number of replicas available). Construction of the progress index requires as essential input only the definition of a representation and distance between snapshots, which is provided by CDISTANCE and possibly CFILE. Again, for scalability reasons, the approximate progress index is constructed, and this entails additional parameters of minor importance (see keyword CPROGINDMODE for details).
With the complete progress index in hand, it is possible to locate the current snapshots for all replicas in the index. This requires that REFREQ be a multiple of CCOLLECT. The progress index is an ordered sequence of snapshots that arranges geometrically similar snapshots close to one another without using a reference state. Every snapshot is associated with a specific distance that corresponds to the length of an edge in an underlying spanning tree. From this information, a composite rank of three individual ranks is constructed. The latter are:

1. Position in the progress index (larger is better as snapshots from low likelihood regions are more likely to appear there).
2. Length of the associated edge (larger is better as distances tend to be larger in low likelihood regions).
3. Distance from any other current snapshot in terms of progress index position (larger distances are better as they indicate more unique sampling domains).

From the composite rank (sum of the individual ranks), a specified number of top-ranked replicas is identified and serves as a database for reseeding the remaining replicas. This number is provided as keyword MPI_GOODPIGS. For each of these lower-ranked replicas, one of the MPI_GOODPIGS top-ranked replicas is chosen with uniform probability, and the following expression is evaluated:
p(X → Y) = [ ζ(X)-ζ(Y) ] / (Δζ_max+1)
Here, ζ(X) and ζ(Y) are the composite (summed) ranks for replicas X and Y, respectively. Δζ_max is the maximum realizable difference in composite rank. The result is compared to a uniformly distributed random number between 0 and 1. A reseeding is accepted putatively if this random number is smaller than the evaluated expression, which biases acceptance toward cases with large rank difference. It is only putatively accepted because every replica can be protected on account of a uniqueness criterion. This is evaluated by finding the first and third quartiles of the snapshots coming from the replica in question in terms of progress index position. If they are tightly clustered, the number is small, and it is inferred that this replica samples a relatively unique area of phase space. Conversely, if they are distributed, this indicates sampling overlap. The difference in the positions of the first and third quartiles is compared to the number REFREQ/CCOLLECT, which is twice the minimum value. If it is less than this number, any putative reseeding is rejected for the replica in question.
A positive reseeding decision incurs the same mechanism as that of accepting a new structure in replica exchange. Principally, all required settings and variables for the propagator are transferred. This excludes the seed of the random number generator, i.e., otherwise identical trajectory can diverge quickly on account of the different sequences of random numbers. This is how the stochastic component of the propagator as mentioned above is relevant. For molecular dynamics propagators, velocities can be kept or reassigned, i.e., both meaningful controls supplied by RE_VELMODE are supported. For pure MC propagators, keyword REMC_DOXYZ is also supported. The history of reseeding decisions can be recorded in a trace file. This file is similar to the same output file for the replica exchange method and can be obtained with keyword RETRACE. It is strongly recommended to always write this file for subsequent diagnosis and analysis.
With the exception of structural clustering, on-the-fly data analysis is supported by PIGS in the same way as it is by the default multi-replica (MPI averaging) setup. Data are gathered across replicas, combined, and total averages and distributions are provided. In general, however, PIGS leads to biased distributions, and it may therefore be more useful to adopt a standard protocol that stores trajectories individually for each replica (with MPIAVG_XYZ), disables most on-the-fly analyses, and performs all further analyses strictly in post-processing (with PDBANALYZE).
Structural clustering uses the same infrastructure that PIGS requires to evaluate the heuristic but the data are deleted after each interval of length REFREQ. Note that this implies that the memory requirement of the head node can be large if REFREQ/CCOLLECT and the number of replicas are both large. Scalability of the protocol with respect to the number of replicas requires parallelization of the progress index computation itself, and this is only implemented at the level of the master MPI process thus far. Conversely, the subordinate ranks do nothing but communicate their snapshot to the master instantly after each collection event. Once the data for the entire stretch has been received from all replicas, the shared memory (OpenMP) parallelization of the data mining algorithms comes into play (in a hybrid MPI/OpenMP run). The available OpenMP threads are only those of the master MPI process even if multiple MPI processes reside on the same shared-memory node. Because of these limitations, it is recommended to ensure through appropriate parameter settings that the cost added by the heuristic is kept manageable. Keep in mind that some aspects of the structural clustering facility are not available in the context of the PIGS heuristic. Obviously, CMODE is not selectable, nor are CPROGINDSTART or CPROGINDMODE controllable (they default to 4, -1, and 2, respectively). Keyword CPROGMSTFOLD has no effect (it use would be undesirable in the context of the first ranking criterion mentioned above). All keywords related to editing or utilizing the link structure of the network are irrelevant. Data preprocessing and the utilization of weights are both supported but the application of linear transforms is not (yet). The use of weights can entail a number of associated parameters that reflect or describe a (time) locality in the sequence of snapshots, e.g., a lag time. It is important to keep in mind that the PIGS algorithm simply concatenates the data from all replicas, which can lead to artificial periodicities or spikes in locally estimated fluctuations, which may or may not be desired. Lastly, the technical parameters controlling the tree-based clustering and the short spanning tree construction for the progress index are of course relevant in PIGS (→ CRADIUS, CMAXRAD, BIRCHHEIGHT, BIRCHMULTI, CREFINE, CLEADER, BIRCHCHUNKSZ, CMERGEDIAM, CPROGINDRMAX, CPROGRDEPTH, CPROGRDBTSZ).

MPI_GOODPIGS

This, along with REFREQ, CCOLLECT, and CDISTANCE, is one of the main parameters of the PIGS protocol (see link for details). It determines how many of the parallel replicas are protected from being reseeded and serve as database for the remaining replicas. If MPI_GOODPIGS equals the actual number of replicas (normally set by REPLICAS), the PIGS algorithm relaxes to the propagation of independent, identical copies of the system (basic functionality of MPIAVG). There is no consensus rule for good choices for this parameter, but a reasonable starting point is usually given by setting it to REPLICAS/2.

MPIAVG_XYZ

If the MPI averaging technique is in use (→ MPIAVG), this simple logical keyword lets the user choose to obtain trajectory data for each of the independent, identical replicas separately (which is also the default). If this keyword is explicitly set to zero (logical false), only a single trajectory file will be written with entries cycling not only through the time or equivalent axis but also through replica space (see elsewhere for details). The choice here is mostly a matter of convenience for post-processing but note that with individual trajectories REPLICAS as much structural data are written as with a single file. Lastly note that very frequent write operations by different processes to a shared output file may occasionally cause race conditions and/or be inefficient due to long waiting times.

MPICOLLS

This keyword acts as a simple logical (turned off by default) that allows the user to enable the usage of collective communication routines defined by the MPI standard for selected communication operations in CAMPARI (routines such as MPI_ALLREDUCE, MPI_BCAST, etc). These routines should at all times be functionally equivalent to what CAMPARI would use otherwise, i.e., collective primitives constructed exclusively from blocking send and receive operations (MPI_SEND and MPI_RECV).
The reason for having such a keyword is twofold. First, buggy code in conjunction with these MPI-defined collective communication routines can be difficult to diagnose and debug, because the MPI standard requires an outcome, but not a specific implementation. Essentially, developers and users cannot make any assumptions about the underlying communication flow. In general, this is of course desired (especially from a performance point of view), since it leaves the optimization of said communication to the MPI library rather than forcing the calling program to address these issues. Second, there are enough reports on the web of potentially faulty implementations of these routines in common MPI libraries. In conjunction with additional concerns regarding thread safety, etc, it could prove advantageous to developers to have modifiable implementations in place.

MPIGRANULESZ

If custom CAMPARI routines for collective communications are in use (→ MPICOLLS), and if a calculation is performed that relies on such collective communication operations, this keyword lets the user alter the communication flow structure CAMPARI sets up to handle these cases. The keyword specifies a number of processes, amongst which communication is presumed fast (most often the number of CPU cores on a single board). The communication flow is then set up in a way that minimizes the required communication between such blocks of processes (they are generally assumed to be in sequence and to all be of identical size). This keyword is therefore unlikely to be useful for heterogeneous allocations (different numbers of cores granted on different machines or processes distributed non-sequentially). Between blocks, communication attempts to minimize latency (tree topology), whereas within blocks communication is (currently) strictly hierarchical and sequential with a single head process for each block. This means that (currently) setting MPIGRANULESZ to the number of processes granted by MPI will generate a global hierarchical flow with a single master, whereas setting it to 1 will generate a global tree-like flow.

Output and Analysis:

---

(back to top)

Preamble (this is not a keyword)

Unlike most other simulation software, CAMPARI offers to analyze certain quantities while the simulation is being performed ("on-the-fly"). This has the advantage that the frequency of dumping raw trajectory data to the disk does not have to control the frequency of analyses. This can save time and money by circumventing expensive write operations to disk. Of course, in a typical simulation setting, the user will still want to obtain trajectory data: for visualization, for non-yet-defined analyses, and so on. However, the built-in analyses can still prove beneficial by utilizing as much data as possible. This is generally controlled by several interval settings: analysis X should be performed or instantaneous data Y should be reported every N steps. Such keywords (see for example ANGCALC) are interpreted the same way unless otherwise noted. For example, if ANGCALC is 250 and NRSTEPS is 1000, the analysis would be performed at steps #250, 500, 750, and 1000. There is only one other keyword affecting this: the number of equilibration steps. If in the above example EQUIL is 400, the analysis would only be performed at steps, 500, 750, and 1000 (i.e., the count is always relative to the 0^th step).
Note that some analyses can be costly. Their scaling with system size will usually be stated. At the very end, the log-output will typically report the fraction of CPU time spent performing analysis routines. This may help assess whether some of the frequency settings should be reduced. Simple ways to disable built-in analyses are provided.
CAMPARI often groups statistics together. For example, for a melt of identical polymers, CAMPARI would by default compute only a single histogram of end-to-end distances. This grouping is at times undesired and is overcome by the concept of analysis groups. Unfortunately, the opposite task of grouping information from different species together is currently not supported for such analyses.
For long CAMPARI runs, the instantaneous analysis has the downside that (currently) no intermediate results are produced (everything remains in memory until the very end). In this case, it can be useful to utilize the restart functionality (→ RSTOUT) to produce simulation blocks of equivalent sizes each with complete analysis output files. This strategy also serves to preserve more information in case of unexpected crashes or job terminations. The alternative is to follow the classical route of shifting the entire analysis burden to post-processing by only saving instantaneous trajectory output. As mentioned above, this has the downside of dealing with larger amounts of data and, more importantly, with a loss of coordinate precision (for example, when using the xtc compression library). Another issue that can prove problematic with long runs is that some instantaneous output files (such as the file with running energy terms) are subject to buffered I/O. This depends on compiler and operating and file systems and means information can be lost in case of unclean terminations, which makes it harder to diagnose the error. Keyword FLUSHTIME helps with this problem.
When the shared memory (OpenMP) parallelization is in use, there are a few additional considerations to be taken into account. First, few analyses are per se parallelized (mentioned below for these cases). For the remainder, which are largely inexpensive in terms of CPU time, CAMPARI uses an inhomogeneous and dynamic task parallelization approach at every step. This means that it is beneficial to to make sure that analyses are triggered at the same simulation/trajectory steps. Conversely, if their executions are staggered, i.e., only one or few tasks are executed at a given step, the load distribution across threads by task cannot provide a benefit. Notably, the final processing/printing of results, with the exception of structural clustering does not employ the shared memory parallelization at all. In contrast, it is possible to chop a large trajectory into multiple pieces and to use MPI-parallel trajectory analysis to speed up analyses on large data sets (whether this involves combining the results in the end or not).

---

RSTOUT

This keyword sets the interval specifying how often to write out a restart file. Such a file will allow continuing both crashed and normally terminated runs without losing significant accuracy due to truncation of significant digits (such as in pdb-files). Note that they are not bitwise perfect, however. The concept is described elsewhere. Restart files are written to two files continuously replacing themselves on an alternating schedule such that even if a crash occurs during a write-operation at least one sane restart file should exist. These files are generally named {basename}_1(2).rst. Settings for EQUIL are (of course) irrelevant for this output. Whenever a restart file is written, the system's potential energy is recalculated, which is the only part aided by CAMPARI's shared memory (OpenMP) parallelization.

ANGRPFILE

This keyword sets path and name to the input file for determining analysis groups by custom request rather than by molecule type (→ ANGRPFILE). By default, CAMPARI will often combine collected analysis data for molecules of identical type. This is not always the desired behavior. For example, CAMPARI fails to recognize differences introduced to molecules of the same type by virtue of molecule-specific constraints or biasing potentials. Analysis groups alleviate this and similar problems by allowing to group molecules of identical type into arbitrary analysis groups. Note that it is never possible to combine data for molecules of chemically different type or to split a single molecule into multiple groups (although the latter may be implemented in the future). Systems employing chemical crosslinks (please refer to sequence input for details) pose a special case: here, intermolecular crosslinks do not conjoin two molecules in terms of data structures and analysis, i.e., it will for example (currently) not be possible to obtain the net radius of gyration of two crosslinked polypeptide chains. Instead, both chains will be analyzed and treated as if they were separate molecules.

FLUSHTIME

This keyword determines the desired time interval (in minutes, with the caveat that there is only a single measurement per elementary step) for two things. First, every FLUSHTIME minutes (fractional values are allowed), CAMPARI will report the current production rate (in elementary steps/day) and time to finish. This happens to either log-output (for serial or pure MPI executables) or to a dedicated output file in case the shared memory (OpenMP) parallelization is in use. This performance estimation is bound to be misleading for inhomogeneous calculations where the average cost of a step per time interval can change dramatically (for example, in simulations with hybrid propagators or analysis runs where not all analysis frequencies are 1). Second, CAMPARI will flush the buffers of all instantaneous output files every FLUSHTIME minutes. This can be useful because I/O buffers on a given system may be so large that the information in these files (which are often used to monitor a running simulation) are rarely up-to-date, and that significant data loss can occur upon unexpected terminations.

DISABLE_ANALYSIS

In CAMPARI, many analysis features are turned on by default. This keyword exists to simplify turning them off, for example, when trajectory post-processing is desired, for trial runs, etc. DISABLE_ANALYSIS is processed at the lowest hierarchy level of the key-file parser and, like all other keywords, sequentially for a given hierarchy level. It is not a keyword in the traditional sense since it does not set any CAMPARI-internal variable associated with it to a given value. Instead, it is a shortcut for listing explicitly analysis features with calculation intervals larger than the simulation length. This is exactly what DISABLE_ANALYSIS does: it sets all the affected calculation intervals (see below) like XYZOUT, DSSPCALC, and so on to NRSTEPS + 1.
The options are:

1. All analysis and instantaneous output options are disabled. The only features not affected are the writing of initial and final structure files, the printing to log output (warnings, summary, and some progress information), the log-file for the OpenMP parallelization, the printing of the trace file in certain MPI multi-copy runs, and the writing of restart files. Using this option without other keywords overriding DISABLE_ANALYSIS, a run will not provide much useful information.
2. All analysis options are disabled. This is the same as the previous option only that simple instantaneous output features like energy or trajectory output are not turned off. Instantaneous output relying on a built-in feature are disable implicitly, e.g., running DSSP output.
3. All instantaneous output options are disabled. This is the same as option 1 except that it leaves all built-in analysis features at their defaults (some are disabled by default in any case since they rely on additional information) but disables both simple and dependent instantaneous output features.

Since DISABLE_ANALYSIS is a meta-keyword it is exceptional in that it matters where it is placed in the key-file. As is done in many tutorials, the correct way to place DISABLE_ANALYSIS is after the specification for NRSTEPS and before any calculation interval keywords. Not following this guideline can lead to counterinuitive behavior. For example, a corrupt key-file might have this:

FMCSC_XYZOUT 1000
FMCSC_NRSTEPS 1000000
FMCSC_DISABLE_ANALYSIS 1
FMCSC_NRSTEPS 2000000

This would result in XYZOUT being set to 1000001, which means it is neither the seemingly requested number of 1000 nor is it disabled. Since using DISABLE_ANALYSIS is equivalent to changing the default settings for many analysis features, it usually leads to a shorter key-file than doing this by hand.

ENOUT

This keyword defines the interval how often current potential energy data are written to a file called ENERGY.dat. Note that the total energy is decomposed into the individual terms controllable by keywords of the type SC_XYZ (for example SC_IPP). It is presently not possible to obtain energy decompositions based on subcomponents of the system. The data in ENERGY.dat are the only direct print-out of unperturbed energy values if energy landscape sculpting is in use. Settings for EQUIL are ignored for this output. Note that energies are calculated at every step for every term that is turned on. Energies are never calculated specifically for reporting purposes. This means that ENOUT has no significant associated cost per se and, more importantly, cannot be used to speed up post-processing runs where energy values are required only for selected frames of an input trajectory (the correct way to deal with this situation is to first extract these frames and to then run the energy analysis in a second step).

ENSOUT

By this keyword, the user sets the interval how often to write current ensemble data to a file called ENSEMBLE.dat. This is only relevant if DYNAMICS is not set to 1 or 6 (pure Monte Carlo sampling or minimization). The reported quantities are informative ensemble variables (limited output presently) including - most prominently - potential and kinetic energies. Settings for EQUIL are ignored for this output. As is the case for keyword ENOUT, these values are calculated at every step regardless, and no computation occurs specifically for reporting purposes.

ACCOUT

If pure Monte Carlo or hybrid sampling is used (→ DYNAMICS), this keyword sets the interval how often to report cumulative acceptance data to a file called ACCEPTANCE.dat. Note that these data are mildly informative in that they do not directly allow to compute acceptance rates. They are mostly useful in analyzing a running simulation and assessing the performance of the move set. CAMPARI will report acceptance statistics as well as residue- and molecule-resolved acceptance counts at the very end of the simulation to log-output. The data in ACCEPTANCE.dat are only resolved by move type. Settings for EQUIL are ignored for this output.

TOROUT

This keyword lets the user decide how often to write sets of internal coordinate space degrees of freedom to a file FYC.dat in a one structure-per-line format. These files can easily become large due to the number of degrees of freedom in general scaling linearly with system size. There are two options selected by using a positive (mode 1) or negative integer (mode 2) for TOROUT.

1. Native CAMPARI degrees of freedom are written with a header providing residue-level information. These generally correspond to the unconstrained degrees of freedom in Monte Carlo or torsional dynamics calculations (see sequence input for details). All but rigid-body coordinates are written to FYC.dat and much more information is provided there. Because rigid-body coordinates as missing, the information in the file is never enough to completely reconstruct the system even when assuming the default covalent geometries
2. Sampled, dihedral angle degrees of freedom are written with a header that provides atomic indices corresponding to the various Z-matrix lines describing these dihedral angles. This mode excludes degrees of freedom that are actually frozen, and can include degrees of freedom that are not native to CAMPARI. All values are again written to FYC.dat, and more details are provided there. This mode never includes bond angles and/or dihedral angles that have no explicit Z-matrix entry.

Note that, regardless of mode, bond angles altered by the Ulmschneider-Jorgensen concerted rotation moves are never reported in FYC.dat. Because there can be a lot of columns, it is possible for significant I/O lag to be associated with this option. Like all other instantaneous output files, the printing of FYC.dat is done by a single thread if CAMPARI's shared memory (OpenMP) parallelization is in use. This happens with other threads performing other tasks concurrently (if there are any).

XYZOUT

This very important keyword sets the frequency with which snapshots containing (at least) the Cartesian coordinates of the system (or selected subsystem) are written to a new file or appended to an existing trajectory file (→ documentation on output files and keyword XYZPDB). Part of the filename(s) will be determined by keyword BASENAME unless the calculation is a of a small molecule screen. For the latter multiple files with different names are written, thus necessetating a set of unique molecule molecule names in the corresponding input file.
This is the fundamental saving frequency for obtaining trajectory data and should be chosen carefully whenever the proposed simulation is resource-intensive. These files can easily be very large, and it is possible for significant I/O lag to arise. The printing of trajectory data is done by a single thread if CAMPARI's shared memory (OpenMP) parallelization is in use. This happens with other threads performing other tasks concurrently (if there are any).

XYZPDB

If structural output is requested (→ XYZOUT), this keyword chooses the output file format (see documentation on output files). It is an integer [1-3(4,5)] interpreted as:

1. Tinker-style .arc-files (ASCII)
2. ASCII .pdb-files (default option) in various output conventions (see PDB_W_CONV and PDB_OUTPUTSTRING)
3. CHARMM-style binary .dcd-files (these include the box information for each snapshot and have a CHARMM-style header - note that the header is written only once by CAMPARI and contains the number of snapshots in the file. This may not always be correct if simulations are prematurely terminated or trajectory files appended)
4. Compressed binary .xtc-files as used in GROMACS: note that this option is only available if the program is linked against a proper version of XDR (see installation instructions)
5. Compressed binary .nc-files as define by the NetCDF format in AMBER convention: note that this option is only available if the program is linked against a proper NetCDF library (see installation instructions).

When simulating large systems with significant computational expense, it is typical to preserve as much trajectory information as possible which is why file-sizes become important. The ratio of sizes for typical settings may be something similar to 15:15:3:1:3 for .arc vs. .pdb vs. .dcd vs. .xtc vs. .nc. Note that CAMPARI always prints out atoms in its intrinsic assumed order which may be different from that used by other programs. The exception to this is a specific setting changing that order across residue boundaries for polynucleotides (see PDB_NUCMODE). Unannotated binary files such as .xtc-, .dcd-, and .nc-files may therefore not be compatible with other software unless a template file is used (for the analogous option within CAMPARI see PDB_TEMPLATE).

XYZMODE

If structural output is requested (→ XYZOUT), this integer [1-2] keyword determines whether to write to a series of numbered files (1) or a single file (2, the default). This, however, currently works for pdb only (specifically: .arc are always multiple files, and the binary formats always write to (append) a single file).

MOL2PDBMODE

This keyword controls whether in a small molecule screen the final conformation of the entire system should be saved for every molecule. This requires having unique molecule names in the corresponding input file. The resultant file names end in "_END.pdb". These files can both be large and become numerous meaning that the option should be used with care. It is useful for recovering the complete conformation of the system in a screen, although this is also available by means of keyword XYZOUT and, in mol2 format, by means of keywords MOL2AUXINDEX and MOL2OUTMODE.

XTCPREC

If structural output is requested (→ XYZOUT) and the chosen output format is the binary .xtc-format (option 4 for XYZPDB), this keyword can be used to specify the multiplicative factor determining the accuracy of compressed xtc-trajectories (the minimum is 100.0). It is also required for proper reading of xtc-trajectories in xtc-analysis mode (see PDBANALYZE and XTCFILE).

PDB_NUCMODE

CAMPARI's internal representation of polynucleotides has one peculiarity. It assigns the entire PO₄^- functional group to the same nucleotide residue whereas most other programs seem to assign the 3'-oxygen atom to the residue carrying the sugar. This causes a non-trivial inconsistency when trying to use CAMPARI-generated pdb-files as input for other software. Therefore, this keyword defines how to assign the O3*-atom of nucleic acids in pdb-output only. There are two options:

1. The O3*-atom is assigned to the residue carrying the 5'-phosphate it is part of, i.e., it is the very first atom in that residue. This is the CAMPARI-inherent convention and reflects the authentic structure of arrays in CAMPARI (which is relevant for any analysis requiring atom numbers, see for example the input on selecting specific distance distributions to be collected).
2. The O3*-atom is assigned to the residue carrying the sugar it is part of; this is the PDB-typical convention. Note that this inherently disrupts the 1:1-correspondence between numbering in the pdb-file and how nucleic acids are represented internally. It is recommended if and only if CAMPARI-output is sought to be compatible with other software working in this latter convention. Note that for this option to work correctly with unsupported polynucleotide residues (recognized as such) atom names have to be canonical.

Note that option 2 also destroys the 1:1 correspondence between binary (unannotated) trajectory files or TINKER .arc-files on the one side and pdb-files on the other side. This may lead to misrepresentations when using the automatic visualization scripts. This option may be extended in the future to support other trajectory file formats - both for reading and writing - as well.

PDB_W_CONV

CAMPARI can in general process different atom and residue naming conventions for the formatting of PDB files. This keyword selects the format for written files. Choices are:

1. CAMPARI format
2. GROMACS format (atom naming, nucleotide and cap residue names, ...)
3. CHARMM format (atom naming, cap residue names and numbering (patches), ...): Note that there are two exceptions pertaining to C-terminal cap residues (NME and NH2) which arise due to non-unique naming in CHARMM: 1), NH2 atoms are called NT2 (instead of NT) and HT21, HT22 (instead of HT1, HT2), and 2), NME methyl hydrogens are called HAT1, HAT2, HAT3 (instead of HT1, HT2, HT3).
   
4. AMBER format (atom naming, nucleotide residue names, ...)

Note that for subsequent work with CAMPARI it is of course safest and easiest to just the default option (1). This keyword is supposed to provide cross-compatibility with other simulation software. Note that support is limited to standard biomacromolecules and typically does not extend to small molecules or unusual polymer residues (extensions may be provided in the future). Also note that for polynucleotides, the setting for PDB_NUCMODE is an independent modifier of pdb-output. This is the twin keyword to PDB_R_CONV above.

PDB_OUTPUTSTRING

This keyword allows changing the formatting string (Fortran) used for PDB files written by CAMPARI. This can be useful to make PDB files of very large systems and in particular for changing the precision of PDB files. In order for CAMPARI to read these files back in, the analogous keyword PDB_INPUTSTRING has to be used. Because Fortran in general deals poorly with string-based I/O, any improper use of this keyword can easily lead to abnormal program termination. The default format is "a6,i5,1x,a4,a1,a3,1x,a1,i4,a1,3x,3f8.3" (with the quotes). The letters (a, i, f) give the type of variable, which must not change. The numbers give the fields lengths, and these can be customized for variables of type integer ("i") or real ("f"). It is also possible to modify the field widths of string variables ("a") but that is likely harmful because the variables in use are tied to the default format. Note that the insertion code (the last "a1" element) is always written as a blank by CAMPARI since all residues are renumbered consecutively. The same is true for the alternate location indicator (the first "a1" element). The vast majority of modifications to the output format will create files that are no longer readable (at least correctly) by other software, .e.g., visualization software, or other simulation codes, and it may be useful to use CAMPARI itself (or to write a script) to convert back these nonstandard files whenever needed.
Common problems with standard PDB files, which can be addressed at least in part by the format string, are that the integer number for atom index overflows, that the chain indicator becomes fused to neighboring columns (because of overlong residue names or large residue numbers), that the residue number column overflows, that the coordinate entries get fused or overflow (if absolute coordinates are not centered at small (in absolute magnitude) values), or that the coordinate precision is insufficient for recovering exact covalent geometries based on this information alone.

XYZ_SOLVENT

If structural output is requested (→ XYZOUT), this logical keyword allows the user to suppress trajectory output for molecules labeled as solvent. This can be useful to down-convert trajectory files from explicit solvent runs or - more general - to isolate certain parts of the system from existing trajectory data (employing PDBANALYZE and ANGRPFILE). It may also be used to save space during actual simulations but it should be kept in mind that information about the solvent may be lost irrevocably and that the resultant trajectories may no longer be straightforward to analyze. A more general option for printing only parts of the system is provided by supplying an index file via keyword TRAJIDXFILE.

TRAJIDXFILE

Usage of keywords XYZ_SOLVENT in conjunction with the concept of analysis groups allows the user some amount of fine control over what is written to the trajectory file. In some scenarios this may not be enough (for example, if external scripts or software or even CAMPARI itself are meant to analyze non-trivial subsets of the system). Then, the user has the option to supply a simple index file providing per-atom control over what coordinate information is written to the trajectory file. Note that this will be useful for subsequent trajectory analysis runs only if the selected subset preserves the integrity of all molecules to remain in the output, or if the output format is pdb such that missing atoms can be re-built. For example, consider a block co-polymer consisting of two blocks. The full trajectory could be re-analyzed using an index file to yield a reduced trajectory in pdb-format (keywords XYZOUT, XYZPDB, and XYZMODE) that contains only one of the two blocks. With a properly adjusted sequence input file, it may then be possible to perform intrinsic CAMPARI analyses over the isolated block which really was part of a larger molecule. In this process, almost certainly some terminal atoms would have to be rebuilt at the break point (but those may not influence the analyses). For a description of the input file format, see here. Note that all other output selection settings are ignored if an index set is used via this keyword.

XYZ_FORCEBOX

If a system is simulated or analyzed that utilizes periodic boundary conditions, this keyword can be used to alter the standard CAMPARI way of placing atoms with respect to the unit cell. By default, CAMPARI will never break up molecules in trajectory output, which implies that the absolute coordinates in the trajectory file(s) can extend significantly beyond the formal boundary of the unit cell. Similarly, by default CAMPARI will assume that structural input preserves the integrity of molecules, i.e., that it conforms to exactly this standard. Sometimes (for example, for visualization or for certain analyses), it may be desired to instead have all atoms be inside the unit cell, and this is what this keyword accomplishes.
There are currently 4 different options related to both input and output.

0. For both input and output, CAMPARI assumes that molecules are intact and intended to be left intact.
1. For output, CAMPARI will leave molecules intact. For input, CAMPARI will assume that the coordinates are such that molecules have been forced to reside inside the central unit cell. Using box information, CAMPARI will calculate image shift vectors and apply them to the processed input. This option is incompatible with PDB_READMODE being 1. Image shift vectors are evaluated before possible tolerance violations are considered (see keywords PDB_TOLERANCE_B and PDB_TOLERANCE_A.
2. For input, CAMPARI assumes that molecules are intact (no corrections applied). For output, it will force coordinates to reside inside the central unit cell by breaking up molecules as needed.
3. This options combines the properties of options 1 and 2 for input and output, respectively.

Note that splitting molecules into two or more parts may interfere with molecular representations relying on bonds, etc.
Note that in some cases trajectory files with broken-up molecules may be ambiguous unless information about the expected topology is present or provided. The input strategy currently implemented works as long as the length of Z matrix bonds remains small in comparison to the box dimensions. Note that the start of the simulation from a pdb file is affected by this keyword as is the analysis of (binary) trajectory files.
It is not recommended to use options 1 or 3 above for writing trajectories from a production simulation, rather the output feature is intended to transform preexisting trajectories (via trajectory analysis mode). Lastly, in the case of an analysis run, any structural input with entire molecules given as the "wrong" images will also be adjusted by options 1 and 3 above. This scenario should be avoided as it leads to inconsistencies in any operations relying on absolute coordinates. For options 0 and 2, output coordinates will not be altered by XYZ_FORCEBOX but they may still be altered by keywords XYZ_REFMOL and ALIGNCALC.

XYZ_REFMOL

If a system is simulated or analyzed that utilizes periodic boundary conditions, this keyword can be used to alter the standard CAMPARI way of placing molecules in three contexts, viz., trajectory output, structural clustering using absolute Cartesian coordinates (RMSD), and, similarly, the derivation of the alignment operator for output trajectory alignment. The use of this keyword is explained primarily in the context of the first role.
By default, CAMPARI will never allow the geometric center (or center of mass in gradient-based simulation runs) to "leave" the central unit cell. When looking at intermolecular interfaces, this can lead to the undesirable effect of the interface being broken across the periodic boundary. These images often flicker back and forth, which makes visual inspection difficult unless periodic images are explicitly replicated. XYZ_REFMOL allows the user to specify a reference molecule whose center serves as reference point for all images, i.e., the coordinates of all other molecules printed to trajectory output are those of the nearest image of these molecules with respect to the chosen reference. This operation does not destroy information (i.e., it does not center or align anything) but leads to molecules being displayed that are outside of the central unit cell. In fact, the reference molecule is the only one that is guaranteed to reside in the central cell at all times.
Note that this keyword does not actually alter coordinates used internally, and therefore has no impact on the majority of analysis functions, etc. The only exceptions are structural clustering relying on absolute Cartesian coordinates (options 5, 6, and 10 for CDISTANCE) and the trajectory alignment facility. For the latter XYZ_REFMOL simply picks the reference molecule to override the internal heuristic. In both scenarios, the alignment operator is derived using image-corrected coordinates for all conformations in question. This role of XYZ_REFMOL is distinct but not separable from the role for trajectory output (i.e., it is not possible to use XYZ_REFMOL to pick the reference molecule for image selection for clustering or trajectory alignment while retaining the default trajectory output). XYZ_REFMOL is also ignored for the pdb files written at the beginning and end of a simulation. Along similar lines, trajectory files created in such a manner can be read back by CAMPARI without problems (internally, every molecule is translated to the central unit cell upon read-in as long as the box information (BOUNDARY, SIZE, and ORIGIN) is preserved). Note that XYZ_REFMOL always relies just on geometric centers (rather than centers of mass), irrespective of any simulation or analysis settings).

ALIGNCALC

In trajectory analysis runs CAMPARI offers the option to structurally superpose the current Cartesian coordinates to a suitable reference. Note that this functionality is conveniently available through almost all molecular visualization software packages. CAMPARI provides automatically generated visualization scripts designed to work with VMD. If these options are unavailable or inconvenient, for example, because the visualization program tries to read an entire very large data set into memory, ALIGNCALC lets the user set the interval at which CAMPARI should perform structural alignment. For example, to create - from an original trajectory - a superposed trajectory of every 10th frame, XYZOUT would have to be 10 and ALIGNCALC would have to be 10 or a factor of 10 (5,2,1).
For convenience, the root mean square deviation over the alignment set after alignment can be written to an instantaneous output file. This can be enabled by specifying a negative number to ALIGNCALC, which is, except for the sign, interpreted in the same way. Sometimes it may also be desirable to align on one set of atoms and compute RMSD values for another set. CAMPARI supports this, if in addition to an appropriate choice of alignment set, the user provides another index set via keyword CFILE. This second input then becomes an additional set to compute RMSD values for. This is the same logic as found in RMSD-based structural clustering with split sets (see option 6 for keyword CDISTANCE).
Alignment happens before any of the analysis routines are called and works by first defining a reference set of atom indices (→ ALIGNFILE). It can be somewhat time-consuming and is currently not aided in any way by CAMPARI's shared memory (OpenMP) parallelization. Using a quaternion-based algorithm, an optimal translation and rotation is determined that minimizes - when applied to the current coordinates - the deviation between the transformed current coordinates and the reference coordinates (i.e., a set of coordinates for all atoms in the alignment set). Note that this procedure will always preserve the internal state of molecules and - except for certain cases in periodic boundary conditions - the relative arrangement of molecules. It will not, however, preserve the relative position of the system boundary. This may lead to artifacts in energetic analyses of aligned trajectories or any analyses that rely upon relative, intermolecular coordinates.
There are two ways of defining/providing the coordinates for the alignment set. The first is via an external file. Here, CAMPARI reuses the pdb-template functionality. If keyword PDB_TEMPLATE is specified and successfully read, then the reference coordinate set is extracted from this file for the set of atoms defined via ALIGNFILE. Note that the template may serve a double purpose in this scenario as it may still provide the atom numbering map needed to read binary trajectory formats with non-CAMPARI atom order. If no template is specified, the reference coordinates will be defined by the previously aligned structure. This successive alignment therefore uses a different reference coordinate set each time and will consequently lead to drift.
As described for keyword XYZ_REFMOL, the combination of periodic boundary conditions and multimolecular assemblies can become ambiguous in terms of absolute coordinates. By default, CAMPARI will scan the alignment set and use the molecule with the largest number of contributing atoms as the reference one. This choice can be overridden by keyword XYZ_REFMOL. It can be confusing that the alignment operator is derived for the image-corrected coordinate sets yet the transformation is applied to the coordinates in their default state. This is relevant if molecules are not found in the central unit cell in the trajectory files. In this scenario, the output gets particularly difficult to interpret if XYZ_REFMOL and/or XYZ_FORCEBOX modify the output coordinates as well (not recommended).

ALIGNFILE

If system alignment is possible and requested (→ ALIGNCALC), this keyword allows the user to supply the path and name of a mandatory input file containing an atomic index list defining the set of atoms to align on. For example, in the simulation of a macromolecule with co-solutes it will not be meaningful to use the entire set of atoms in the system as the alignment set since the randomly dispersed co-solutes will dominate the alignment. Instead, one will typically want to only supply nonsymmetric protein atoms here.
This keyword serves a second purpose, viz., if structural clustering is requested, and if an RMSD distance criterion with differing alignment and distance atom index sets is desired, this keyword lets the user specify the input file with the alignment set. Simultaneous use of both functionalities is permitted. The converse is also possible, i.e., to specify an additional distance set for RMSD evaluation and instantaneous output in the same logic. Then, keyword CFILE can be used to specify this additional distance set. Lastly, note that any set used for alignment must consist of at least three atoms.

MOL2OUTMODE

This keyword determines in coarse fashion what information, per screened molecule, is written to the running output file of a small molecule screen. The options available are as follows:

1. The coordinates corresponding to the respective minimum energy conformations are written. In addition, coordinates corresponding to cluster centroids of clusters exceeding the desired threshold are provided.
2. This is the same as option 1 only that in addition the final conformation is written to file as well.
3. Only the respective minimum energy conformations are written to the mol2 file.
4. Only the respective final conformations are written to file.
5. With this option, the output to the mol2 file can be synchronized with the standard trajectory output enabled by keyword XYZOUT. This means that the file is appended periodically (respecting keyword EQUIL for each individual calculation).

In all cases, the coordinates written to the file include those of the exchanged molecules and, possibly, any additional coordinates requested by the user through keyword MOL2AUXINDEX. Note that this file, as it is heavily annotated and human-readable, can become very large very quickly.
The general policy of CAMPARI-written mol2 output files is that they preserve the input file structure and content for the 3 main sections (MOLECULE, ATOM, BOND) as much as possible. Other sections are not preserved (like SUBSTRUCTURE) or generated from scratch (like ALT_TYPE). There are two notable exceptions to the former policy, however. First, all special bond annotation information (like "ar") is lost (always "1"). This may be improved in the future. Second, in the ATOM section, the substructure and substructure index fields can be utilized in different manners, which is controlled by keyword MOL2SUBPRT. In addition, there are minor variations, e.g., molecule names are appended to distinguish the various poses listed above for the same molecule, or the partial charge set is always given as "USER_CHARGES" in the MOLECULE section.

MOL2AUXINDEX

This keyword works exactly like keyword TRAJIDXFILE only that it selects a subset of additional atomic positions to be written to the running output file of a small molecule screen. The indexing as usual is with respect to CAMPARI's internal numbering.
A special option for MOL2AUXINDEX is given by "automatic" (without the double quotes). In this mode, CAMPARI will analyze the constraints specified by keywords FMCSC_FRZFILE, FMCSC_TMD_UNKMODE, and FMCSC_MOL2FOCUS and determine an suitable index list automatically. This does not respond correctly to constraints introduced exclusively by move set choices in pure Monte Carlo runs. The index list is written to output file MOL2EXTRAATOMS.idx. Since the resultant mol2 files no longer contain just small molecule information, their (re)processing by CAMPARI requires specifying the same index list as a separate input file (and the receptor to be present), i.e., for keyword MOL2AUXINPUT.

MOL2SUBPRT

This keyword sets the priority for what to write to the substructure fields in the ATOM section of a running output file of a small molecule screen. The options available are as follows:

1. Prioritize residue information over solvation group information over charge group information.
2. Prioritize residue information over charge group information over solvation group information.
3. Prioritize solvation group information over charge group information over residue information.
4. Prioritize charge group information over solvation group information over residue information.

In all cases, priorities for features not supported by the current calculation are ignored, i.e., if the Coulomb potential is turned off, there is no charge group information, and if the ABSINTH DMFI is turned off, there is no solvation group information. The residue information columns mean different things for the screened molecule and any additional atoms written to the mol2 file. For the former, it replicates the information found in the input file while for the latter it prints native CAMPARI residue names and numbers (referencing the whole simulated system).

POLOUT

This keyword sets the interval how often to compute and write current system-wide polymeric variables (→ POLYMER.dat). This instantaneous output can be useful to easily monitor structural changes (such as dimerization events) in dilute systems with heterogeneous density. It is completely uninformative for systems with homogeneous density. For simulations of a single polymer chain, distributions of polymeric order parameters as well as correlation functions can be computed from the output in POLYMER.dat. When CAMPARI's shared memory (OpenMP) parallelization is in use, the computation of the system-wide gyration tensor and related properties as well as the writing to POLYMER.dat are done by a single thread. This happens with other threads performing other tasks concurrently (if there are any).

POLCALC

This keyword lets the user specify the frequency with which values for polymeric properties incurring low computational cost are computed. These data are collected and reported resolved by analysis group and include characteristic values for shape and size, histograms of end-to-distances, etc. Setting this keyword such that polymeric analyses are performed, several output files are generated: (→ POLYAVG.dat, RGHIST.dat, RETEHIST.dat, and RDHIST.dat). Furthermore POLCALC controls the interval for data collection to obtain averages of the suitably defined angular correlation function along the polymer backbone, which may be related to the intrinsic stiffness or persistence length of the polymer (→ PERSISTENCE.dat and TURNS_RES.dat). Lastly, this keyword controls the frequency for the computation and averaging of molecular, radial density profiles, i.e., the mass distribution function along the radial coordinate originating from the each molecule's center of mass considering only atoms belonging to that molecule (→ DENSPROF.dat). This quantity is used in Lifshitz-type polymer theories. When CAMPARI's shared memory (OpenMP) parallelization is in use, these calculations are performed by a single thread while other threads perform other tasks concurrently (if there are any).

RHCALC

Since the computation of comprehensive polymer-internal distances is more expensive, this dedicated keyword controls the data collection interval for analyses relying on such data. A comprehensive set of internal distances in CAMPARI is used to compute three quantities:

1. An alternative estimate of the polymer's spatial size which is sometimes related to the hydrodynamic radius (→ corresponding entry in POLYAVG.dat; note that should RHCALC be set such that no analysis is performed but POLCALC be chosen such that the other quantities in POLYAVG.dat are compute and provided, the corresponding column must be ignored).
2. A scaling profile of the internal distances with distance of separation in primary sequence (→ INTSCAL.dat).
3. The scattering (Kratky) profile of the polymer (→ KRATKY.dat; this relies on the additional frequency setting SCATTERCALC).

Note that the scaling of internal distances can be used to assess solvent quality given the simulation of just a single polymer very efficiently. All mentioned data are obtained resolved by analysis group. When CAMPARI's shared memory (OpenMP) parallelization is in use, these calculations, including the dependent Kratky analysis, are (at the moment) performed by a single thread while other threads perform other tasks concurrently (if there are any). Because these analyses scale poorly with system size, they can quickly become performance-limiting, which will similarly limit parallel efficiency.

SCATTERCALC

As alluded to above, this keyword sets an auxiliary frequency for the calculation of scattering properties resolved by analysis group (→ KRATKY.dat). This requires computing Fourier transforms of internal distances for a series of wave vectors and is consequently a very expensive calculation. Due to the coupling to the computation of internal distances (see RHCALC), this keyword is not interpreted like the other interval keywords (???CALC). Instead, SCATTERCALC sets the calculation interval amongst only those steps chosen already via RHCALC. For example, if RHCALC is 10 and SCATTERCALC is 20, then scattering data will be accumulated every 200 steps. The data in KRATKY.dat can be used to compare simulation data directly to experiment. In a double-logarithmic plot, it may also be possible to identify linear regimes ("power law regime" in contrast to the "Guinier regime" for smaller wave vectors) which can be fit to yield the scaling exponent for fractal objects. Conversely, for globular polymers, Porod's law may hold.

SCATTERRES

Since the required number of points and range of wave vectors for the prediction of scattering profiles may be system-dependent, this keyword allows the user to adjust the spacing of wave vectors assuming scattering data are being calculated at all (→ RHCALC and SCATTERCALC). The first wave vector's absolute magnitude q=|q| will always be 0.5·SCATTERRES with units of Å^-1. In general, the larger the chain, the smaller the absolute magnitudes of wave vectors needed.

SCATTERVECS

Since the required number of points and range of wave vectors for the prediction of scattering profiles may be system-dependent, this keyword allows the user to adjust the total number of employed wave vectors assuming scattering data are being calculated at all (→ RHCALC and SCATTERCALC). Together with SCATTERRES, this determines the range of the wave vectors. Note that generally a coarse resolution (and hence a small number of vectors) is sufficient as scattering profiles tend to be very smooth functions.

HOLESCALC

For polymers it may be interesting to analyze the distribution of "internal" void spaces. In CAMPARI, a rudimentary analysis routine exists which attempts to place spheres of varying size at different distances from the molecule's center-of-mass and to record whether any overlap with part of the polymer is encountered. This analysis is recorded in instantaneous output (HOLES.dat), and the latter needs to be post-processed. Note that this analysis is restricted to simulations of monomeric polymers. When CAMPARI's shared memory (OpenMP) parallelization is in use, it is performed by a single thread while other threads perform other tasks concurrently (if there are any).

RGBINSIZE

If standard polymeric analyses are performed (→ POLCALC), this keyword sets the size of the bins in Å for the three output files RGHIST.dat, RETEHIST.dat, and DENSPROF.dat. It therefore determines the resolution along the radius of gyration- or related axes.

POLRGBINS

If standard polymeric analyses are performed (→ POLCALC), this keyword can be used to set the number of bins of size RGBINSIZE for the three output files RGHIST.dat, RETEHIST.dat, and DENSPROF.dat. Since quantities like the radius of gyration or end-to-end distances are strongly system-dependent, it is up to the user to ensure the appropriate number of bins. Note that - just like all other histograms in CAMPARI - terminal bins will be overstocked should range exceptions occur.

PHOUT

This keyword controls the frequency how often to output ionization states of certain ionizable residues. Currently, this analysis relies on pseudo-Monte Carlo moves (see PHFREQ) to work and is therefore only available in straight MC runs. Further limitations are listed in the descriptions of sampler and output file.

ANGCALC

This keyword lets the user define the interval how often to extract polypeptide backbone torsion angle statistics, i.e., how often to go through all non-terminal polypeptide residues and bin values for the φ/ψ-angles into a two-dimensional histogram. This keyword also controls the data collection frequency for estimation of vicinal NMR J-coupling constants (H_N to H_α → JCOUPLING.dat). The Ramachandran analysis itself is reported globally in a file called RAMACHANDRAN.dat. Due to the system-wide averaging (including over molecules of different type), this is probably most meaningful for simulations of single homopolymers. For more detailed control, further output files may be obtained: residue-specific as well as analysis group-specific maps should requests have been provided via keywords RAMARES and RAMAMOL, respectively. When CAMPARI's shared memory (OpenMP) parallelization is in use, these analyses are performed by a single thread while other threads perform other tasks concurrently (if there are any).

ANGRES

This keyword matters only if ANGCALC is chosen such that polypeptide backbone φ/ψ-statistics are accumulated. If so, it sets the resolution in degrees for such angular distribution functions. The smallest permissible value at the moment is 1.0°.

RAMARES

This keyword matters only if polypeptide φ/ψ-analysis is requested (→ ANGCALC). If so, it allows the user to monitor the distributions specifically for selected polypeptide residues in the system. The first entry, which defaults to zero, specifies the number of such specific requests. The user then has to provide the appropriate number of integer values (residue numbers as defined per sequence input) on that same line in the key-file. The maximum number for individually monitored residues is limited to 1000, but even this requires increasing the default string length CAMPARI assumes (in a file called macros.i) during compilation. Successful requests (those pointing to non-polypeptide, non-existing, or terminal residues will be ignored) will create output files like "RESRAMA_00024.dat".

RAMAMOL

This keyword is exactly analogous to RAMARES only that it operates not on residue but on analysis groups (all residues of all molecules in that analysis group are pooled, numbering as reported initially in the log-output). It will create files like "MOLRAMA_00002.dat".

INTCALC

This keyword sets the interval how often to compute comprehensive statistics for typical internal coordinates of the system, i.e., all bond lengths, angles, torsional angles, as well as improper torsional angles (trigonal-planar centers - consult PARAMETERS for further details). Note that molecular topology defines which atom pairs - for example - share a bond. With this analysis, it is therefore not possible to analyze arbitrarily defined distances, angles, and torsion angles in the system. If turned on, up to five different output files are provided, namely INTERNAL_COORDS.idx, INTHISTS_BL.dat, INTHISTS_BA.dat, INTHISTS_DI.dat, and INTHISTS_IM.dat. When CAMPARI's shared memory (OpenMP) parallelization is in use, all of these analyses are performed (in sequence) by a single thread while other threads perform other tasks concurrently (if there are any).

WHICHINT

This is one of the few keywords expecting multiple inputs and matters only if internal coordinate analysis is requested (→ INTCALC). Four integers should be provided and each one is interpreted as a logical to turn on individual groups of internal coordinate analyses. The first turns on the calculation of bond length histograms, the second that of bond angle histograms, the third that of improper dihedral angle histograms, and the fourth that of proper torsional angle histograms. Note that the number of possible internal coordinates quickly exceeds the number of atoms for any complex molecule. These analyses can therefore easily become fairly time-consuming as well as data-rich (in terms of the sizes of the output files). This is one of the reasons for introducing this selection mechanism. The other lies simply in the fact that in any simulation using CAMPARI-typical torsional space constraints (see CARTINT) analyses of bond length, angle, and improper dihedral distribution is meaningless.

SEGCALC

This keyword lets the user specify the interval how often to scan the polypeptide backbone for stretches of similar secondary structure (as defined in the specified file through FMCSC_BBSEGFILE). The annotation - in contrast to DSSP - is obtained purely on torsional criteria and relies on defining consensus regions within φ/ψ-space. These consensus definitions are found in a supplied data file (→ BBSEGFILE). At the end of the simulation results are written to files named BB_SEGMENTS_NORM.dat, BB_SEGMENTS_NORM_RES.dat, BB_SEGMENTS.dat, and BB_SEGMENTS_RES.dat This analysis is resolved by analysis group and useful to identify coarse secondary structure propensities in polypeptides. As an example, the data in BB_SEGMENTS_NORM_RES.dat can be used to compute parameters of the helix-coil transition according to the Lifson-Roig formalism (see for example Tutorial 3 or this reference). SEGCALC also controls the computation of global (at a molecular level) secondary structure order parameters f_α and f_β (which are also used for the corresponding bias potentials → SC_ZSEC used in Tutorial 9 or this reference). Various distribution histograms are written to files ZSEC_HIST.dat, ZAB_2DHIST.dat, and ZBETA_RG.dat. Analysis of these order parameters is similarly performed in analysis group-resolved fashion. When CAMPARI's shared memory (OpenMP) parallelization is in use, both of these analyses are performed sequentially by a single thread while other threads perform other tasks concurrently (if there are any).

DSSPCALC

This keyword specifies how frequently to perform DSSP analysis. DSSP is a secondary structure assignment procedure for proteins (reference). All eligible (i.e., full peptide) residues are scanned for backbone-backbone hydrogen bond patterns and various statistics and running output is provided if so desired (see DSSP_NORM_RES.dat, DSSP_NORM.dat, DSSP.dat, DSSP_RES.dat, DSSP_HIST.dat, DSSP_EH_HIST.dat, and DSSP_RUNNING.dat). The DSSP results typically complement the results from backbone segment statistics (see for example BB_SEGMENTS_NORM_RES.dat) well as the former are based exclusively on hydrogen bond patterns while the latter are based exclusively on dihedral angles. When CAMPARI's shared memory (OpenMP) parallelization is in use, the DSSP analysis is performed by a single thread while other threads perform other tasks concurrently (if there are any). Similar to contact analyses, the determination of the hydrogen bond patterns scales, at some level, poorly with system size. They thus can become performance-limiting, which will similarly limit parallel efficiency.

INSTDSSP

If DSSP analysis is requested (→ DSSPCALC), this keyword is interpreted as a simple logical whether to write out running traces of the full DSSP assignment for the current snapshot (see DSSP_RUNNING.dat). This can be useful when analyzing input trajectories or even individual pdb-structures with CAMPARI. Instantaneous DSSP output is currently not supported for MPI-averaging calculations (see MPIAVG). This output file can easily become very large, and it is possible for significant I/O lag to occur because of this.

DSSP_MODE

Based on DSSP analysis (→ DSSPCALC), the code computes two order parameters to measure canonical secondary structure content. The E-score corresponds to the β-content and the H-score to the α-content. they are system-wide quantities and are computed as follows:

   E-score = E-fraction · ( H-bond-Score_E )^1/n
   H-score = H-fraction · ( H-bond-Score_H )^1/n

Here, E-fraction and H-fraction are simply the fractions of residues which are assigned E or H according to DSSP. n is an arbitrary scaling exponent (see DSSP_EXP). H-bond-Score_E is a continuous variable which measures the mean quality of the hydrogen bonds forming the β-sheets in the system and H-bond-Score_H is the analog for α-helices. In principle, all the hydrogen bond energies are collected and divided by the value for the same number of good hydrogen bonds (see DSSP_GOODHB). The quantity can be capped, however, based on the choice for DSSP_MODE:

1. Every hydrogen bond can maximally contribute the value of DSSP_GOODHB. Therefore, H-bond-Score_X is always less than unity and only approaches unity if each and every relevant H-bond is at least as favorable as the cutoff given by DSSP_GOODHB. This is the most stringent score. The resultant X-scores will always be less or equal to the corresponding X-fractions.
2. Every hydrogen bond can maximally contribute DSSP_MINHB which is always more negative than DSSP_GOODHB. The value of H-bond-Score_X, however, is capped to be at most unity. In this score, very strong H-bonds can compensate the effects of a few weak ones but the value for X-score still is capped by the corresponding X-fraction.
3. Every hydrogen bond can maximally contribute DSSP_MINHB. The value of H-bond-Score_X is not capped and can adopt values larger than unity. The X-score is capped, however, to never exceed unity. This is the most lenient score and the only one in which X-score can exceed the value of X-fraction.

Through the H-bond weighting two things are achieved: i) instead of the inherently discreet X-fractions, smooth and continuous distributions are obtained for X-score, and ii) it removes redundancy in which secondary structure elements with predominantly weak H-bonds are indistinguishable from perfect, canonical secondary structure elements when using X-fraction. The limit of X-score ≡ X-fraction is of course obtained for n → ∞.

DSSP_EXP

For the DSSP analysis in CAMPARI (→ DSSPCALC), this keyword choose the integer scaling exponent for the H-bond term in computing E- and H-scores (see DSSP_MODE).

DSSP_GOODHB

For the DSSP analysis in CAMPARI (→ DSSPCALC), this keyword defines the standard energy for a "good" hydrogen bond. This is used to evaluate the smoothed E- and H-scores (see DSSP_MODE) and not part of the original DSSP standard. Permissible values lie between -1.0 and -4.0 kcal/mol.

DSSP_MINHB

For DSSP analysis (→ DSSPCALC), this keyword specifies the minimal (= lowest possible = most favorable) energy for any hydrogen bond. Since the DSSP-formula is based on inverse distances it is useful to introduce this lower cap such that conformations with steric overlap do not overly bias the analysis (for example in pdb-analyses → PDBANALYZE). Permissible values lie between -10.0 and -4.0 kcal/mol.

DSSP_MAXHB

For DSSP analysis (→ DSSPCALC), this keyword allows the user to define the maximal (= highest possible = least favorable) energy fo any hydrogen bond. This is the fundamental cutoff for DSSP to consider H-bonds and therefore a very important quantity for the analysis to be meaningful. The recommended value is -0.5 kcal/mol but values between -1.0 and 0.0 kcal/mol are allowed.

DSSP_CUT

For DSSP analysis (→ DSSPCALC), this keyword defines the distance cutoff applied to the C_α-atoms of two peptide residues to consider them for hydrogen bonds. This can be relatively short (defaults to 10 Å) but the accuracy hinges on the choice for DSSP_MAXHB. Consistency has to be ensured by the user. Using a C_α cutoff for pre-screening of residue pairs significantly reduces the computation time needed by the DSSP analysis.

CONTACTCALC

This keyword specifies the interval how often to perform contact analysis, i.e., how often to get information about which and how many solute residues are close to each other. Such contacts are generally calculated according to two definitions in CAMPARI; by considering center-of-mass distances and by considering minimum atom-atom distances (both applied to pairs of residues). The output includes a map of average contact frequencies (CONTACTMAP.dat), histograms of contact numbers (CONTACT_HISTOGRAMS.dat), and a dependent analysis of solution structure by molecule (CLUSTERS.dat, MOLCLUSTERS.dat, and COOCLUSTERS.dat). The last analysis relies on an additional keyword: CLUSTERCALC. Note that these analyses are always restricted to residues of molecules tagged as solutes (→ "FMCSC_ANGRPFILE) in order to facilitate frequent contact analysis even if solute molecules are explicitly represented (which may be prohibitively expensive otherwise). When CAMPARI's shared memory (OpenMP) parallelization is in use, contact analysis is performed by a single thread while other threads perform other tasks concurrently (if there are any). Similar to DSSP analyses, the determination of spatial proximity patterns scales, at some level, poorly with system size and can thus become performance-limiting, which will similarly limit parallel efficiency.

CLUSTERCALC

This keyword (along with CONTACTCALC) controls the computation frequency for solute cluster statistics (i.e., cluster sizes, cluster contact orders, and molecule-resolved cluster statistics) where a cluster is defined through the minimum atom-atom distance contact definition (between any pair of residues). Note that this is the interval at which to perform cluster analysis from within the calculation of contacts (i.e., CLUSTERCALC is relative to CONTACTCALC, as SCATTERCALC is to RHCALC). The reason is that the cluster detection algorithm relies on the determination of contacts but that it may not always be a meaningful analysis to perform (see CLUSTERS.dat, MOLCLUSTERS.dat, and COOCLUSTERS.dat for further details on the output).

CONTACTOFF

If contact analysis is requested (→ CONTACTCALC), this keyword defines a sequence-space offset to exclude neighboring residues from the analysis. For topologically connected systems (i.e., polymer chains) data for near-neighbor contacts such as i↔i+1 may be uninformative as they will always be in contact on account of the underlying topology. Note that the omission only applies to intramolecular contacts. Setting this to zero includes everything (even i↔i), and any larger integer lets the analysis start from this distance. The default here is zero, and there is rarely a reason to change it.

CONTACTMIN

For contact and cluster analysis (→ CONTACTCALC), this keyword provides the threshold value for of a residue-residue contact in Å. Here, the threshold is applied to the minimum distance between any arbitrary pair of atoms formed by the two residues in question. This defaults to 5.0 Å. Note that this computationally more expensive definition has the advantage of rendering the contact probabilities more or less size-independent for polyatomic residues. In the presence of excluded volume interactions, monoatomic residues (ions) of different size will still yield contact statistics which include physically meaningless biases, however.

CONTACTCOM

For contact and cluster analysis (→ CONTACTCALC), this keyword gives the alternative threshold value for a residue-residue contact in Å. Here, the threshold applies to the distance between the centers of mass of the two residue it question. It also defaults to 5.0 Å. Note that (in the presence of excluded volume interactions) contact probabilities obtained this way are by design dependent on the size of the interacting residues and results may be misleading if contact statistics between pairs of residues with highly variable size are compared.

PCCALC

This keyword allows the user to specify how often to perform pair correlation analysis, i.e., get distance counts for a variety of intra- and intermolecular distances and - in the case of intermolecular distances - proper normalization by the current volume element. It controls the computation frequency for three different classes of distance distributions:

1. Generic intramolecular amide-amide distributions covering various acceptor-donor pairs, as well as a centroid-centroid distribution (→ AMIDES_PC.dat), only relevant for polypeptide systems.
2. Generic intermolecular pair correlation functions for solutes (→ RBC_PC.dat), only relevant for systems with more than one solute. Note that this option can consume inordinate amounts of memory should a lot of different solute types be present. Workarounds consist of disabling this analysis or of using the analysis group feature to redeclare most of those as solvent molecule types and to use specific atom-atom distributions instead.
3. Specific atom-atom distributions and/or pair correlation functions as defined through an index file provided by keyword PCCODEFILE (→ GENERAL_PC.dat).

Note that analysis groups are respected by both the output in RBC_PC.dat and in GENERAL_PC.dat. The user-defined requests, unlike the centroid-centroid distributions, ignore whether a molecule is tagged as solvent or solute (→ ANGRPFILE). Conversely, the output in AMIDES_PC.dat is not controllable in any way, and the results are usable only for very specialized applications.
When CAMPARI's shared memory (OpenMP) parallelization is in use, each of these 3 analyses is treated independently. This means that each one is executed by a single thread while other threads perform other tasks concurrently (if there are any).

DO_AMIDEPC

If pair correlation analysis is requested (→ PCCALC), this keyword enables the user to disable the computation of intramolecular amide-amide distance distribution functions (→ AMIDES_PC.dat) by setting it to zero.

PCBINSIZE

This keyword specifies the distance bin size in Å for pair correlation analysis (→ PCCALC).

PCCODEFILE

This keyword specifies the path and filename to the input file for requesting specific pair correlation or distance distribution analyses (see FMCSC_PCCODEFILE). It is also possible to generate instantaneous traces for the selected distances with keyword INSTGPC. In general, the input is rather flexible and it is possible to pool many analogous or even unrelated atom-atom distances under a certain code or to use unique codes for very specific requests. Upon successful parsing of the input and given that pair correlation analysis is globally requested (→ PCCALC), the output file GENERAL_PC.dat is created.

GPCREPORT

This logical keyword instructs CAMPARI whether or not to write out a summary of the terms requested through FMCSC_PCCODEFILE (→ GENERAL_PC.idx). It is only available if distance distribution / pair correlation analysis is in use (→ PCCALC).

INSTGPC

This keyword lets the user instruct CAMPARI how often to print out instantaneous values for all the specific distances selected via FMCSC_PCCODEFILE. Note that this does not include the generic distances CAMPARI analyzes, and consequently the keyword has no effect if no usable input has been provided via FMCSC_PCCODEFILE or of course if pair correlation analysis is not in use. This keyword is understood as a dependent frequency, i.e., a setting of 1 will print instantaneous values for every PCCALC^th step. Note that this feature is disabled by default and that the output in GENERAL_DIS.dat can easily become large.

SAVCALC

This keyword specifies how often to compute (or record) solvent-accessible volume (SAV) fractions and solvation states for the system. If the ABSINTH implicit solvent model is in use (→ SC_IMPSOLV), this analysis can rely on the current values for those quantities (no additional, computational cost); otherwise computing atomic SAV fractions incurs a moderate computational cost. The solvent-accessible volume will globally depend on the choice for the thickness of the assumed solvation shell (→ SAVPROBE). The mapped solvation states as reported for individual atoms (please refer to the ABSINTH publication for details) will depend on further ABSINTH parameters. Some of these can be adjusted through patches, e.g., user-supplied values for overlap reduction factors.
SAV analysis creates at most three output files; an instantaneous one (SAV.dat) that depends on auxiliary keyword INSTSAV, an atom-resolved output file that reports simulation averages (→ SAV_BY_ATOM.dat), and finally a file containing distribution functions (histograms) for selected atoms for those quantities (→ SAV_HISTS.dat). The latter file is dependent on another auxiliary keyword, i.e., SAVATOMFILE. The instantaneous output is primarily useful as a diagnostic tool for the system while the simulation is running, and to be able to compute correlation functions, multidimensional histograms, etc. for quantities related to the solvation of specific sites on macromolecules. Please refer to the descriptions of the output files for further details.
When CAMPARI's shared memory (OpenMP) parallelization is in use, the SAV analysis is handled by a single thread while threads perform other tasks concurrently (if there are any). However, if the ABSINTH DMFI is turned on, the analysis task simply consists of recording the values. Conversely, the evaluation of the DMFI is thread-assisted as usual.

INSTSAV

If analysis of solvent-accessible volume fractions is requested (→ SAVCALC), this keyword allows the user to have a quantity related to the total SAV along with a running average being printed to a dedicated output file (→ SAV.dat). In addition, the values for SAV fractions for selected atoms (via SAVATOMFILE) are written out. The latter allows the construction of correlation functions, multidimensional histograms, etc. The keyword (positive integer) is interpreted as a print-out frequency relative to the frequency with which SAV analysis is performed per se. This means that the effective print-out frequency will be SAVCALC·INSTSAV. Depending on the choices, the resultant output file can easily become very large, and it is possible for significant I/O lag to occur because of this.

SAVATOMFILE

If analysis of solvent-accessible volume fractions is requested (→ SAVCALC), this keyword specifies the location and name of a simple input file (list of atomic indices, format is described elsewhere) that allows the user to select a subset of the system's atoms for creating histograms of both SAV fraction and resultant solvation state (see above). These histograms are written to a dedicated output file (→ SAV_HISTS.dat). In addition, if instantaneous output of SAV-related quantities is requested (→ INSTSAV), the values for the SAV fractions for the selected atoms are written to the corresponding output file (SAV.dat). Note that instantaneous values for the SAV fractions allow manual computing (during post-processing) of solvation states (using parameters set in the key-file and/or reported in SAV_BY_ATOM.dat, and using the reference publication to retrieve the necessary expressions). It should be kept in mind that with normal settings for SAVPROBE, SAV fractions of nearby atoms are tightly coupled. This means for example that requesting information for atoms that are covalently bound will rarely yield additional information. Lastly, the binning for the histograms is fixed and uses 100 bins across the interval from zero to unity (both quantities are restricted to this interval).

NUMCALC

This keyword is relevant only when the chosen thermodynamic ensemble allows for particle number fluctuations (simulation is performed in the (semi-)grand canonical ensemble). It then specifies the number of Monte Carlo steps between successive accumulations of number-present histograms for each fluctuating particle type. For a description of the corresponding output file please refer to PARTICLENUMHIST.dat.

COVCALC

This simple keyword instructs CAMPARI to collect raw data (signal trains) for select degrees of freedom in the system (currently this is restricted to all flexible dihedral angles → TRCV_xxx.tmp) every COVCALC steps. This is a near-obsolete functionality that has large practical and technical overlaps with the output written to FYC.dat via TOROUT. It was meant to provide intrinsic support for variance/covariance analyses, e.g., with the ultimate goal of performing dimensionality reduction. Given that merely raw data are provided and that dihedral angle data are generally circular (periodic) variables requiring the use of circular statistics (not as trivial as it may sound), usage of this facility is generally not recommended. This option is available in different modes (see COVMODE) and may eventually be revived or extended later. Note that CAMPARI can perform intrinsic principal component analysis (PCA) and time-lagged independent component analysis (tICA) as part of the structural clustering facility (→ CCOLLECT and PCAMODE).

COVMODE

This keywords chooses between (currently) two types of raw data to be provided by CAMPARI in output files TRCV_xxx.tmp. It can be set to:

1. Internal degrees of freedom (i.e., torsions) directly in torsional space (radian)
2. Internal degrees of freedom (i.e., torsions) expressed as their cosine and sine components

As alluded to above (COVCALC), more options may be added in the future. In all cases, more documentation is found for TRCV_xxx.tmp.

DIPCALC

This keyword specifies how often to compute molecular and residue-wise dipole moments for net-neutral molecules (or residues). Because the analysis relies on atomic partial charges, dipole analysis requires SC_POLAR to be set to a value larger than zero as charges are otherwise not assigned. The (somewhat preliminary) analysis produces output files MOLDIPOLES.dat and RESDIPOLES.dat. When CAMPARI's shared memory (OpenMP) parallelization is in use, these analyses are executed by a single thread while other threads perform other tasks concurrently (if there are any).

EMCALC

This keyword specifies how often to compute spatial density distributions for the simulated system. If the density restraint potential is in use, this analysis is automatically performed at every step given that it is computed regardless. The result is an averaged density on a three-dimensional grid of dimensions controlled generally by keywords EMDELTAS and SIZE. For nonperiodic boundaries, the evaluation grid is or can not be mapped to the system dimensions exactly, and keyword EMBUFFER becomes relevant. When using the density restraint potential the grid serves both the purpose of analysis as described here, and the purpose of evaluating the potential itself, which implies that it is an option to adopt the grid dimensions from the input density map. This is the default behavior for a cuboid system with 3D periodic boundary conditions when EMDELTAS is not provided.
The resultant spatial density (or densities) is that of a given atomic property selected by keyword EMPROPERTY (which can be more than one). It is written to an output file in NetCDF format, an external library required to use this feature. The details of the file format CAMPARI use are described elsewhere. For a given property X, the spatial density is computed as follows:

ρ_ijk = ρ_sol + V_ijk^-1 Σ_n^N [ X_n - γ_nV_nρ_sol ] Π_d³ B_A ( r_n^d - P_ijk^d )

Here, V_ijk is the volume of the grid cell with indices i, j, and k, N is the number of atoms in the system, X_n is the target property of the atom with index "n", V_n is that atom's volume, and r_n^d are the three components of its position vector. The parameter γ_n is a pairwise, volume overlap reduction factor that corrects atomic volume for overlap with covalently bound atoms. It is explained in some detail elsewhere. The parameter ρ_sol sets a physical background density for the property in question, and this is relevant when not all matter contributing to the property density in the system is represented explicitly. In such a case, an assumed vacuum would lead to severe errors. Note that atomic volumes and volume reduction factors are no longer relevant if ρ_sol is zero in the above equation. Finally, the product in the above equations utilizes cardinal B-spline functions of order "A", B_A, which are assumed centered at the center of each grid cell (vector P_ijk with components P_ijk^d for each dimension). This technique of distributing a property on a lattice is shared with the particle-mesh Ewald method.
Like the corresponding density restraint potential, the accumulation of these data has been parallelized, i.e., when CAMPARI's shared memory (OpenMP) parallelization is in use, all threads work on this task synchronously. If the potential is turned on, there is no additional significant cost; otherwise the grid has to be incremented with the current configuration. Parallel efficiency can suffer in this mode of operation if subsequent snapshots have very different configuration (due to poor load balance). Parallel efficiency is generally poor if the lattices are large (in number of grid cells) relative to the number of atoms.

EMDELTAS

If the density restraint potential is not in use, but spatial density analysis is requested, this keyword is mandatory and sets the lattice cell size of the analysis grid by providing three floating point numbers corresponding to the lattice cell sizes in Å for the x, y, and z dimensions, respectively.
Conversely, if the density restraint potential is in use, this keyword is optional and allows the user to set a lattice cell size different from the one used by the input density map. The keyword again requires the specification of three floating point numbers that set the lattice cell sizes in Å for the x, y, and z dimensions of the analysis and evaluation grid, respectively. Note that acceptable choices require that it be possible to superpose the cells of the input density map exactly with the analysis grid after reducing its resolution to that of the input map. Minor adjustments may be made automatically to system size and/or the origin of the input map. If, for example, in the x-dimension the input map has 10 cells of width 2Å, and the evaluation grid has 26 cells of width 1Å, then the system origin has to be chosen such that the left boundary of the first cell of the input density aligns with the left boundary of the first, third, or fifth cell of the evaluation grid (but not any others). In the same example, CAMPARI would reject a system size of 25Å, because the resultant number of cells in the x-dimension would not be divisible by the integer factor corresponding to the differences in resolution (here 2). It would also reject an origin aligning the first input cell to the seventh evaluation grid cell, because this would mean that the input map extends beyond the system boundaries. Finally, implied boundary conditions of the input map are not made to correspond to system boundary conditions automatically. For any periodic boundaries of the system, the evaluation grid is and must be fit exactly to the system dimensions. The grid is the same for all properties being analyzed.

EMPROPERTY

If spatial density analysis is requested, or if the density restraint potential is in use, this keyword lets the user pick an atomic property to be distributed on a lattice. The options are as follows:

1. Use atomic mass (resultant units are g/cm³).
2. Use atomic number, i.e., proton mass (resultant units are also g/cm³ for convenience).
3. Use atomic charge (resultant units are e/ų) relying on the parameters read-in from parameter file and used in the Coulomb potential, the use of which is required.
4. Use a custom property (resultant units are a.u./ų) relying on a custom custom input file. This is the only option that allows the use of more than one density to be collected and/or restrained. The presence of more than one property means that certain keywords should take multiple input values, notably FMCSC_EMTHRESHOLD, FMCSC_EMTOTMASS, FMCSC_EMTRUNCATE, FMCSC_EMBGDENSITY, FMCSC_EMBACKGROUND, and FMCSC_EMFLATTEN.

Note that the density calculation is controlled by formal grid resolution and by the function used to represent the point property or properties in question. If there is an assumed nonzero physical background level, the effective atomic volumes become relevant as well.
It is important to realize that properties that can take both negative and positive values (like partial charge) must be and are treated slightly differently from those that are positive definite (like mass). This is because the interpretation of the input map must sometimes consider the absolute value of the property to arrive at a meaningful interpretation of the parameters for total integral, threshold level, and truncation level.

EMBGDENSITY

If spatial density analysis is requested, or if the density restraint potential is in use, this keyword sets an assumed background level for the atomic property or properties in question. This means that, if EMPROPERTY is 4, more than one value may be required (on the same line). In general, background densities should be zero if all relevant matter in the system is represented explicitly, i.e., if empty space is indeed meant to correspond to a vacuum. If not, for example if the background is supposed to capture contributions from solvent molecules not represented explicitly, the values should be given in appropriate units depending on the property that the density is derived from. These are g/cm³ for mass and proton densities (atomic number), e/ų for charge, and arbitrary for custom properties. Note that the assumed background can also be zero for other reasons, e.g., the average charge density of an implicit net-neutral solvent buffer zero.

EMPROPERTYFILE

If spatial density analysis is requested, or if the density restraint potential is in use, this keyword lets the user specify the path and name of a custom input file to supply values for arbitrary atomic properties to CAMPARI, of which to calculate and possibly restrain their spatial densities (see option 4 for EMPROPERTY). The details of the input format and the consequences of choosing more than one property are described elsewhere.

EMBUFFER

If spatial density analysis is requested, or if the density restraint potential is in use, this keyword sets a ratio for how much to extend the evaluation grid for spatial densities beyond any nonperiodic boundaries of the system. In the direction of a nonperiodic boundary, CAMPARI takes the maximum dimension (e.g., the diameter of a sphere) and multiplies it with this factor to obtain the (approximate) size of the rectangular cuboid grid. Alignment with a potential input grid is achieved by shifting the origin of the evaluation grid slightly. Note that the behavior will generally be undefined for cases where solute material samples positions off the evaluation grid. It is up to the user to ensure that the buffer spacing is big enough for the stiffness of the boundaries to prevent this from happening. This is particularly problematic in Monte Carlo simulations with large-scale moves such as rigid-body moves of the randomizing kind. In such a case, a trial conformation might have to be evaluated that extends significantly beyond the boundary. Even though, this move will almost certainly be rejected on accord of the boundary, the density restraint potential might create nonsensical answers, which is to be avoided. By default, all solute coordinates are periodically wrapped onto the analysis/evaluation grid even with a nonperiodic boundary (because no algorithms are implemented that deal with explicit grid edges in terms of B-splines, etc). This is always undesirable in a nonperiodic boundary. In extreme cases (molecules protruding more than one side length from the box, warnings are produced.

EMBSPLINE

If spatial density analysis is requested, or if the density restraint potential is in use, this keyword sets the order of B-splines used to distribute the one ore more atomic properties of interest on the lattice. This setting corresponds to parameter "A" in the equation above. B-splines of order 3 or higher lead to functions with smooth derivatives, and are appropriate for gradient-based methods. B-splines have finite support, and the cost per atom will increase with A³ for a three-dimensional lattice. The limiting case of A being unity corresponds to a simple binning function, whereas for large A, a Gaussian function is recovered. The effective width does not grow linearly with A, but it is rather the tails of the functions that grow. This implies that very large values for A are probably not a useful investment of CPU time. Note that the effective width of the B-spline can be thought of as setting an inherent resolution or averaging scale for a given atom in question, since it replaces a point function with a distribution. The choice for this keyword should therefore be made in concert with the choice of formal grid resolution.

DIFFRCALC

This keyword specifies how often to compute approximate fiber diffraction patterns for the whole system (excluding ghost particles in GC simulations → ENSEMBLE). The system is aligned according to an assumed fiber axis in the system (see DIFFRAXIS), and amorphous diffraction patterns using cylindrical coordinates (through Fourier-Bessel transform) are computed. The code currently assumes atomic scattering cross sections which are proportional to atomic mass with the additional modification that all hydrogen atoms are excluded from the diffraction calculation. Specifically, the atomic scattering function for heavy atom i is proportional to m_i/m_C with a proportionality constant yielding units of the square root of scattering intensity. It is zero for hydrogen atoms. See DIFFRACTION.dat for more details. As a cautionary comment it should be noted that these calculations are somewhat untested and that output should be carefully examined. When CAMPARI's shared memory (OpenMP) parallelization is in use, the diffraction pattern is calculated by a single thread while other threads perform other tasks concurrently (if there are any). This is a limitation because of the high inherent cost of this analysis.

DIFFRRMAX

For diffraction calculations (→ DIFFRCALC), this specifies the maximum number of bins in the reciprocal radial dimension (r in cylindrical coordinates). The resultant bins will be centered around zero.

DIFFRZMAX

For diffraction calculations (→ DIFFRCALC), this specifies the maximum number of bins in the reciprocal axial dimension (z in cylindrical coordinates). The resultant bins will be centered around zero.

DIFFRRRES

For diffraction calculations (→ DIFFRCALC), this gives the resolution in the reciprocal radial dimension (r in cylindrical coordinates) in Å^-1.

DIFFRZRES

For diffraction calculations (→ DIFFRCALC), this gives the resolution in the reciprocal axial dimension (z in cylindrical coordinates) in Å^-1.

DIFFRJMAX

This defines the maximum order of Bessel functions to use in the Fourier-Bessel (Hankel) transform to generate the (fiber) diffraction pattern (→ DIFFRCALC). Note that the transform takes the product of actual and reciprocal radial coordinate as its argument. Hence, the maximum order will determine how meaningful the generated information for large values of inverse radial dimensions is. This soft cutoff will scale reciprocally with the size of the system in the radial dimension. These features arise due to the fact that Bessel functions of order n only contribute non-zero values beyond a (unitless) argument value of ca. n. Also note that the input file for the Bessel functions (see FMCSC_BESSELFILE) needs to provide the tabulated functions up to the necessary order.

DIFFRAXIS

For diffraction calculations (→ DIFFRCALC), it is possible (and usually meaningful and necessary) to use a fixed system axis as the assumed fiber axis. This is (naturally) particularly appropriate for single-point calculations on specific structures. The axis' x, y, and z components have to be provided as three floating point numbers. The length of the vector is not important. The axis will pass through the point defined (see DIFFRAXON). If this keyword is not specified, the program will identify the longest possible atom-atom distance in the system, and use the resultant axis. Note that this axis will not be constant with respect to the absolute (lab) coordinates, but that it is supposed to cover cases where changes in configuration are allowed (especially if rigid-body movement is permitted).

DIFFRAXON

This keyword specifies the point the (constant) axis (see DIFFRAXIS) for diffraction analysis (→ DIFFRCALC) will pass through. This will define the zero-point in the z-coordinate, and hence the origin of the cylindrical coordinate system. If this keyword is not provided, CAMPARI will assume the {0.0 0.0 0.0}-point for this (independent of specifications for the system origin).

REOLCALC

This keyword is only relevant in MPI replica exchange calculations (or parallel trajectory analysis runs using the same setup). It instructs CAMPARI to compute various overlap measures between the different Hamiltonians employed in the REMC/D run (see N_XXX_OVERLAP.dat). Note that this relies on the evaluation of the system energy at different conditions, i.e., Hamiltonians. Unless the only exchange dimension is temperature, CAMPARI makes the assumption that the energy has to be fully reevaluated for each condition, which means that there is a significant cost associated with the overlap calculation. Cutoffs and long-range corrections (see keywords CUTOFFMODE, LREL_MC, and LREL_MD) are always respected by these additional evaluations of cross- (or foreign) energies. In dynamics runs, an additional complication arises if neighbor list updates are performed infrequently (see NBL_UP). Here, CAMPARI enforces an extra update of neighbor lists that is always out-of-sync with the schedule of the simulation propagation (this is for technical reasons). The unfortunate consequence is that for identical random seed, trajectories are not going to be identical if NBL_UP is greater than 1 and overlap calculations are performed with different frequencies.
The user controls whether to calculate foreign energies across all replicas (see REOLALL). If only neighboring conditions are requested, output in N_XXX_OVERLAP.dat may be truncated or uninformative. It is important to mention that the MC branch of the energy functions is used only in plain REMC calculations, and that in all other cases (including hybrid methods → DYNAMICS) the dynamics branch is used. This is important since cutoff and long-range treatments can easily be inconsistent between the two (see LREL_MC and LREL_MD). Because the main cost of the overlap calculation is the evaluation of "foreign" energies, CAMPARI's shared memory (OpenMP) parallelization can employ its full parallelization scope for this task.

REOLINST

This keyword is only relevant in MPI-Replica Exchange calculations (or parallel trajectory analysis runs using the same setup). This keyword requests instantaneous "foreign" energies to be written (see N_XXX_EVEC.dat). "Foreign" or "cross"-energies are simply the energies of the current structure evaluated at Hamiltonians different from the one generating the ensemble. Note that the user controls whether to calculate foreign energies across all replicas (see REOLALL). If only neighboring conditions are requested, a truncated vector (length 2 or 3) is provided in N_XXX_EVEC.dat. To facilitate frequent overlap analysis with sparser instantaneous output, this keyword is interpreted as a subordinated frequency for REOLCALC (as SCATTERCALC is relative to RHCALC).

REOLALL

This keyword is only relevant in MPI-Replica Exchange calculations (or parallel trajectory analysis runs using the same setup). It is interpreted as a simple logical which determines whether "foreign" energies are computed over all other or just the neighboring replicas (see N_XXX_EVEC.dat and N_XXX_OVERLAP.dat).

TRACEFILE

This optional keyword is relevant for the post-processing of two types of parallel simulation runs. First, if a parallel trajectory analysis run in the RE setup is performed (→ details elsewhere), it allows the user to supply a file with a running map of replicas to starting conditions. Details of format and interpretation are given elsewhere. The default map assumed by CAMPARI is the identity mapping 1..REPLICAS. If a trace file is provided, sets of step number and an updated map for that specific step are read. This is primarily meant to make replica exchange trajectories that are continuous in condition (i.e., have conformational jumps in them) continuous in conformation (i.e., afterwards they have jumps in condition in them). In such a case, the trace file is the history of replica exchange moves such as output by CAMPARI itself. CAMPARI will then recombine information from the input trajectories according to the trace. This means that all analyses performed are on the unscrambled trajectory that can of course also be written (→ XYZOUT). Naturally, this keyword can also be used to specify any other map for other applications, e.g., to create trajectories for obtaining bootstrap-type error estimates. The relation of step numbers in the trace file to frames in the trajectories is handled by keywords RE_TRAJOUT and RE_TRAJSKIP.
Second, if a serial trajectory analysis run or a parallel trajectory analysis run using the MPI averaging framework is performed, it can be used to post-process data from an parallel PIGS run. PIGS runs provide their own trace file. For the serial analysis, the trajectories from individual replicas must be concatenated in numerical order, otherwise they should be left as is. Unless the trace file itself is edited (its first column has the step number), keywords RE_TRAJTOTAL, RE_TRAJOUT, and RE_TRAJSKIP define the output settings for the original simulation run, and the settings must be matched exactly. For example, with 4 replicas, XYZOUT 50, NRSTEPS 1000, and EQUIL 500, each trajectory will have 10 snapshots. In trajectory analysis mode, the concatenated trajectory (40 snapshots) can then be supplied with settings of RE_TRAJTOTAL 10, RE_TRAJOUT 50, RE_TRAJSKIP 500, and NRSTEPS 40. Alternatively, the set of individual trajectories can be supplied to a parallel analysis run using NRSTEPS as 10 instead. The trace file is processed exclusively in the context of network-based analyses (see CCOLLECT, CMODE, output file STRUCT_CLUSTERING.graphml, and so on). Reading in the PIGS trace accomplishes the automatic removal and addition of (conformational) network links incurred by the PIGS protocol. Overlapping functionality is provided by keywords TRAJBREAKSFILE and TRAJLINKSFILE, but these are only available in serial analysis mode. If appropriate geometric information is present, this function will also produce an output file containing snapshots weights for the PIGS runs estimated by the weighted ensemble strategy (see dcoumentation for the corresponding output file for details). Note that a PIGS analysis run (see elsewhere for details) does of course not process the PIGS trace as it emulates the behavior of only a single PIGS stretch (reseeding interval). The presence of this keyword in the input key file is explicitly not allowed (results in a halt of the execution) if operating the NetCDF analysis mode.

RE_TRAJOUT

This keyword is relevant for some trajectory analysis runs. In particular, those runs relying on an input file with the reseeding/exchange history of a parallel simulation run need to translate the information about step numbers in this file to the analyzed data. This keyword therefore lets the user set the trajectory output frequency CAMPARI is supposed to assume for the supplied input trajectories (separate or concatenated) being analyzed. This is important because the trace is meant to use simulation step numbers that are not preserved in trajectory analysis mode (no step number or time information from input trajectories are read and used).
If a parallel analysis run in the replica exchange setup run is performed, a successful unscrambling of the trajectories requires that the exchange trace is exhaustive at the level of the output frequency of this keyword. This means that it is sufficient to provide the current map of condition to starting structure for every snapshot in the input trajectories (more information can be supplied without harm, less information will lead to errors). In the replica exchange case, keyword RE_TRAJSKIP is also essential. If an analysis run on a PIGS data set is performed (possibly in parallel), the trace must contain information about all reseedings. Here, both keywords RE_TRAJSKIP and RE_TRAJTOTAL are processed as well.
Unlike in the cases outlined above, which are both related to processing a trace file, this keyword attains a different function in a parallel PIGS analysis run. Since such a run is supposed to emulate the PIGS heuristic, it serves as an output control setting to compute the step number as RE_TRAJTOTAL times RE_TRAJOUT, which is then printed to the output trace file.

RE_TRAJSKIP

This keyword is relevant for some trajectory analysis runs. In particular, those runs relying on an input file with the reseeding/exchange history of a parallel simulation run need to translate the information about step numbers in this file to the analyzed data. This keyword therefore lets the user set the equilibration period for trajectory output that CAMPARI is supposed to assume for the supplied input trajectories (separate or concatenated) being analyzed. This is important because the trace is meant to use simulation step numbers that are not preserved in trajectory analysis mode (no step number or time information from input trajectories are read and used).
Both RE_TRAJOUT and this keyword are required for CAMPARI to correctly relate the frames in the trajectories to the step numbers in the trace file. Of course, it is also possible to edit the file with the trace to match the saved trajectory data exactly, and to then set RE_TRAJOUT and RE_TRAJSKIP to 1 and 0, respectively. In the case of a PIGS run being analyzed, keyword RE_TRAJTOTAL is also essential.

RE_TRAJTOTAL

If a serial trajectory analysis run or a parallel trajectory analysis run is performed and a file with the PIGS reseeding history (trace) has been provided, this keyword lets the user set the length in numbers of snapshots per replica that CAMPARI is supposed to assume for the trajectory input (→ elsewhere). In the serial case, this is usually NRSTEPS/REPLICAS whereas in the parallel case it is just NRSTEPS. This is important because the trace is meant to use simulation step numbers that are not preserved in trajectory analysis mode (no step number or time information from the input trajectory is read and used). RE_TRAJOUT, RE_TRAJSKIP, and this keyword are required for CAMPARI to correctly relate the frames in the trajectories to the step numbers in the trace file. Note that when using an input file with subsets of frames in random-access mode this keyword has to be adjusted to the actual number of selected frames per replica, which still has to be constant.
Unlike in the processing of a trace file, this keyword attains a different function in a parallel PIGS analysis run. Since such a run is supposed to emulate the PIGS heuristic, it serves as an output control setting to compute the step number as RE_TRAJOUT times RE_TRAJTOTAL, which is then printed to the output trace file.

CCOLLECT

This keyword controls the frequency with which a selected set of features (see CDISTANCE and CFILE) extracted from the trajectory data (typically in a trajectory analysis run → PDBANALYZE) is stored in a large array in memory for post-processing. Such post-processing currently consists of different algorithms (→ CMODE), for example to identify structural clusters in the data, and is performed after the last step of the run has completed. If CCOLLECT is set to something larger than the number of simulation steps (NRSTEPS), the clustering analysis is disabled (also the default).
Various output will be produced aside from information written directly to standard out or the log-file. At the most basic level, the extracted features themselves, after the various preprocessing steps outlines below, can be written to disk in an optional output file (see CLUSTERING_FEATURES.nc and keyword CDUMP). The most common output file is a list of cluster annotations per analyzed snapshot (→ STRUCT_CLUSTERING.clu) that is produced along with a helper script for the visualization software VMD (→ STRUCT_CLUSTERING.vmd). Furthermore, CAMPARI will print a file representing the clustering as a graph in an xml-based (so-called "graphml") format (→ STRUCT_CLUSTERING.graphml). Taken together these files allow further analyses of the clustering, primarily those that take advantage of the fact that the clustering yields a complex network/graph (e.g., cut-based free energy profiles using committor probabilities).
All clustering algorithms and also the progress index algorithm (→ CMODE) will write a number of diagnostic and reporting summaries to log-output. For clustering algorithms, this includes a summary of the determined clusters (usually involving at least the number of contained snapshots and a measure of size) to log-output. The exact progress index method is an exception as it does not explicitly record a clustering (the three aforementioned output files are missing). With any progress index method in use, at least one additional output file is obtained. This file is the essential requirement to create plots as in the progress index reference.
Note that structural clustering breaks the typical CAMPARI paradigm of "on-the-fly" analysis since the bulk of the CPU time for analysis will be invested only at the very end. Therefore, structural clustering will most often be used in trajectory analysis runs as it will be highly undesirable to risk an unclean termination of an actual simulation (certain algorithms for structural clustering require large amounts of memory and/or CPU time). Note as well that structural clustering should not be confused with the (much simpler) analysis of molecular clusters (see CLUSTERCALC and its corresponding output files). Because structural clustering and related analyses can be CPU time-intensive tasks, they are handled by CAMPARI's shared memory (OpenMP) parallelization, i.e., many algorithms are tackled by all threads at once. Most importantly, the tree-based clustering and the approximate progress index method (options 4 and 5 to keyword CMODE) as well as iterative algorithms operating on derived graphs (see MAXTIME_ITERS for details) have been parallelized this way, Details are provided below, in particular for keyword CMODE.
A special remark is required for simulation runs using the MPI averaging technique. Similar to any use of the clustering functionality "on-the-fly", trajectory output should be generated in accordance with the setting for CCOLLECT (most easily by using MPIAVG_XYZ and a matching value of XYZOUT). This is so the clustering results can be annotated and understood at all. In an MPI averaging run, CAMPARI will then at each collection step gather data from all replicas and store them in an array allocated exclusively by the master process. The data arrangement is such that trajectories will be continuous and ordered by increasing replica number. The concatenation introduces spurious transitions that may affect subsequent computations. Data collection causes a synchronization and communication requirement absent in other types of MPI averaging calculations. At the end of the simulation, the resultant concatenated trajectory is analyzed exclusively by the master process, which - depending on settings and algorithms in use - may lead to severe imbalances in terms of both memory consumption and CPU time requirements. This should be kept in mind when using this approach across machines not sharing any memory. To enforce the complementary behavior of every identical replica analyzing its own trajectory, it is possible to use a fake replica exchange run by using a single dummy (or irrelevant) parameter for exchange. In a hybrid MPI/OpenMP calculation, the OpenMP layer on the master process performing the analysis will be limited to the number of threads granted initially even though other MPI processes residing on the same shared-memory environment will be idle during this time. Note that the feature extraction itself, which is the only task performed during the run, does not benefit from threads parallelization except for the calculation of dynamic weights for options 2 or 4 for keyword CDISTANCE. Conversely, feature extraction in parallel does occur in an MPI averaging run as outlined above.
Because the chosen set of degrees of freedom often is a superset of an unknown subspace of particular interest to the user, CAMPARI offers two common routes for a dimensionality reduction. These rely on standard linear algebra techniques and are available if i) the chosen proximity metric is not circular (this excludes options 1-2 for CDISTANCE); ii) the code was linked to a linear algebra library (LAPACK-compliant, see installation instructions for general information on linking libraries); and iii) there are more samples than variables (degrees of freedom). The reason that circular (periodic) data are currently not supported is that the required measures of variance and in particular covariance become somewhat empirical and laborious to compute. If this type of transformation is performed (→ PCAMODE), CAMPARI produces up to two output files, one containing the eigenvectors themselves (PRINCIPAL_COMPONENTS.evs) and another optional one containing the data matrix in the transformed space (PRINCIPAL_COMPONENTS.dat). The latter can be used to derive probability or free energy surfaces in reduced-dimensional spaces.

PCAMODE

If data for structural clustering are collected (→ CCOLLECT), this keyword instructs CAMPARI to calculate and perform a linear transformation on the collected data. As mentioned above, this option is not available for all measures of conformational distance. The linear algebra works straightforwardly for options 3 and 7 for keyword CDISTANCE and always involves centering the data first (subtraction of dimension-wise means). For options 4, 9, and 10 (local weights), the locally adaptive weights are averaged, and the input data are scaled by dimension-wise average weights. The same scaling idea is used for option 8 (global weights). Lastly, the possibility of alignment of 3D coordinates (options 5, 6, and 10 → CALIGN) causes additional complications. The general strategy here is to first align all snapshots to the last one (static alignment), which may or may not be provide a meaningful description.
Five options are currently available:

1. No transformation is performed
2. Principal component analysis (PCA) is performed via single-value decomposition (SVD), and the eigenvectors of the covariance matrix are written to a dedicated output file. PCA works by identifying linear transforms of the centered data that collect maximal sample variance in as few components as possible. The principal components are normalized and orthogonal, i.e., have unit length and zero (linear) covariance. The latter should not be equated with a lack of correlation. Many nonlinear correlations between variables yield zero covariance. The amount of variance contained in the first few components can differ dramatically between data sets. The printed eigenvectors and eigenvalues are the only result of this analysis, i.e., the transform is not actually used.
3. This is the same as the previous option with an important difference. Here, the original sample data are transformed and centered data in PCA space. The transformed data set is written to an additional output file. If keyword CREDUCEDIM is not zero, the original data are overwritten and lost, and any algorithm relying on conformational distance evaluations thereafter will treat these as the simplest case (CDISTANCE becomes 7). This is because the weighting or alignment requests were taken care of before. The benefit of using CREDUCEDIM is to be able to obtain a more informative representation in a space of reduced dimensionality in an unsupervised fashion.
4. Time structure-based independent component analysis (tICA) is performed, which is based on original work from the 90s. tICA solves the matrix equation ΤF=ΣFΛ, where Σ is the covariance matrix, Τ is a time-lagged and symmetrized covariance matrix (lag time is set by keyword CLAGTIME), F is the matrix of eigenvectors, and Λ is a diagonal matrix with eigenvalues, which correspond to the values of the autocorrelation function at the specified lag time for the transformed variables. Unlike in PCA, the eigenvectors do not form an orthonormal basis (rather, they satisfy F^TΣF=I_D). This means that unlike PCA the transformed data do not preserve values of Euclidean distances between points even if the full dimensionality is used. As in option 2, the printed eigenvectors and eigenvalues are the only result of this analysis, i.e., the transform is not actually used.
5. This is the same to option 4 as option 3 is to option 2, i.e., the original sample data are transformed to tICA space and centered with the aforementioned options, implications, and consequences.

The default option is 1. Note that options 3 and 5 can generate extremely large output files. The use of options 3 and 5 in conjunction with locally adaptive weights entails the additional complication of when and how weights should be normalized. In contrast to what is described in the reference publications (see here), the weights are now normalized per snapshot before the average per dimensions is computed (which will typically cause only minor differences). While PCA is performed via SVD of the data matrix, the covariance matrices are computed explicitly for tICA, which scales unfavorably with dimensionality. As mentioned above, when choosing options 3 or 5, CAMPARI also offers to perform a simplified clustering in a space of reduced dimensionality (→ CREDUCEDIM). Supplying data dimensions that are linearly dependent on other dimensions or have zero variance may cause the analysis to fail, in particular for tICA. An unusual exit from the respective LAPACK routine will be indicated by a warning. If CAMPARI's shared memory (OpenMP) parallelization is in use, the linear transform is (currently) calculated and applied by the master thread alone.

CDISTANCE

If data for structural clustering are collected (→ CCOLLECT), this keyword defines what type of data to collect and how to define structural proximity. There are currently 10 supported options:

1. This option is tailored toward the intrinsic degrees of freedom of a typical CAMPARI simulation that are also the essential internal degrees of freedom of most molecular systems, i.e. the molecules' dihedral angles. The values {φ_k} for a set of K dihedral angles are collected throughout the run. A list can be provided by using a dedicated input file (→ CFILE), otherwise most of CAMPARI's internal degrees of freedom are used (excluding those pertaining to the conformation of five-membered rings). The details of the set of eligible dihedral angles are controllable by keyword TMD_UNKMODE. More information can be found in the description of the input file. The distance between two states is given as:
   d_l↔m = [ (1.0/K) · Σ_k^K ( (φ_k^l - φ_k^m) mod 2π )²]^1/2
   Because dihedral angles are periodic (circular) quantities, a meaningful metric of proximity must account for boundary conditions, hence the "mod 2π" term. Dihedral angles-based clustering poses - aside from periodicity - the challenge that all considered degrees of freedom are bounded and that the strongest contribution to the signal will come from those torsions with large variance, which unfortunately are often the ones of least interest (for example sidechain torsions). Therefore, a careful selection of the subset to use is critical for an informative clustering. Like any other method, dihedral angle-based clustering is vulnerable to Euclidean distances in high-dimensional spaces becoming uninformative. Note that all dihedral angle-based proximity criteria are useful primarily for single molecules since relative intermolecular orientations are not representable whatsoever.
2. This is identical to the previous option only that each dihedral angle is also associated with a locally adaptive weight. Adaptive weights are those that change from snapshot to snapshot. Initially, the weights for this representation are set to the effective masses (the associated diagonal element in the mass matrix, i.e., mass-metric tensor) of a given dihedral angle. Evaluating a distance requires combining these adaptive weights for 2 respective snapshots l and m, e.g. w_k^lm = f(IM_k^l,IM_k^m). The distance between two states will then be given as:
   d_l↔m = [ (Σ_k^K w_k^lm ) ^-1 · Σ_k^K w_k^lm · ( (φ_k^l - φ_k^m) mod 2π )²]^1/2
   The actual values for the weights for individual snapshots, e.g., IM_k^l, can be altered using keyword CMODWEIGHTS. The function for combining the weights to yield w_k^lm is selected with the help of keyword CWCOMBINATION. Adaptive weights are generally normalized per snapshot (such that Σ_k^K IM_k^l evaluates to 1.0 for all l). This is different from what is described in 2 reference publications (see here and here). Any type of weighting scheme (static or adaptive) can be used to remedy the problem with the previous one regarding the impact of "uninteresting" degrees of freedom. The weighting with the effective masses ensures that slow degrees of freedom (e.g. central backbone torsions) will contribute much more to the overall signal than sidechain torsions. This effect becomes exacerbated for long chains. There are two additional caveats. First, the initial mass matrix-based weights are affected by the choice for ALIGN. Second, Dihedral angles describing disulfide bonds are supported but the presence of disulfide bonds destroys the notion of the effective masses (see CRLK_MODE for some background). The default weights for the C_α-C_β-S-S and C_β-S-S-C_β torsions are simply set to 1.0. This means that a meaningful use of this option while selecting disulfide bonds as part of the representation requires setting CMODWEIGHTS to something other than 0.
3. This option is largely identical to option 1. It carries all the same caveats with the exception of the periodicity of dihedral angles. Here, we expand each dihedral angle into its sine and cosine terms to construct a distance metric as follows:
   d_l↔m = [ (0.5/K) · Σ_k^K (sin(φ_k^l) - sin(φ_k^m))² + (cos(φ_k^l) - cos(φ_k^m))²]^1/2
   Note that the sine and cosine terms of the same angle are nonlinearly but strictly correlated. This has consequences for the interpretation of dimensionality in this representation.
4. This is the analogous modification of the previous option by introducing locally adaptive weights that are initially composed from the effective masses and can be altered by keyword CMODWEIGHTS:
   d_l↔m = [ 0.5 (Σ_k^K w_k^lm) ^-1 · Σ_k^K w_k^lm · ( (sin(φ_k^l) - sin(φ_k^m) )² + (cos(φ_k^l) - cos(φ_k^m) )² ) ]^1/2
   Note that this implies the presence of only a single weight per pair of Fourier terms.
5. This option is probably the most commonly used variant, the positional RMSD. The Cartesian position vectors {r_k} for a set of K atoms are collected throughout the run. A list can be provided by using a dedicated input file (→ CFILE), otherwise all atoms in the system are used. The distance between two states is then given as:
   d_l↔m = [ (1.0/K) · Σ_k^K ( r_k^l - RoTr(r_k^m) )²]^1/2
   Here, RoTr is meant to indicate rotation and translation operators that superpose the {r_k}^m optimally with the frame provided by the {r_k}^l. This alignment uses the same quaternion-based algorithm mentioned elsewhere. Superposition (alignment) implies that the atomic RMSD is not necessarily a bona fide metric of distance as it is not guaranteed to satisfy d_l↔m ≤ d_l↔p + d_p↔m, i.e., the triangle inequality. This is because the operator RoTr is different for computing d_p↔m than it is for computing the other two distances. In reality, for similar structures, this is never really a problem in the context of clustering. RMSD-based clustering is - like any other method - vulnerable to Euclidean distances in high-dimensional spaces becoming uninformative and - in particular - to obscuring of the signal by uneven variances (a reason why very commonly terminal parts of polymer are excluded from such analyses). The alignment step for both this and the next option can be disabled with the help of keyword CALIGN (RoTR is then simply the identity operator). Without alignment external degrees of freedom become part of the distance criterion. The coordinate-based RMSD is generally difficult to use for sets of atoms spanning multiple molecules since intermolecular motion can easily provide most of the variance in the signal. In periodic boundary conditions, there is a particular difficulty of which image of a molecule to use. Keyword XYZ_REFMOL is supported in this context and can be use to circumvent this problem (although it should be kept in mind that there is no unique solution for assemblies of more than 2 molecules).
6. This is similar to the previous option, and is only relevant if alignment is performed. Then, this option allows the user to split the atomic index sets used for alignment and distance computation, i.e., the alignment operator, RoTr, minimizes pairwise distances computed over an independent set of atoms that can either be a superset, subset or completely different set of atoms than the one specified via CFILE. Then, if we term the distance set {D} and the alignment set {A}, with {A} to be provided via ALIGNFILE, the distance between two states will be given as:
   d_l↔m = [ (1.0/|D|) · Σ_d^|D| ( r_d^l - RoTr_{A}(r_d^m) )²]^1/2
   Note that choosing disparate sets can easily destroy the fundamental meaning of alignment, i.e., the removal of differences caused purely by external (rigid-body) degrees of freedom. This in turn would almost certainly lead to violations of the assumption that members of different clusters are dissimilar, and can also eliminate the notion of similarity amongst members of the same cluster. Conversely, it can be useful in improving the signal-to-noise ratio for cases where one is interested in states populated by a specific part of a much larger system that moves as a single entity (specifically, states characterized by relative arrangements of parts of a system may emerge more clearly if alignment is performed on the whole entity, but distances are computed only over a small portion of interest). Note that errors in calculations relying on mean cluster properties computed for example in the tree-based algorithm or hierarchical clustering (→ CMODE) using mean linkage can easily become large if the two atom sets have little overlap. Specifically, a cluster of similar snapshots as determined by the distance set, which is constituted by elements with large differences in the alignment set, will produce deteriorating accuracy of, for example, computing a snapshot's mean distance to it. This is because the heterogeneity of the alignment operator is masked by the simplified algebra used to compute these properties in constant time. The general caveats for RMSD-based clustering mentioned for option 5 above remain relevant as well.
7. Let us define a set of K interatomic distances, {r_ij} over unique atom pairs i and j. These distances are collected throughout the run. A list can be provided by using a dedicated input file (→ CFILE), otherwise a subset of randomly selected but unique interatomic distances is used. The number of randomly selected degrees of freedom is usually set to 3N where N is the number of atoms (it can be smaller for small N). Because the {r_ij} are geometric distances, they are also positive and potentially large. CAMPARI allows a functional transform to be applied during data collection to, which, generally speaking, allows focusing the sensitivity to particular distance regimes. If we consider this transformed set of distances, {f(r_ij)} (f(x) can be the identity function of course, which is also the default), the distance between two states will then be given as:
   d_l↔m = [ (1.0/K) · Σ_k^K [ f(r_ij(k)^l) - f(r_ij(k)^m) ]²]^1/2
   I.e., the chosen distance metric is simply the root mean square deviation across the set of transformed interatomic distances. Distance-based clustering inherently removes external degrees of freedom from the proximity measure, and it is therefore suitable to most applications. As with any other measure, Euclidean distances in high-dimensional spaces may become uninformative and results may be obscured by uneven variances.
8. This is identical to the previous option only that each distance, which is potentially transformed, is subjected to a static weight. This weight is computed initially from the combined mass of the constituting atoms. The distance between two states would then be given as:
   d_l↔m = [ (Σ_k^K (m_i(k)+m_j(k)) ) ^-1 · Σ_k^K (m_i(k)+m_j(k)) · [ f(r_ij(k)^l) - f(r_ij(k)^m) ]²]^1/2
   Here, m_i denotes the mass of atom i, and f(x) is the function used for transformation (defaults to the identity function). These (static) weights are not particularly useful in the default form but can be altered by changing masses, e.g., by a suitable patch, or by means of the dedicated facility (keyword CMODWEIGHTS). They are normalized such that similar distance thresholds can be used as in the unweighted case.
9. This is identical to option 7 above only that each interatomic distance, which is potentially transformed, is subjected to a locally adaptive weight (as in options 2 and 4 above). These weights increase the corresponding memory demands by a factor of 2 and are all initialized to be unity. It is necessary to use the dedicated facility (keyword CMODWEIGHTS) to make them meaningful. All localized weights available for interatomic distances require at least a window size parameter and a rule for how to combine weights from different snapshots. The latter is expressed as function g(x1,x2) specified by keyword CWCOMBINATION. The resultant functional form for pairwise distance between snapshots is:
   d_l↔m = [ (Σ_k^K g(Ω_k^l,Ω_k^m) ) ^-1 · Σ_k^K g(Ω_k^l,Ω_k^m) · ( [f(r_ij(k)^l) - f(r_ij(k)^m) ]² ) ]^1/2
   Here, Ω_k^l is the locally adaptive weight for the k^th feature and the l^th snapshot, and f(x) is the function used for transformation (defaults to the identity function). The same general caveats apply as for options 2 and 4 above. In particular, it is important to reemphasize that all locally adaptive weights are now normalized per snapshot in contrast to the descriptions found in the literature (see here and here).
10. This is similar to options 5 and 9 above. Here, each of the 3K Cartesian coordinates, X, of a system of K selected atoms is subjected to a separate, locally adaptive weight. Due to the presence of these weights, pairwise alignment is currently not supported for this option. CAMPARI computes the Euclidean distance between snapshots, which means that any type of input data can be analyzed straightforwardly by transcribing the data set into a fake trajectory of atoms with each Cartesian coordinate corresponding to an input data dimension. The locally adaptive weights increase the corresponding memory demands by a factor of 2 and are all initialized to be unity. It is necessary to use the dedicated facility (keyword CMODWEIGHTS) to make them meaningful. As for option 9, weights require at least a window size parameter and a rule for how to combine them for different snapshots. The latter is expressed as function g(x1,x2) specified by keyword CWCOMBINATION. The resultant functional form for pairwise distance between snapshots is:
    d_l↔m = [ 3(Σ_k^3K g(Ω_k^l,Ω_k^m) ) ^-1 · Σ_k^3K g(Ω_k^l,Ω_k^m) · ( (X_(k)^l - X_(k)^m )² ) ]^1/2
    For the weighting aspect, the same caveats apply as for options 2, 4, and 9 above. Due to the distance definition relying on absolute coordinates, the caveats mentioned for option 5, which relate to atoms sets encompassing multiple molecules, remain relevant as well.

The CAMPARI units for options 1-2 above are °, while the units for options 5-10 are all Å (more generally, in trajectory analysis mode, the units for options 5-10 will be those of the input data). This is relevant in understanding values of cluster sizes and similar parameters reported to standard log-output. Options 3-4 have no formal unit.

CFILE

If data for structural clustering or related analyses are to be collected (→ CCOLLECT), this keyword provides the path and location to an input file selecting a subset of the possible coordinates. For options 1-4 of the proximity measure, this file is a single column list of indices specifying specific system torsions (see elsewhere). For options 5, 6, and 10 it is a single column list of atomic indices (see elsewhere). Lastly, for options 7-9, it is a list of pairs of atomic indices (two columns, see elsewhere). The keyword can take on an additional meaning if instantaneous output of RMSD values is requested through ALIGNCALC. In this context, CFILE specifies an atomic index set as for option 6 of CDISTANCE. In a small molecule screen, the presence of such an input file is mandatory if the structural clustering facility is intended to be used. Details are provided below.

CALIGN

If structural clustering is performed (→ CCOLLECT), and an atomic RMSD variant is chosen as the proximity measure (→ CDISTANCE), this keyword can be used to specifically disable the alignment step that occurs before the actual RMSD of the two coordinate sets is computed. To achieve this, provide any value other than 1 (the default) for this on/off-type keyword. Note that alignment must be disabled for option 10 to be available for CDISTANCE.

MOL2CLUMODE

If data for structural clustering or related analyses are to be collected (→ CCOLLECT) during a small molecule screen, this keyword is serves to amend the functionality normally provided by CFILE. The allowed proximity measures in this execution mode are (currently) 1-5, 7, 9, and 10. For coordinate RMSD-based measures (5 and 10), the options are as follows:

0. All atoms are used.
1. All atoms except aliphatic hydrogen atoms (absolute value of partial charge below 0.2) are used.
2. Only those atoms defining a dihedral angle in the Z matrix are used (in addition to the three atoms forming the "base" of the molecule). Conceptually, this option is best understood with the help of keyword TMDREPORT and associated documentation.

The options for measures based on interatomic distances (7 and 9) are practically the same. The only difference is that here the selected atoms from the small molecule are always paired with a set of atoms from the static part. This means that it is not possible to use distance-based clustering for small molecule screens lacking a static part. For dihedral angle-based measures (1-4), the options are somewhat analogous as follows:

0. All dihedral angles are used.
1. All dihedral angles except those involving the rotation of only terminal atoms of identical atom type are used. Conceptually, this option is best understood with the help of keyword TMDREPORT and associated documentation.
2. This is the same as option 1.

Note that the use of the structural clustering utility in a small molecule screen mandates the use of an input file to select features. For the static part, this works exactly as if the small molecules were not there. If there is no static part, or if the features should all involve the screened molecules according to the settings above, the input file must be present nonetheless. It should then reference the first relevant entity in the screened molecule (the first atom for RMSD, and the index of the first dihedral angle past the number found in the static part for dihedral angles). This request will be automatically discarded. It can also reference additional requests (which will also be discarded), but at least one of these must be within the hypothetical bounds set (directly or indirectly) by MOL2MAXSIZE.
The use of interatomic distances is peculiar in this regard. Here, the input file can contain, in addition to any pairs within the static part, distance pairs referencing the first atom of the screened molecules. All the partner atoms coming from the static part defined by these pairs, are then paired with all atoms from the small molecules as per the selection for MOL2CLUMODE explained above. Of course, it is, for all three classes, possible to request a clustering representation composed purely of the static part of system, but this will seldom be meaningful.

MOL2THRESH

If data for structural clustering or related analyses are to be collected (→ CCOLLECT) during a small molecule screen, this keyword defines a fractional size threshold for clusters. The centroids of clusters exceeding this threshold, i.e., those that have more members than MOL2THRESH*N, where N is the number of snapshots collected for the molecule in question, are written to the main output file of the screen if a suitable option for keyword MOL2OUTMODE is chosen.

CDISTRANSFORM

If structural clustering is performed (→ CCOLLECT), and the raw features are interatomic distances (CDISTANCE is 7, 8, or 9), this keyword can be used to specify a function that stores a transformation of the interatomic distance as the feature (this is the function f(x) in the description above). Options are as follows:

0. f(x) = x: This is the identity function and the default.
1. f(x) = 1.0 - [1.0 + exp(-(x-χ)/τ)]^-1: This is a sigmoidal function decaying from a maximum value of 1.0 to 0.0 with increasing distance. The step is centered at χ and the sharpness is given by τ. Vanishing values for τ give a transform that is equivalent to a contact map transform. For larger values of τ, the values of f(x) when x is small will increasingly deviate from 1.0 (be smaller).
2. f(x) = [x + r_buf]^-1.0/h_exp: This is a hyperbolic function. At an interatomic distance of 1.0-r_buf, the value is always 1.0. Smaller values will diverge, which should be avoided by choosing at least 1.0 for this parameter. At larger distances the values are very small and approach 0.0 asymptotically. The rate of approach is controlled by h_exp, and smaller values give a faster approach. Note that the so-called DRID metric (reference) fundamentally relies on hyperbolic transforms where r_buf is 0.0 and h_exp is 1, 1/2, or 1/3.
3. f(x) = 1.0 if x > r_cut and f(x) = sin(x·0.5π/r_cut) otherwise: This is a piecewise function that for small distances resembles the identify function (with an effective scale) before tapering off to a constant value. The point where the function becomes 1.0 exactly is r_cut.

Note that all options except the identity transform have a plateau region for large interatomic distances. This means that the differences between snapshots will be dominated by those interatomic distances where in at least one of the two snapshots the distance is small. The either 1 or 2 parameters required are set by keywords CDISTRANS_P1 and CDISTRANS_P2. Note that all of these transforms severely alter the scale of the features, which means that values for CRADIUS or CMAXRAD must generally be adjusted accordingly.

CDISTRANS_P1

If structural clustering is performed (→ CCOLLECT), the raw features are interatomic distances (CDISTANCE is 7, 8, or 9), and a transform other than the identity function is used, this keyword sets a shift parameter. For the sigmoidal function, this is the parameter χ, for the hyperbolic function, it is the parameter r_buf, and for the sine transform, it is the parameter r_cut. The equations are given above. The value is to be provided in Å and can be zero or positive.

CDISTRANS_P2

If structural clustering is performed (→ CCOLLECT), the raw features are interatomic distances (CDISTANCE is 7, 8, or 9), and either a sigmoidal or a hyperbolic transform is used, this keyword sets a scale (or width) parameter. For the sigmoidal function, this is the parameter τ and for the hyperbolic function it is the parameter h_exp. The equations are given above. The value is either to be given in Å (sigmoidal) or unitless (hyperbolic) and must be positive.

CWCOMBINATION

If data for structural clustering or related analyses are collected (→ CCOLLECT) and locally adaptive weights are in use, this keyword sets the function to be used for combining locally adaptive weights from different snapshots. This is relevant for options 2, 4, 9, and 10 for CDISTANCE. The input is interpreted identically to that for keyword ISQM, i.e., values of -1, 0, and 1 give harmonic, geometric, and arithmetic means, respectively. Values outside of this range can be expected to degrade performance due to expensive powers being evaluated. Special options avoiding most arithmetics altogether simply use the smaller or larger of the two values. In reality, these correspond to the limits of negative and positive infinity, and they are available by selecting -999 and 999, respectively.

CPREPMODE

If data for structural clustering or related analyses are collected (→ CCOLLECT), this keyword offers the user a choice to perform simple data preprocessing operations. Specific options are as follows and are all applied independently for all data dimensions:

0. The data are untouched.
1. The data are centered (subtraction of the means).
2. The data are centered and scaled by the inverse standard deviation. The resultant data are often referred to as standard or Z-scores.
3. The data are smoothed by cardinal B-splines of specified order. This operation scales linearly with this order, and it is therefore computationally wasteful to specify very large values (the long tails of the polynomial functions contribute little to the smoothing). Note that virtually no result obtainable from these data is preserved upon smoothing (except the mean), which means that results may become difficult to interpret.
4. The data are centered and smoothed.
5. The data are converted to Z-scores and then smoothed.

Note that centering leaves distance relations untouched. Centered data generally offer improved precision when computing dependent quantities relying on summation. If CAMPARI's shared memory (OpenMP) parallelization is in use, these transformations are (currently) applied by the master thread alone.

CSMOOTHORDER

If data for structural clustering or related analyses are collected (→ CCOLLECT), data smoothing may be in use. It is enabled by certain choices for keywords CMODWEIGHTS and CPREPMODE. Smoothing currently relies on cardinal B-splines, and this keyword lets the user specify the order of these functions. Cardinal B-splines are also used elsewhere (keywords BSPLINE for the PME method and EMBSPLINE for structural density restraints), but the keywords are completely independent.

CMODWEIGHTS

If data for structural clustering or related analyses are collected (→ CCOLLECT), and either static or locally adaptive weights are in use (options 2, 4, 8-10 for CDISTANCE), it is possible to override the default weights with data-derived information obtained in post-processing. This is required for options 9 and 10 to be meaningful (the locally adaptive weights for these cases are all initialized to be 1.0). Depending on the chosen option, additional parameters may be required. A detailed list is as follows:

0. This leaves all weights unchanged.
1. This option computes local estimates of the root mean square fluctuation (RMSF) and takes the inverse as the resultant, locally adaptive weight. The window size is chosen by the user. The definition of "local" by proximity in the trajectory itself implies that the data are ordered, usually along a time or similar progress axis. Note that this option is invariant only to data translation (centering). The windowed MSF are computed using an incremental algorithm that has constant cost with window size.
2. This replaces weights with weights derived from the autocorrelation function (ACF) evaluated at fixed lag time. The weights are static, i.e., they can be understood as a pre-scaling of the data. For dimensions with a negative ACF at the chosen lag time, the weight is explicitly adjusted to zero, which means that the effective dimensionality can be reduced considerably. As second moments, ACF values are noisy and generally more reliable at short lag time. For options 2 and 4 for CDISTANCE, the resultant weight is always the larger of the two obtained for sine and cosine terms. The ACF is invariant under data translation and global scaling operations.
3. This option computes a composite weight by taking the square root of the product of the ACF at fixed lag time (as for option 2) and the inverse RMSF over a window of specified size (as for option 2).
4. This option defines locally adaptive weights based on crossings of the global mean. Specifically, for each dimension, the global data mean is computed. Over a window of a user-defined size, it is then counted how many times the value of that dimension crosses the mean. Each data point receives a weight based on a window centered at this point in terms of the trajectory. The definition of "local" by proximity in the trajectory itself implies that the data are ordered, which is most often but not necessarily by time. Because it is possible that the count is zero, the resultant, locally adaptive weights are computed as (n_cross+a)^-1, where "n_cross" is the aforementioned number of crossings of the global mean and "a" is a user-defined buffer parameter (see keyword CTRANSBUF). For options 2 and 4 for CDISTANCE, the resultant weight is always the larger of the two obtained for sine and cosine terms. The idea behind this type of weight is to deemphasize data dimensions sampling roughly symmetric distributions with a single peak and to emphasize data dimensions sampling multimodal distributions with locally small variance. False negatives can be produced if the global mean happens to coincide with one of the peaks of a multimodal distribution. These weights are exceptionally simple, can be computed efficiently and with high accuracy for large data sets, and require no additional parameters beyond the window size. They are also invariant for data translation and global scaling.
5. This option is the same as the previous one (#4) except that the data are smoothed for the purpose of generating weights. This leaves the original data untouched, i.e., it does not imply data smoothing in general (see CPREPMODE for the latter). The smoothing entails an additional parameter, viz., CSMOOTHORDER.
6. This option is a combinations of options #2 and #4. The final, locally adaptive weights correspond to the square root of the static weights derived from the ACF at fixed lag time and the weights derived from crossings of the global means within windows of user-defined size.
7. This option is the same as the previous one (#6) except that the data are smoothed for the purpose of generating the local component of the weights (based on crossings of the mean). This does not imply data smoothing in general. The smoothing entails an additional parameter, viz., CSMOOTHORDER.
8. Similar to option #4, this defines locally adaptive weights based on counting crossings. Here, a histogram is created for each data dimension (fixed number of 100 bins). From the histogram, CAMPARI automatically locates minima in the histogram (at least 3 bins to either side have to have larger counts). Over a window of user-defined size, crossings of any of these minima are counted, and the weight is constructed as w_max/(n_cross+1). Here, w_max is an adjusting weight. Each minimum splits the data into two fractions of unequal size, and w_max is the maximum of the smaller fractional populations across all minima. If no minima are found, this option reverts to option #4 for the dimension in question. The histogram construction and minima parsing mask many parameters that cannot be controlled by the user at the moment. Histograms are constructed in a way that makes these weights invariant for shifted and scaled data. This option is marred primarily by the lack of both robustness and significance of the minima detection procedure. The meaning of keyword CTRANSBUF is preserved in exactly the same way as for option #4.
9. This option is the same as the previous one (#8) except that the data are smoothed for the purpose of generating weights. This leaves the original data untouched, i.e., it does not imply data smoothing in general. The smoothing entails an additional parameter, viz., CSMOOTHORDER.

Note that a conversion of locally adaptive weights to static ones by means of this keyword will not reduce CAMPARI's memory footprint. When using any of the above options computing locally adaptive weights in conjunction with option 8 for CDISTANCE, the assumed window size is taken to be the entire trajectory, i.e., the weights remain static. If CAMPARI's shared memory (OpenMP) parallelization is in use, the weights are (currently) calculated by the master thread alone.

CWINDOWSIZE

If data for structural clustering or related analyses are collected (→ CCOLLECT), and certain types of locally adaptive weights are in use, this keyword sets the window size (in numbers of snapshots) from which to obtain the weight. Each snapshot is given a weight derived from data in a window centered around that point. This makes sense primarily if the data are in a specific order, most often they are assumed to be sorted by time. Points toward the beginning (or end) of the data set all obtain the same weight as the first (or last) snapshot to have access to a complete window. This implies that windows should generally be much smaller than the data set length (they can at most extend to half the data set length). This keyword is relevant for locally adaptive weights based on variances and transition counts that can be selected via CMODWEIGHTS.

CLAGTIME

If data for structural clustering or related analyses are collected (→ CCOLLECT), the autocorrelation function (ACF) at fixed lag time can play a role, and this lag time is set by CLAGTIME. This is relevant if either static or locally adaptive weights are in use (options 2, 4, 8-10 for CDISTANCE), or if time structure-based independent component analysis (tICA) is performed (see PCAMODE). This keyword sets the time (in numbers of snapshots) to be used for this purpose.
In the case of weighted distance functions, the ACF is evaluated for each dimension independently and assumes a single, generating process:
ACF(τ) = [ Σ^N-τ(X_(k)(n)-μ_(k))(X_(k)(n+τ)-μ_(k)) ] / [σ_(k)²(N-τ)]
Here, the global data mean and variance, μ_(k) and σ_(k)², are estimated directly from the data for each dimension. Note that fewer data are available for large τ. Importantly, negative values for the ACF are all set exactly to zero meaning that these data dimensions are eliminated from distance evaluations. When applied to dihedral angles (options 2 or 4), the ACF is always evaluated separately for sine and cosine terms to avoid ambiguous definitions of variance for circular variables. The weight is then set to the larger of the two values. In case of tICA, the ACF features as a time-lagged covariance matrix that is computed for simple, centered data (no circular variables, no pairwise alignment, no locally adaptive weights). No corrections and truncations are applied to this matrix.

CREDUCEDIM

If data for structural clustering are collected (→ CCOLLECT), and a linear transformation is computed and applied (→ PCAMODE), this keyword allows the user to elect to run all further post-processing (→ CMODE) on a data set of reduced dimensionality that corresponds to the first N_V data vectors in the transformed space, where N_V is set by the choice for this keyword. The components are sorted from largest to smallest eigenvalues such that the maximum amount of variance (PCAMODE is 3) or autocorrelation (PCAMODE is 5) is included.
Note that the transformed data are interpreted as simple, aperiodic signals, i.e., none of the peculiarities for different choices of CDISTANCE are considered any longer (CAMPARI internally converts everything to CDISTANCE being 7, which may lead to confusing output regarding units, etc). Specifically, for options 4, 9, and 10 for CDISTANCE, the underlying locally adaptive weights are averaged, and the data are pre-scaled by these averages. This means that use of this keyword for those cases changes more than just the dimensionality. Similarly, for options 5 and 6, if alignment is requested, this alignment is performed as a preprocessing step, and the last snapshot of the data is used as reference. Furthermore, for option 6, only the atom set chosen for distance evaluations is retained, and this is the set to eliminate further dimensions from with the help of this keyword. Note that Euclidean distances are invariant for the full-dimensional transformed data set relative to the original data set in PCA (PCAMODE is 3) but not in tICA (PCAMODE is 5). This of course applies only to the linear transformation and not to any possible preprocessing operations.
If no linear transform is computed, or if the choice for PCAMODE implies that the data transform is not actually computed, this keyword can be used to simply discard dimensions at the end of the internal list of dimensions. This is supported for specialized applications and should not be used unless absolutely needed (use CFILE to control dimensionality precisely). This option does not work with any distance measure requiring alignment. In all cases, if CREDUCEDIM is not specified or set to too large a value, data processing will proceed with the original data and the original size. If linear transforms have been computed, the transformed data are simply written to output file PRINCIPAL_COMPONENTS.dat but not used otherwise.

CTRANSBUF

If data for structural clustering or related analyses are collected (→ CCOLLECT), and weights are in use (options 2, 4, 8-10 for CDISTANCE), it is possible to use alter the definition of weights relying on counts of crossings (see option #4 and following for CMODWEIGHTS). In a general functional form of w = (n+a)^-1, the offset or buffer parameter a is set by this keyword. The default value is 1. Large values will lead to weights with low sensitivity. The limit of CTRANSBUF approaching zero will lead to cases with n=0 receiving all the weight, which is not generally useful.

CDUMP

If data for structural clustering or related analyses are collected (→ CCOLLECT), this simple logical keyword instructs CAMPARI to write the preprocessed set of features along with possible weights and after eventual dimensionality reduction to a binary output file. This file can later be reused in CAMPARI's data mining mode.

CMODE

If data for structural clustering are to be collected (→ CCOLLECT), this keyword allows the user the specify the algorithm by which the accumulated data are to be clustered. Before going into detailed options, a few general words are in order:

1. CAMPARI strives to allow the geometric and other net quantities of a collection of snapshots to be computable irrespective of which metric of proximity is chosen (→ CDISTANCE). For options 3 and 7 this is trivial. For option 1, periodicity has to be accounted for. This is solved approximately by i) making sure the proper image of an added snapshot is considered, ii) adding appropriate periodic shifts to the geometric center increments each time a boundary violation is found after updating. Other transforms are corrected accordingly. Options 2 and 4 incur the use of several additional cluster sums (means) due to the dynamic weights (for details, the reader is referred to the source code in clustering_utils.f90: key subroutines are "clustering_distance" or "cluster_addsnap"). For option 5 (atomic coordinate RMSD), the first member of a cluster defines a reference frame. This frame is used for alignment of all subsequently added frames (therefore, the definition and all derived quantities are approximate although the error is usually small for small clusters). Option 6 is a generalization of this allowing for a split of the set of coordinates into an alignment and a distance subset. Option 8 is a mass-weighted equivalent of option 7. Options 9 and 10 are extensions of 7 and 5 to use dynamic weights as for options 2 and 4, which again requires maintaining additional cluster sums.
2. With the geometric center being defined, certain properties of a cluster are computable at constant cost with respect to cluster size. For example, the square of the average distance from the center ("radius") is, in the simplest case, given as: R² = D^-1 N^-2 · [ N · Σ_k^N x_k² - Σ_k^Nx_k · Σ_k^Nx_k]
   x_k denotes the coordinate vector belonging to the k^th member of the cluster, D is the number of coordinates, and N is the number of members of the cluster. Other properties such as the mean snapshot-to-snapshot distance ("diameter") are similarly available. All that is required is that each cluster accumulates the necessary cluster sums.

The ability to compute properties of clusters in constant time was introduced in the BIRCH clustering algorithm. It is a crucial advance when attempting to provide a scalable assessment/annotation of the results and/or to implement scalable refinement steps. It does, however, imply the Euclidean metric as the functional form for measuring dissimilarity.
The currently implemented options for CMODE are as follows (the short discussion above applies to all of them except option 4 when CPROGINDMODE is 1):

1. The data are clustered according to the leader algorithm. This is a very simple algorithm that sequentially scans the data. Each new snapshot is compared to the center snapshots of preexisting clusters and added to the first one for which a provided distance threshold is satisfied (→ CRADIUS). If no such cluster is found, a new cluster is spawned. Results will be input order dependent and clusters will have ill-defined "centers" since the central snapshot is set at the time the cluster is spawned and remains unchanged. Processing direction(s) can be chosen with the auxiliary keyword CLEADER. The leader algorithm has not been parallelized and is executed by a single thread when CAMPARI's shared memory (OpenMP) parallelization is in use, It generally offers no obvious benefit over the tree-based algorithm below (option 5). The performance of the leader algorithm deteriorates with decreasing threshold because the number of spawned clusters will eventually become significant relative to the number of snapshots.
2. The data are clustered according to a modified leader algorithm. This works very similarly to the standard leader algorithm with two important modifications. First, each new snapshot is compared to the current geometric center of preexisting clusters to evaluate the threshold criterion. Second, the result is (optionally → CREFINE) post-processed and snapshots belonging to smaller clusters that would also satisfy the threshold criterion for a larger cluster are transferred to that larger cluster. There are exactly two passes over the data of this refinement step (iteration is difficult and time-consuming due to continuously changing cluster centers). Processing direction(s) can be chosen with the auxiliary keyword CLEADER and the threshold criterion is set via CRADIUS. Modified leader-based clustering tends to generate fewer clusters compared to the standard leader algorithm due to better cluster centers. Due to centers changing position, the maximum snapshot-to-snapshot distance is no longer guaranteed to be below twice the value for CRADIUS (although in typical scenarios violations are very rare). The modified leader algorithm has not been parallelized and is executed by a single thread when CAMPARI's shared memory (OpenMP) parallelization is in use, It generally offers no obvious benefit over the tree-based algorithm below (option 5).
3. The data are clustered according to a hierarchical algorithm. In theory, a hierarchical algorithm works by first creating a sorted list of all N(N-1)/2 unique snapshot-to-snapshot distances. Starting with the shortest distance, the two constituting snapshots do one of the following:
   1. They spawn a new cluster (if they are both unassigned and the threshold criterion is fulfilled).
   2. They merge the two clusters they belong to (if they are both assigned and the threshold criterion is fulfilled).
   3. The cluster the previously assigned snapshot is part of is appended with the unassigned snapshot (if one of them is unassigned and the threshold criterion is fulfilled).
   4. They terminate the algorithm (if the threshold criterion is not fulfilled).
   In theory, it is possible to terminate the algorithm after a certain number of clusters has been generated, but CAMPARI does not offer this (yet). Termination occurs strictly by size threshold, i.e., as soon as the next considered distance is larger than twice the value for CRADIUS. Note that the threshold criteria mentioned above for what happens to the two constituting snapshots rely on the setting for CLINKAGE. All snapshots that remain unassigned after clustering are interpreted to spawn their own clusters of size 1.
   Because the problem as stated is intractable for large data sets, CAMPARI uses a dedicated scheme to help keep the computation as feasible as possible. In the first step, a snapshot neighbor list is generated that uses a truncation cutoff set by CCUTOFF. The neighbor list generation uses a pre-processing trick that aims to reduce the number of required distance calculations. This pre-processing step relies on a truncated leader algorithm whose target (threshold) cluster size is set by the (borrowed) keyword CMAXRAD. The resultant clusters are then used to screen groups of snapshot pairs and to exclude them from distance computations. Unfortunately, the problem of dimensionality often renders this procedure worthless. In high-dimensional spaces → CFILE, volume grows with distance so quickly that the distance spectrum becomes increasingly δ function-like, and in turn becomes unsuitable for exploiting additive relationships. This stems from conformational distances having a rigorous upper bound for systems in finite volume and with fixed topology. The situation is obfuscated further if many of the dimensions are tightly correlated (such that the effective number of dimensions is indeed lower). Alternatively, this neighbor list can be read in from a previously obtained file (→ NBLFILE). The neighbor list is then further truncated to exactly match the size threshold specified via CRADIUS. For the algorithm to work properly, CCUTOFF has to be at least twice the value of CRADIUS. From this truncated list, a global list is created and sorted according to size. This can be quite memory-demanding. The global list is then fed into the algorithm as described. The results of hierarchical clustering depend very strongly on the linkage criterion (→ CLINKAGE). For many real and high-dimensional data sets, the limitations in both processing time and memory footprint mean that analyses are restricted to thousands of snapshots. The hierarchical algorithm has not been parallelized and is executed by a single thread when CAMPARI's shared memory (OpenMP) parallelization is in use, This is in part because such a parallelization would not solve the memory problem.
4. The data are arranged according to the so-called progress index method described in detail elsewhere (→ reference). The progress index is a rearrangement of the snapshots such that a given snapshot at position i is added on account of it having the shortest available distance to any snapshot j<i. In its exact form, this is resemblant of the hierarchical clustering described directly above. In technical terms, the main (and only real) (hyper)parameter is a specified criterion of distance. Using this criterion, either the exact minimum spanning tree (MST) or an approximation to it is constructed for the underlying complete graph constituted by all trajectory snapshots (vertices) and the N·(N-1)/2 unique, pairwise distances (weighted edges) between them. The spanning tree is a convenient data structure for deriving the progress index but it is not conceptually fundamental to the algorithm. Provided a certain starting snapshot, the spanning tree is mined to generate a sequence of snapshots (progress index) with the above property, i.e., the snapshot added next is the one that has the minimum distance to any other snapshot already added. The complete progress index has the desirable property that it is likely to group similar objects together without overlap. In order to work, it requires the sampling density to be sufficiently inhomogeneous, i.e., there are enclosed regions (basins) that are sampled preferentially and that consequently have higher point density than the regions connecting them. It is important to keep in mind that the chosen features along with any preprocessing steps (e.g., weights) may project/distort the full, underlying phase space.
   The method provides an annotation function for the progress index that contains kinetic (or effectively kinetic) information. This function assumes that the evolution of the system is incremental and happens on a continuous manifold. Therefore, apparent jumps in phase space such as those introduced by the replica-exchange methodology may diminish the value of this annotation. There are alternative annotation functions, and some are discussed further in the documentation of the corresponding output file. For practical concerns, there is a methodological choice to pick either the exact or the approximate scheme (→ CPROGINDMODE) in addition to providing a starting snapshot (→ CPROGINDSTART). There are further keywords associated exclusively with this methodology, the most important one being CPROGINDRMAX, which sets the number of search attempts per snapshot per iteration for the approximate scheme (this is the primary controllable determinant of computational cost). Keyword CPROGINDWIDTH is a parameter related to annotations while CBASINMIN and CBASINMAX are related to automatic ways of finding starting snapshots. The approximate scheme runs almost entirely in parallel with excellent efficiency when CAMPARI's shared memory (OpenMP) parallelization is in use. Compared to the published algorithm, there are a few technical tweaks to allow this parallelization: these pertain to the auxiliary clustering (see option 5 below as well as keyword BIRCHMULTI), to search exhaustiveness (→ CPROGRDEPTH), to the handling of points in low-density regions that are not between basins (→ CPROGMSTFOLD), and to the parallel random search procedure itself (→ CPROGRDBTSZ),
5. The data are clustered according to a tree-based algorithm (→ reference) that shares architectural similarities with the BIRCH clustering algorithm. The tree algorithm implemented in CAMPARI is not focused on memory efficiency but instead keeps the entire data set stored in memory. The tree is assumed to be of a set height (number of hierarchical levels → BIRCHHEIGHT) that span a provided range of threshold criteria (upper and lower bounds set by CMAXRAD and CRADIUS, respectively) for cluster sizes. In the process of providing a parallel version for CAMPARI's shared memory (OpenMP) parallelization, a few minor modifications relative to the published algorithm were also introduced for the serial version. These modifications are included in the description below. Briefly, the algorithm consists of three phases. In the first phase, the levels are looped over starting at the root of the tree (the coarsest level) and going up to the penultimate level. At each level, every snapshot is added to an existing cluster (if the nearest distance is below the threshold for that level) or it spawns a new one (if it is not). The metric is defined by the criterion of distance applied to the snapshot and the geometric center of the cluster. The key trick is that the search space (in terms of clusters) for a given snapshot is only the (growing) set of children of the cluster this snapshot belongs to on the previous level. By spacing the thresholds accordingly, it can thus be achieved that the number of clusters searched per level and snapshot is constant irrespective of data set size. During the first phase, cluster centroids move on account of snapshots being added (compare the modified leader algorithm above). The first phase can be understood as "learning the tree" from the data. In the second phase, cluster centroids are frozen and all snapshots are reassigned to the nearest existing cluster. This again loops over the same levels as phase 1. The second phase can be understood as "binning" all snapshots into the learned tree. In the third and last phase, the results from phase 2 are used as follows. For a given cluster on a given level, all the snapshots it contains after phase 2 are subjected to a "local" reclustering at the next finer level, i.e., the search space is restricted to the binning results at the next coarser level. Phase 3 is executed for the penultimate level, which gives rise to the finest (leaf level) clustering, and potentially additional levels (see BIRCHMULTI). As for refinement, the challenge is to find protocols that do not exceed the time/space complexity of the algorithm itself. Currently, there is only one type of optional refinement step that will locally merge leaf clusters that have different but proximal parent clusters if the diameter of the joint cluster decreases upon merging (relative to the individual values).
   Except refinement, the tree-based algorithm has been fully OpenMP-parallelized. While phases 2 and 3 are relatively straightforward in this regard, phase 1 is more tricky. To achieve stable results that are identical to those of the (slightly modified) serial version, the coarsest level can only be addressed by a single thread at a time, which obviously impairs load balance. This requires keyword BIRCHCHUNKSZ to be 1, which is the default. In parallel, the clustering can alternatively try to achieve better load balance by a divide-and-merge scheme described in the context of keywords BIRCHCHUNKSZ and CMERGEDIAM. In general, the tree-based algorithm is extremely fast and will generate more clusters than, for example, the leader algorithm with the same setting for CRADIUS. However, the cluster distribution is altered nonuniformly (the largest clusters in the tree-based algorithm will often be larger, but the number of very small clusters (1-5 snapshots) will increase substantially, especially for large height). Overall, the clusters tend to be substantially tighter. In essence, the multiple hierarchical levels act, metaphorically speaking, as a layered array of filters that creates a resultant net pore size that is smaller than any one of the filters by themselves.
6. The data are assumed to be clustered already, and the clustering is read from a dedicated input file. This takes a list of snapshot-to-cluster mappings that is identical to the simple output produced in STRUCT_CLUSTERING.clu. This mode is obviously redundant unless further operations dependent on the clustering are performed, e.g., obtaining a graph output file, network-based reweighting, calculating a cut-based free energy profile, and so on. The actual data are read and fully processed. This has two important consequences. First, the clustering is completely reconstructed including information about geometric sizes and distances. Second, the time savings relative to redoing the clustering may not be significant (e.g., for typical applications with large data sets, the tree-based clustering itself takes little time compared to reading and processing the input trajectory). Note that the setting for CRADIUS is meaningful in this execution mode: both for computing cluster quality (reported to log-output) and for options 8/-8 for keyword CADDLINKMODE.
7. This is the same as the previous option, i.e., the data are assumed to be clustered already, and the clustering is read from a dedicated input file. The important difference is that the actual data are not read. This means that information about geometric sizes and distances of clusters and snapshots is not present, and any options relying on this information are either disabled or redundant. This option is useful if repeated graph-based operations are to be performed on a fixed clustering, e.g., changing the lag time of a Markov state model and recalculating the steady state. It can reduce both execution time and memory usage dramatically. In this mode, CAMPARI's normal functionality is entirely skipped (although it is still required to define a(n arbitrary) system, which can lead to (irrelevant) warnings and messages being printed).

All methods mentioned above, with the exception of the exact progress index method, create either as the final product or as a by-product a clustering. If this clustering is interpreted as a continuous trajectory of discrete states in a propagation variable such as time, it can make sense to derive a transition matrix (network model or MSM) from it. For this, the snapshot-to-snapshot transitions in the original trajectory are mapped to state-to-state transitions, from which the count matrix is derived (see elsewhere for details). The network model is written to a graph output file and can be used in further analyses (e.g., network-based reweighting, cut-based free energy profiles, committor probabilities, and so on). The count matrix generally assumes that snapshots are directly connected (i to i+1). This map can be altered by reading a file with additional breaks, by a trace file from a PIGS run, and by a file with additional links. An additional modification is the introduction of lag time different from unity. The first two file-based modifications respond to lag time while the additional links do not. There are also link modifications at the network level supported through keyword CADDLINKMODE.
Note that the connectivity map for snapshots always refers to the actual data that ends up in memory. This is controlled by NRSTEPS, CCOLLECT, EQUIL, and, if present, an input file with subsets of frames. It is consequently up to the user to ensure that the constructed network model remains meaningful.

CLUFILE

If data for structural clustering are to be collected (→ CCOLLECT), this keyword lets the user provide the name and location of a file containing a series of integers to be interpreted as the main input for file-based clustering. This file should be formatted identically to the output file STRUCT_CLUSTERING.clu written by CAMPARI itself. The associated keyword CLUFILECOL can be used to pick from the possibly more than one columns in the input file. Some more details are provided elsewhere.
The limitations are as follows. First, trajectory analysis mode has to be enabled. Second, no MPI support exists if the data are not also read. Third, the file should be analyzed with settings that pertain to the underlying data and are not remapped to the file itself (i.e., if the file is produced by CAMPARI itself, input settings should be the same as the settings for the original clustering). For example: Using NEQUIL 1000 and CCOLLECT 10, a trajectory of 10000 snapshots would give rise to 900 entries for the output in STRUCT_CLUSTERING.clu (corresponding 1010, 1020, 1030, ..., 10000). While it would be possible to reset NEQUIL to 0, NRSTEPS to 900, and CCOLLECT to 1 to read these data back in, doing so would destroy the validity of any auxiliary input file that refers to snapshot numbers in the original trajectory. Files that do so irrespective of the setting for CCOLLECT and other modifiers are files with additional breaks, trace files from PIGS runs, or files with additional links. Instead, keywords should be left at their original settings. This is because the snapshot connectivity structure is inferred independently and before the clustering (irrespective of algorithm) is performed or (if CMODE is not 7) the data are even read.

CLUFILECOL

If data for structural clustering are to be collected (→ CCOLLECT), and file-based clustering has been selected (CMODE is either 6 or 7), this keyword allows the user to pick a particular column (default is 1) from the input file. The input file format is the same as that of output file STRUCT_CLUSTERING.clu, and some more details are provided elsewhere.
If the clustering was generated by the tree-based clustering with a number of informative resolutions (see keywords BIRCHHEIGHT and BIRCHMULTI), CLUFILECOL can be used to quickly calculate network-derived properties for a number of resolutions, which can be used to assess the robustness of a result or to find the best resolution given a target property.

CCUTOFF

If data for structural clustering are to be collected (→ CCOLLECT), and an algorithm is used that requires a rigorous snapshot neighbor list (currently either hierarchical clustering or the exact variant of the progress-index based scheme → CMODE), this keyword defines the cutoff distance for said neighbor list. It is very critical to choose an appropriate (as small as possible) value for this parameter as otherwise CAMPARI will both run out of (virtual) memory and create humongous files that are written to disk. Note that even with a minimal setting, the problem of computing and storing the neighbor list can very easily become intractable. Often simulation data in high-dimensional spaces will be clustered very unevenly in space meaning that multiple "length scales" in distance space matter. This is detrimental to a neighbor list relying on defining a single, specific length scale through CCUTOFF.

NBLFILE

If data for structural clustering are to be collected (→ CCOLLECT), and an algorithm is used that requires a rigorous snapshot neighbor list (currently either hierarchical clustering or the exact variant of the progress-index based scheme → CMODE), this keyword can be used to provide name and location of an input file in the appropriate format. CAMPARI uses the versatile binary NetCDF format for this purpose, and consequently the code needs to be linked to the NetCDF library for this option to be available (see installation instructions). Most commonly, this type of file will have been created by CAMPARI itself (it is automatically written if the code is linked against NetCDF and if an algorithm is used that requires a neighbor list → corresponding documentation). This keyword is primarily meant to circumvent the costly neighbor list generation in subsequent applications of the algorithm (for instance, with different settings for CRADIUS).

CRADIUS

If structural clustering is performed (→ CCOLLECT), and an algorithm is used that uses a distance (span) threshold criterion (→ CMODE), this keyword sets the value for said threshold criterion. For leader-based clustering this is either the distance from the center snapshot (standard leader) or from the current geometric center (modified leader) and therefore constitutes a maximum cluster radius. For hierarchical clustering, twice this value is the maximum distance of any two snapshots to be part of the same cluster, so again CRADIUS will control the maximum cluster radius. For tree-based clustering, this keyword again sets the maximum distance from the current geometric center. Values are to be provided in Å for proximity measures 5-10, unitless for 3-4, and in degrees for 1-2 (→ CDISTANCE).
When working with a new set of data, it is often difficult to estimate appropriate values for this keyword right away. The same is true when changing dimensionality after data transformation on a well-known data set. To help with this, CAMPARI will print out a summary of the distance spectrum reporting subsampled quantiles and the mean before entering the selected clustering algorithm. To avoid extremely slow and/or memory-consuming executions, it is thus recommended to, in first instance, choose a Leader or the tree-based clustering with extremely large values for CRADIUS (and possibly CMAXRAD) and to, in a second run, set appropriate values based on this provided summary of the estimated spectrum.

CREFINE

If structural clustering is performed (→ CCOLLECT), this simple logical keyword lets the user control whether to apply any possible refinement strategies to the initial clustering results. Currently, there are two such procedures: for the modified leader algorithms, a refinement procedure is available which redistributes polyvalent snapshots to larger clusters. For the tree-based algorithm (for descriptions of these methods see elsewhere), a possible refinement consists of a (noniterative) merging of clusters with sufficient overlap. They are largely experimental procedures and can have a strong negative impact on performance. In particular, in the OpenMP parallel execution of the tree-based algorithm, only a single thread does the refinement.

CRESORT

If structural clustering is performed (→ CCOLLECT), this simple logical keyword lets the user control whether to break ties in the sorting of clusters by size in a systematic way. If set to 1, CAMPARI will resort clusters with identical sizes by the indices of their centroid representatives or origin snapshots in increasing order. This is useful primarily in OpenMP parallel executions of the tree-based clustering (CMODE is 4 or 5) when clustering consistency is achieved (the batch size parameter is 1). Under these circumstances, results are technically identical across multiple runs with more than one thread, but can differ in the order of clusters of identical sizes. This inconvenience can be avoided using keyword CRESORT.

CLEADER

If structural clustering is performed (→ CCOLLECT), and a leader-based algorithm is used (→ CMODE), this keyword allows the user to alter the processing directions of the leader algorithm by the following codes:

1. The collected trajectory data are processed forward. Clusters are searched backward (starting with the most recently spawned one).
2. The collected trajectory data are processed forward. Clusters are searched forward (starting with the one spawned first).
3. The collected trajectory data are processed backward. Clusters are searched backward (starting with the most recently spawned one).
4. The collected trajectory data are processed backward. Clusters are searched forward (starting with the one spawned first).

Note that the default is option 1, i.e. to process trajectory data forward, but to search clusters backwards. If the underlying data are continuous in time this may be more appropriate as it favors kinetic proximity in addition to the structural proximity criterion defined by CRADIUS. Note that this keyword also controls the trajectory processing direction in tree-based clustering (→ CMODE).

CLINKAGE

If structural clustering is performed (→ CCOLLECT), and the hierarchical algorithm is used (→ CMODE), this keyword allows the user to choose between different linkage criteria:

1. Maximum linkage: Appending a cluster with a snapshot implies that the new snapshot is less than twice the value for CRADIUS away from all snapshots currently part of the cluster. For merging two clusters, maximum linkage implies that all possible inter-cluster distances satisfy the threshold condition. This creates clusters with an exact upper bound for their diameter (maximum intra-cluster distance) and therefore resembles leader clustering.
2. Minimum linkage: Appending a cluster with a snapshot implies that the new snapshot is within a distance of twice the value for CRADIUS of at least one snapshot already contained in the cluster. Merging two clusters implies that at least one inter-cluster distance satisfies the threshold condition. With a minimum linkage criterion clusters no longer have a well-defined radius and tend to get very large unless tiny values are used for CRADIUS. This is rarely a useful option for molecular simulation data.
3. Mean linkage: Appending a cluster with a snapshot implies that the snapshot is within a distance of CRADIUS of the current geometric center of the cluster. Merging two clusters implies that their respective geometric centers are within a distance of CRADIUS of one another. This will create clusters that no longer have a rigorous upper bound for the intra-cluster distance and therefore resembles the modified leader algorithm.

Note that the default is option 1, i.e. to use maximum linkage.

CMAXRAD

If structural clustering is performed (→ CCOLLECT), and the tree-based algorithm or the approximate progress index-based scheme is used (→ CMODE), this keyword sets the upper distance threshold value for the hierarchical tree, i.e., it corresponds to the coarsest threshold used outside of the (virtual) root (see BIRCHHEIGHT for additional details).

BIRCHHEIGHT

If structural clustering is performed (→ CCOLLECT), and the tree-based algorithm or the approximate progress index-based scheme is used (→ CMODE), this keyword sets the number of hierarchy levels in the clustering algorithm. Briefly, the tree-based algorithm works by defining a series of threshold criteria (set by interpolating between CRADIUS and CMAXRAD) that define hierarchical levels. An initial clustering tree is learned from the data (phase 1), the snapshots are reassigned to the learned clusters (phase 2), and the reassignment is used to recluster at the next finer level (phase 3). In all phases, the fundamental trick is to restrict the search space for adding snapshots to clusters with the help of the tree structure (parent-child relations). The base of the tree is never counted toward BIRCHHEIGHT as it always encloses all snapshots. By specifying 1 for BIRCHHEIGHT one can thus recover an algorithm that is - in its basic outline - very similar to the modified leader scheme (see CMODE).
Larger numbers of levels generally lead to the formation of more clusters. This is because of a specific characteristic that is linked to the fact that children of a cluster (i.e., a set of clusters at the next finer level) can occupy similar space as the children from a nearby parent. If a snapshot explores only the children of a single cluster, inevitably the chances increase that an actual appropriate target cluster at finer levels is missed. In phase 3, this leads to the creation of tight clusters that are "too small" with respect to the desired threshold, i.e., this new cluster could theoretically be combined with one or more nearby clusters without the maximum intracluster distance ever exceeding the distance threshold. The offered refinement option is meant precisely to combat these errors. However, this merging scheme cannot extend arbitrarily far toward the root without destroying the computational efficiency of the algorithm. It also needs to apply stringent criteria. In practical terms, the value of BIRCHHEIGHT is a relatively free parameter if the smaller clusters can be tolerated (their quality is not compromised). In particular it can be used, in conjunction with BIRCHMULTI, to create a high-quality multi-resolution clustering, which is a desirable starting point for network model optimization. At coarser resolutions, if a multi-threaded executable is in use, the divide-and-merge strategy (see BIRCHCHUNKSZ) actually offers a separate handle on this characteristic.

BIRCHMULTI

If structural clustering is performed (→ CCOLLECT), and the tree-based algorithm or the approximate progress index-based scheme is used (→ CMODE), this keyword sets the number of hierarchy levels to refine during the second stage of the algorithm. Normally, only the most fine-grained (so-called leaf) level is populated in phase 3 of the algorithm. This leaves all levels closer toward the root in a less refined state. By specifying a value for BIRCHMULTI that is larger than the default of zero, the user requests CAMPARI to extend phase 3 to additional levels toward the root. The (virtual) root (single cluster) and the level with the coarsest actual threshold are both excluded from this refinement. The output in output file STRUCT_CLUSTERING.clu is adjusted to provide the correct number of coarse-grained trajectory annotations. Other analyses, unless specified otherwise, are only performed for the leaf level clustering (network). With appropriate settings for CRADIUS, CMAXRAD, and BIRCHHEIGHT, BIRCHMULTI can be used to create a high-quality multi-resolution clustering. The output in STRUCT_CLUSTERING.clu can then be used to perform graph-based analyses for all resolutions by choosing CMODE to be 6 or 7 and relying on keywords CLUFILE and CLUFILECOL, which is an efficient way of overcoming the aforementioned limitation.

BIRCHCHUNKSZ

If structural clustering is performed (→ CCOLLECT), the tree-based algorithm or the approximate progress index-based scheme is used (→ CMODE), and the multi-threaded executable is in use, this keyword controls an important aspect of the parallel clustering algorithm. To avoid load imbalance and scaling limitations, the first phase of the algorithm can, optionally, employ a divide-and-merge strategy for the determination of clusters at tree levels with few clusters overall. This divide-and-merge strategy can be enabled by choosing an integer value larger than 1 for this keyword (the default is 1). As a result of the divide-and-merge approach, clustering results become dependent on the number of threads in use. Only a setting of 1 guarantees that the clustering result will be the same as in single-threaded execution.
The precise role of this keyword is to set a threshold of N_s/BIRCHCHUNKSZ for coarse clusters (including the tree's root, where all snapshots are in a single cluster) to enable the divide-and-merge approach. Here, N_s is the total number of snapshots. Larger values will favor further divides and can improve load balance and scalability. The merging procedure is of course associated with a cost itself. The amount of merging is tunable by the associated keyword CMERGEDIAM. This in itself is a viable approach to controlling the properties of the clustering at coarser levels (see BIRCHHEIGHT for additional information).

CMERGEDIAM

If structural clustering is performed (→ CCOLLECT), the tree-based algorithm or the approximate progress index-based scheme is used (→ CMODE), and the multi-threaded executable is in use, this keyword controls an important aspect of the parallel clustering algorithm. To avoid load imbalance and scaling limitations, the first phase of the algorithm can, optionally, employ a divide-and-merge strategy for the determination of clusters at tree levels with few clusters overall. This divide-and-merge strategy is enabled by the associated keyword BIRCHCHUNKSZ. Applying the divide-and-merge approach implies that clustering results become dependent on the number of threads in use.
The precise role of CMERGEDIAM is to define a leniency on a criterion for merging clusters in the divide-and-merge approach. This is necessary because individual threads will likely have produced clusters with very substantial overlap. A merging of a smaller into a larger cluster is accepted whenever two conditions hold. First, the centroid-to-centroid distance is required to be less than CMERGEDIAM times a data-derived mean cluster radius at the same tree level. Second, the normalized difference of joint radius and mean snapshot-to-snapshot distance must be less than CMERGEDIAM-1.0. The default value of 1.0 therefore provides a stringent merging criterion. Smaller values make this even more stringent whereas larger values increase leniency. Note that only clusters part of a divide-and-merge block and being created by different threads are considered for merging. This makes this functionality complimentary to refinement, which operates at the leaf level.

CPROGINDMODE

If structural clustering is performed (→ CCOLLECT), and the progress index-based algorithm is used (→ CMODE), this keyword allows the user to choose between the exact (1) and the approximate scheme (2 = default). The two cases differ as follows:

1. In the exact scheme, CAMPARI attempts to construct the true minimum spanning tree (MST) for the trajectory of interest. This is achieved by following the same setup procedure used in hierarchical clustering (described under option 3 to CMODE), i.e., a heuristics-based scheme is used to construct a neighbor list in snapshot space up to a certain hard cutoff. Alternatively, the neighbor list can be read from a dedicated input file. From this list, a globally sorted list of near distances is constructed. This setup work provides the foundation to construct the MST without additional parameters via Kruskal's algorithm . The high cost (both in terms of time and memory) makes the exact scheme impractical for large data sets. Note that the neighbor list must be sufficient for the algorithm to run. This means that all the edges for the MST have to occur in the neighbor list, which is unfortunately not guaranteed even if each snapshot has multiple neighbors listed. Potential failures are therefore difficult to predict. When using CAMPARI's threads parallelization, the exact scheme is carried out by a single thread alone. This limitation is in part due to the same reasons as the same limitation for hierarchical clustering: threads parallelization does not solve the memory problem.
2. In the approximate scheme, CAMPARI utilizes a two-stage approach. The goal is to improve upon the large computational cost associated with the exact scheme without sacrificing too much information encoded in the progress index. This is done by replacing the calculation of the minimum spanning tree with an approximation, called a short spanning tree (SST). First, the trajectory data are clustered using the highly efficient tree-based algorithm (described under option 5 to CMODE). For clarity, the hierarchical tree of groups of snapshots (clusters) is not to be confused with the spanning tree we wish to generate. Because the tree-based clustering is used, keywords CRADIUS, CMAXRAD, and BIRCHHEIGHT are all relevant. The hierarchical tree is then used as follows. For every snapshot, a fixed number (sometimes an upper limit) of guesses is made to find the shortest available distance to any other eligible snapshot. Rather than searching exhaustively among all snapshots (as would be required for the MST), we restrict the search to pairs of eligible snapshots belonging to the same cluster at the finest possible level of the clustering tree. The shortest guess for every snapshot becomes a candidate edge for the SST. At every one of the ~logN iterations a number of guesses are discarded because they would introduce cycles. The algorithm is continued until the SST is complete. At any given stage, the eligible snapshots are those belonging to different subtrees of the SST. The SST will be formed primarily by connections between snapshots in the same clusters at the finest level. This procedure emulates Borůvka's algorithm with a search space limited by the hierarchical tree. Because the spanning tree thus constructed is not strictly minimal, it is important to update component memberships after each merging operation.
   The algorithm is dependent on two parameters. The first regulates the maximum number of search attempts used for finding the next-nearest and eligible neighbor for any snapshot (the minimum across a spanning tree component then becomes the candidate edge for that component). It is set by keyword CPROGINDRMAX. The respective clusters at the finest level of the hierarchical tree offering any eligible candidate edges may not offer CPROGINDRMAX guesses. In this case, the second parameter becomes relevant. It controls a depth as to how many additional levels of the hierarchical tree to descend into in order to satisfy the maximum number of guesses. This second parameter is set by keyword CPROGRDEPTH. There is a third parameter, CPROGRDBTSZ, which is a technical setting controlling how a cluster is searched randomly. This is only necessary if the number of eligible candidates in a cluster exceeds the number of missing guesses requested by CPROGINDRMAX. Then, CPROGRDBTSZ can be used to reduce the number of required random numbers. Depending on the settings, the algorithm is expected to run in approximately NlogN time with the constant prefactor determined by the clustering and the choice for CPROGINDRMAX. Similarly, the quality of the generated spanning tree depends nontrivially on both aforementioned search parameters as well as on the properties of the tree-based clustering. It is of course unlikely that the SST be in fact the true MST for trajectories of appreciable length. By using appropriately large values for both CPROGINDRMAX and CPROGRDEPTH one can create an asymptotic limit for recovering the true MST. This limit can be of practical use even though a guaranteed MST computed this way requires at least O(N²) time, which is worse than the time complexity of the exact form (aided by safe heuristics). However, the space (memory) complexity of this approach is much superior (linear rather than O(N^1.5) to O(N²)).
   The above description reveals some minor differences relative to the original published algorithm. The change associated with keyword CPROGRDBTSZ is directly related to the parallelization of the SST construction. When CAMPARI's thread-parallel version is in use, this operation offers excellent scaling properties, and limiting the number of required random numbers is beneficial for large numbers of threads. Because threads access the random number generator in nondeterministic order, keyword RANDOMSEED cannot be used to ensure that the SST in two successive executions is exactly identical for more than one thread. The second modification relative to the original publication is the straightforward generalization offered by keyword CPROGRDEPTH (in essence, the previous algorithm implied this keyword to always be 0).

In both cases, the resultant (short or minimum) spanning tree is used to determine the progress index per se. This is achieved using Jarník's (Prim's) algorithm on the spanning tree (note that a slightly different class of algorithms is used to construct it in the first place) either with a starting vertex (snapshot) selected via CPROGINDSTART or on an automatically determined set of starting vertices. At this stage, keyword CPROGMSTFOLD may become relevant. It allows preprocessing of the spanning tree to alter the edge lengths considered by Jarník's algorithm in a way that incorporates leaf vertices before any other connected vertex. This is a feature not present in the original publication but that was used already in this reference. Application of Jarník's algorithm will usually require linear time.

CPROGINDSTART

If structural clustering is performed (→ CCOLLECT), and the progress index-based algorithm is used (→ CMODE), this keyword allows the user to pick a specific snapshot to serve as starting point for the generation of the progress index. Because, like INISYNSNAP, the keyword uses a snapshot index, it is important to point out that the value of this keyword must always be specified in absolute terms of the input data, i.e., generally speaking, no corrections must be applied in case CCOLLECT is greater than 1, a sequential access file with user-selected input frames is specified, or frames are discarded at the beginning (this was different in previous versions). CAMPARI takes care of this automatically. The use of a frames file requires particular care. If the file accesses the trajectory in random access ("as is") mode, the snapshot index is assumed to refer to the line number in the frames file rather than the index of the frame on that line. This is a general change of interpretation inherent to FMCSC_FRAMESFILE with certain input file formats. Conversely, if the file accesses the trajectory in strictly sequential mode, step numbers continue to refer to the original trajectory.
As a special option, specifying zero instructs CAMPARI to find a set of suitable starting snapshots. These are generally found by generating a sample profile (discussed elsewhere) that is then scanned for extrema using an automated detection system that can be tuned with two additional keywords, CBASINMAX and CBASINMIN. The idea behind this is to generate profiles starting from a complete set of putative basins. If this automatic detection is unsuccessful, CAMPARI will revert to using the first snapshot as a starting point.
As a further option that is only available in the approximate scheme (→ CPROGINDMODE), a specified value of "-1" instructs CAMPARI to use as starting snapshot the central snapshot of the largest cluster found during the preparatory tree-based clustering. The default options are -1 in the approximate scheme and 0 in the exact scheme.

CPROGMSTFOLD

If structural clustering is performed (→ CCOLLECT), and the progress index-based algorithm is used (→ CMODE), this keyword allows the user to modify the spanning tree underlying the progress index before the index is computed. The modification consists of "folding" or collapsing the leaves into their parent vertex, which means that they are added first as soon as the index encounters the parent in question. By specifying a positive integer, the user requests CPROGMSTFOLD applications of this inward folding procedure (each of which scales linearly with the number of snapshots in terms of computational cost). After each iteration, the identity of vertices as leaf vertices is updated, which means that branches are continuously folded inward. Note that already a single iteration will fold a large number of edges (the actual number is reported to log output). For multiple folded vertices connected to the same parent CAMPARI preserves the expected order (shortest distance first).
The reasoning behind this modification is the following. When operating on the (minimum) spanning tree, Prim's algorithm proceeds by always finding the shortest distance available. As long as basins are sampled densely and transitions are rare, this has the desired effect of arranging snapshots in a way that allows identification of basins by suitable annotation. However, it is common for basins to have "fringe" regions where sampling density becomes low (and distances are large). Points in these regions will often be missed by the progress index and placed at the end (far away from "their" parent basin). Points in these regions are also likely to correspond to leaf vertices in the spanning tree. Therefore, it can be assumed that collapsing them into their parent will partially ameliorate this issue (they will occur in the correct basin). Users should keep in mind that this alters the rule that the progress index is built to track local density as much as possible.

CPROGRDEPTH

If structural clustering is performed (→ CCOLLECT), and the approximate progress index-based algorithm is used (→ CMODE and CPROGINDMODE), this keyword allows the user to control the maximum search depth for random guesses. In this method, a hierarchical tree is used in conjunction with a parameter, CPROGINDRMAX, to restrict the search space for finding edges of a short spanning tree. The hierarchical tree is based on the tree-based clustering algorithm, and its height is set by keyword BIRCHHEIGHT. For each snapshot, the algorithm will start searching for putative edges within the cluster the snapshot is part of at the finest level offering any eligible candidates. Often, the number of candidates is smaller than the setting for CPROGINDRMAX. Then, CAMPARI will descend the hierarchical tree toward the root by at most CPROGRDEPTH levels to fulfill the requested number of guesses per snapshot. The reason for offering this restriction is that the search at additional levels is often inefficient. This is because it introduces additional redundancy (the same candidates are evaluated more than once), and the candidates at a coarser-than-necessary level are unlikely to be better guesses than the ones at the finest available level. The default for CPROGRDEPTH is zero. Note that, with a meaningful clustering in place, the default setting will prevent the spanning tree from approaching the correct minimum spanning tree in almost all cases. This is because of the hard search space restrictions. At considerable cost, this keyword can overcome the impact of these restrictions.

CBASINMAX

If structural clustering is performed (→ CCOLLECT), the progress index-based algorithm is used (→ CMODE), and an automatic determination of multiple starting snapshots for profiles is requested (→ CPROGINDSTART), this keyword controls how a test profile using the standard annotation function described elsewhere is parsed to automatically identify minima in this function. Specifically, around each eligible point in the profile, environments of varying sizes are considered, and the following criteria are used:

• The sum of values to the left over a stretch of n_e points must be greater than the sum of values over a stretch of n_e points centered at the point currently considered.
• The sum of values to the right over a stretch of n_e points must be greater than the sum of values over a stretch of n_e points centered at the point currently considered.
• The sum of values to the left and right over a stretch of n_e points each must be greater than a reference sum that is given as twice the sum of values over a stretch of n_e points centered at the point currently considered plus 4n_e.
• The left (far) half of the sum of values to the left over a stretch of n_e points must be greater than the right (near) one.
• The right (far) half of the sum of values to the right over a stretch of n_e points must be greater than the left (near) one.
• No point toward the left over a stretch of n_e points must be greater than or equal to the point currently considered.
• No point toward the right over a stretch of n_e points must be greater than the point currently considered.

CBASINMAX controls the maximum value considered for n_e in the above rules.

CBASINMIN

If structural clustering is performed (→ CCOLLECT), the progress index-based algorithm is used (→ CMODE), and an automatic determination of multiple starting snapshots for profiles is requested (→ CPROGINDSTART), this keyword controls the minimum value considered for n_e as explained in the documentation of keyword CBASINMAX.

CPROGINDRMAX

If structural clustering is performed (→ CCOLLECT), the progress index-based algorithm is used (→ CMODE), and the approximate version is chosen (→ CPROGINDMODE), this keyword controls the maximum number of attempts for a search of the next correct spanning tree neighbor of a growing spanning tree component. Depending on the choice for keyword CPROGRDEPTH, such a search first exhausts the possibilities within a given cluster of the hierarchical tree underlying the approximate algorithm and will only consider a limited amount of clusters at coarser-than-necessary levels. Therefore, the parameter is interpreted as a maximum and not generally an actual value. Whenever the number of eligible candidate snapshots in a cluster is less than the missing amount of guesses for the snapshot in question, the search becomes deterministic. Otherwise, it is random (with replacement). In both cases, the eligible snapshot with the minimum distance to the spanning tree component under consideration is becomes a candidate for the next link of the approximate MST. If CAMPARI's shared memory (OpenMP) parallelization is in use, the choice for this keyword affects parallel performance at most weakly. This is because the parallelization is at the level of snapshots and not at the level of guesses.

CPROGRDBTSZ

If structural clustering is performed (→ CCOLLECT), the progress index-based algorithm is used (→ CMODE), and the approximate version is chosen (→ CPROGINDMODE), this keyword controls the structure of the random search in a cluster with a number of eligible candidates that exceeds the remaining number of required guesses for all but the first stage of Borůvka's algorithm. The default is 1 meaning that every single random guess requires a random number. Values larger than 1 imply that the random search proceeds in systematic stretches of length CPROGRDBTSZ in the contiguous stretch of eligible candidates starting from a member selected with uniform probability. The specified value is an upper limit, i.e., the number of guesses is never exceeded. Use in the first stage is forbidden so as to avoid bias from the input order, which can still be present in the list of snapshots constituting a cluster. In later stages, cluster snapshot lists have been reordered by subtree memberships, and systematic biases become increasingly unlikely. The keyword is relevant primarily if CAMPARI's shared memory (OpenMP) parallelization is in use. In this scenario, the cost of random number production can become significant relative to distance evaluations because the individual threads share the same random number generator (which leads to minor waiting times). Consequently, if the cost of the distance evaluations is high to begin with (dependent on features and metric), the default should not be changed.

CPROGINDWIDTH

If structural clustering is performed (→ CCOLLECT), and the progress index-based algorithm is used (→ CMODE), this keyword controls the auxiliary annotation function defined elsewhere. Specifically, it corresponds to the parameter l_p in the documentation found by following the link.

TMAT_MD

This important keyword lets the user set the time direction(s) for the inferred transition matrix to be used in all related analyses, which may be iterative solutions of the steady state (see CREWEIGHT), mean first passage times (see CMSMCFEP), the generation of synthetic trajectories (or random walks, see SYNTRAJ_MD) and/or, if the code was compiled and linked with HSL support (→ installation instructions), the achievement of committor probabilities (DOPFOLD and CMSMCFEP) and/or the computation of the spectral properties of the transition matrix itself (EIGVAL_MD). For the present keyword and related analyses to have an effect, a clustering analysis must be performed (see CCOLLECT and CMODE). In case CMODE is set to 4, the approximated version of the progress index algorithm must be used (CPROGINDMODE set to 2). In this case, or if CMODE is set to 5, the underlying state space used for the evaluation of the matrix is always the one at the leaf level (→ BIRCHHEIGHT).
In general, the analysis of transition matrix-derived properties will be done exclusively for those states that form the reference strongly connected component, which is identified by the cluster selected with the keyword INISYNSNAP. Some algorithms may provide solutions for all eligible components individually (see INISYNSNAP). Results of all analyses that explicitly reference user-selected snapshots (e.g. committor probabilities for folded and unfolded sets) are obtained over this reference strongly connected component only. The reference component is isolated from all the other ones (if any) by removing all the one-way transitions. The transition matrices can be requested to be written to file with the specialized keyword TMATREPORT. For the present keyword, the relevant options are:

1. Only data derived from one transition matrix are calculated, i.e., the one that uses the forward-time transitions between the clusters of the reference component (default). In the simplest scenario - viz. CLAGT_MSM set to 1, no breaks, no links and no trace files specified - these transitions are simply reflected in the output file STRUCT_CLUSTERING.clu when processed line by line from top to bottom.
2. Only data derived from one transition matrix are calculated, i.e., the one that uses the backward-time transitions between the clusters. Breaks and links are interpreted by reversing the time-information in the relevant input files. Similar to option 1, in the simplest situation, the transitions for this case are reflected in the STRUCT_CLUSTERING.clu output file when processed line by line from bottom to top.
3. Both types of transition matrices (i.e. forward and backward time) are constructed and most subsequent analyses are performed twice, once per type of transition matrix.

A transition matrix is probably the most common mathematical representation of a transition network and is - here a right - stochastic matrix (most likely sparse) that ultimately models the jumps between the states of the transition network, or Markov State Model (MSM). MSMs have recently become an important tool for the analysis of MD data, and for the details of this technique we refer the reader to the literature (Prinz et al.). Briefly, a single entry t_ij(τ) of the matrix is referred to as a "transition probability" as it reflects the (conditional) probability that the associated stochastic process (Markov Chain) jumps from state i to state j within a time window or lag time τ and given that the chain is valued in state i initially. The mathematical definition used in CAMPARI to infer t(τ)_ij is simply: t_ij(τ) = n_ij(τ) / Σ_j=1^N_clu n_ij(τ), where n_ij(τ) is the number of transitions from node i to j evaluated at a time distance equal to τ along the coarse-grained trajectory STRUCT_CLUSTERING.clu, and N_clu is the number of nodes. This means that the transition matrix that CAMPARI evaluates is always, and exclusively, the maximum-likelihood estimate. At the level of states (clusters), the maximum likelihood structure of the transition matrix can be altered by keyword CADDLINKMODE, for example to impose detailed balance.
Since the basic inference of the transition matrix is based on the count matrix, the initial estimate depends on the assumptions of snapshot-to-snapshot connectivity in the input trajectory. The default assumption (subsequent snapshots are connected in time) can be altered by several keywords. The general time spacing (lag time) can be changed with keyword CLAGT_MSM. Custom links and breaks can be added with specific input files TRAJBREAKSFILE and TRAJLINKSFILE. In addition, a special automatic handling of rerouted transitions is offered in case the input trajectory has been generated using the PIGS protocol and the associated trace file is provided as input. Importantly, these snapshot-based modifications can be handled and analyzed by CAMPARI at the beginning of the run. Obviously, all changes to the transition matrix impact all the routines that use it subsequently. Keyword BRKLNKREPORT can be used to instruct CAMPARI to print a summary of rerouted (or all) snapshot transitions.

TMATREPORT

This keyword is interpreted as a simple logical. When set to 1, it asks CAMPARI to write one or more files (see TMAT_xxxxxx_yyy.dat for details on formatting) the non-zero entries of the processed transition matrix(ces) (see TMAT_MD). For this option to be available, structural clustering analysis must be performed (see CCOLLECT and CMODE). If any method is used that relies on keyword INISYNSNAP, which includes synthetic trajectories, spectral decomposition, and committor probabilities, this snapshot will be used to identify the strongly connected component, for which the file(s) are written.

CLAGT_MSM

This integer value specifies the lag time τ to be used to compute the transition matrix for any relevant analysis based on a network (graph, Markov state model) derived from a structural clustering, e.g., SYNTRAJ_MD, EIGVAL_MD and DOPFOLD. Setting its value to any number greater than 1 (default) entails superimposing all the transition counts between clusters as derived at fixed time distance τ along the coarse-grained trajectory (STRUCT_CLUSTERING.clu), an approach that is often called "sliding window" in the relevant literature This way, there are as many superposition steps as the integer value of the lag time. CLAGT_MSM strictly refers to the spacing (in number of frames) of the data actually stored for clustering, which depend on EQUIL, CCOLLECT, and, possibly, an input file with user-selected frames. The actual distance in units of time that CLAGT_MSM corresponds to has to be computed by considering the actual spacing of the underlying data set (e.g., for a CAMPARI molecular dynamics trajectory, this would have been controlled by TIMESTEP and XYZOUT). Because CLAGT_MSM ultimately edits the way snapshots (frames) of the input trajectory are linked together, it is also relevant for the output of the progress index method (see output file PROGIDX_000000000001.dat).
The sliding window mode of operation will automatically propagate modifications to the connectivity introduced by input files TRAJBREAKSFILE and TRACEFILE. Conversely, any manually added links are always kept "as is." If the user is interested in processing all the trajectories that are superimposed this way as separate entities, it is necessary to prepare as many dedicated input frames files as the integer value of the lag time and to perform a separate analysis for each of them. It is worth pointing out that the independent clustering on each input frames file may introduce some inconsistencies in this workaround.

CADDLINKMODE

If structural clustering is performed (→ CCOLLECT), this keyword allows the user to request different modifications of the link (edge) structure of the derived network (graph). This is unavailable if the exact progress index method has been selected. Modifying the link structure can be useful because the transition counts usually suffer from poor statistics for many if not most links. This can cause problems, e.g., by splitting the graph into several strongly connected components or by creating dramatic sensitivities of network-derived properties (such as the steady state) on very few elements of the transition matrix. For small values of chosen lag times, networks are assumed to be locally connected only (sparse). While this potentially reduces the impact of statistical errors, a large number of subsequent analyses (whether in CAMPARI or elsewhere) unfortunately assume a memory-less evolution, which is difficult to fulfill. Conversely, for large values of chosen lag times, the memory-free nature of the dynamics may become appropriate, but the number of relevant transition matrix elements grows dramatically while the counts available for inference decrease considerably.
These joint concerns mean that it is unfortunately not at all simple to identify the optimal transition matrix based on counts. The available options are meant to deal with this problem as follows:

0. The network is left as is, i.e., all transition matrices will be inferred directly from the observed transition counts. This is the statistically optimal estimator if the system is truly Markovian. It can lead to fractured graphs, which introduce arbitrary probability relationships between subgraphs.
1. Strongly connected components are identified using Tarjan's algorithm. They can result from supplying a file with trajectory breaks or a trace file for an MPI PIGS calculation. Any one-way links between different components are augmented with the reverse transition. The floating point weight for this reverse link is set by keyword CLINKWEIGHT. If there is no link in either direction, multiple components will remain as in option 0.
2. Any clusters (vertices) without any observed self-transitions (self-loops) are augmented with a self-transition with a floating point weight of CLINKWEIGHT. In a Markov model sense, this will increase residence times and populations for the augmented nodes. It also removes deterministic chains of singleton clusters, which often occur in high resolution networks in fringe regions (regions of low sampling density).
3. This is a combination of options 1 and 2.
4. The count matrix is symmetrized. If one of the two corresponding elements is zero, this creates a new reverse link with the same properties as the existing forward one. If both directions are already populated, this means that the transition with a lower number of observed counts is augmented to match the exact count number of the more populated one. This option ignores keyword CLINKWEIGHT. This is different from symmetrization achieved by adding the entire transition count matrix obtained from the same trajectory reversed in time. Both variants imply detailed balance. Again, if no link exists in either direction, nothing is done, and multiple strongly connected components may persist as in option 1.
5. This is a combination of options 2 and 4.
6. Symmetrization of the count matrix is a crude way to impose detailed balance. In particular, it is almost certainly suboptimal in a statistical likelihood sense. If we assume the likelihood of the inferred transition matrix as Π_i,jT_ij^c_ij, where c_ij is the number of observed counts for the transition from i to j, and T_ij is the inferred transition matrix element, then it is possible to solve a constrained problem that maximizes this likelihood while maintaining row normalization and detailed balance as constraints on the T_ij. It is important that the particular form of the likelihood function is a strong imposition, i.e., the transition counts are assumed independent, which is equivalent to asserting Markovianity. Markovianity is a very challenging property to achieve with sufficient accuracy (in the sense of a true statistical test). This means that in many applications the resultant transition matrix does not actually maximize a meaningful quantity. This holds as much for the non-augmented inference (option 0) as for this option, which includes the added constraint of maintaining detailed balance. Bowman et al. derived an iterative estimator solving this constrained problem. This estimator was subsequently simplified by Prinz et al., and their version, which works on the log-likelihood as usual, is implemented in CAMPARI. Also with this method, links with weight zero in both directions will remain empty, which again means that multiple strongly connected components may persist. This iterative algorithm benefits from CAMPARI's shared memory (OpenMP) parallelization and is under time control (the procedure can be slow). Parallelization is such that the results should always be identical to serial execution.
7. Undersampled transition matrices can give rise to very noisy predictions. All options above (except 0) can be understood as attempts to regularize these matrices and thus make them more well-behaved. A different framework for doing so is the inclusion of objective prior information. This option adds pseudocounts of weight CLINKWEIGHT to every element of the transition matrix. This implies that the resulting graph is complete. In a statistical sense, this means that the inferred transition matrix is the maximum a posteriori estimate assuming a Dirichlet prior (which is conjugate to the multinomial distribution) with flat concentration parameters of value 1+CLINKWEIGHT. This is in a way an objective estimate assuming full connectivity. Note that this option does not impose detailed balance. A common choice for the pseudocount weight is 1/N where N is the number of states. This can be achieved by using a negative value for CLINKWEIGHT.
8. Similar to the previous option, this uses a pseudocount strategy only that the prior is nonuniform. Briefly, every row of the transition matrix receives a total weight of CLINKWEIGHT in fractional counts. These counts are distributed according to the distribution, given the metric and rerpesentation and given the lag time, of conformational distance between snapshots connected in time. Specifically, the weight is proportional to the observed frequency without corrections (fitting, smoothing). The finest binning considered depends on keyword CRADIUS (10%). If this is not fine enough, the frequency estimate may be too coarse to add useful information. This is not generally an issue unless file-based clustering (option 6 for CMODE) is used. This option was introduced in a reference publication in 2019.

None of the above options destroys an existing link. However, on occasion it may also be desirable to split different strongly coupled components completely (rather than linking them). This implies that most subsequent analyses are restricted to the reference component (see keyword INISYNSNAP below). Consequently, CAMPARI offers the following compatibility options:

-1. All links connecting different strongly coupled components are removed completely. This can create separate graphs (networks).
-2. This is currently redundant (it is exactly the same as option 2 above).
-3. This is the same as option 3 above only that all links connecting different strongly coupled components are removed completely (this does not affect self-transitions).
-4. This is the same as option 4 above only that all links connecting different strongly coupled components are removed before imbalanced transitions are symmetrized. This removal creates symmetry and will thus leave the components separate.
-5. This is the same as option 5 above only that all links connecting different strongly coupled components are removed before imbalanced transitions are symmetrized (this does not affect self-transitions).
-7. This is the same as option 7 above only that all existing links connecting different strongly coupled components are removed and no pseudocounts are added for links connecting different strongly coupled components in the original network (they remain separate).
-8. This is the same as option 8 above only that all existing links connecting different strongly coupled components are removed and no pseudocounts are added for links connecting different strongly coupled components in the original network (they remain separate).

Note that some properties reported in output file STRUCT_CLUSTERING.graphml will be inferred for added links. In particular, the reported mean square displacement values are copied (minimally required reverse transitions in options 1 and 3), set to half the value of CRADIUS squared (self transitions in options 2, 3, and 5), or constructed as a weighted average (reverse transitions in option 4 and 5). Most importantly, any substantial change to the link structure means that the network-derived equilibrium distribution (steady state) is altered. It therefore recommended to use CREWEIGHT in conjunction with this keyword. This ensures that information about the updated steady state is contained in output files such as STRUCT_CLUSTERING.graphml or MFPT_yyy_CFEP_xxxxxxxx.dat, etc.. Because these links are at the state network level, CADDLINKMODE has no influence on the results of the progress index method.

CLINKWEIGHT

If structural clustering is performed (→ CCOLLECT), and the addition of links (edges) to the derived network (graph) is requested (→ CADDLINKMODE), this keyword sets the floating-point weight for some of the added links (see above for details). Note that the basic unit is an (integer) count of observed transitions in the input trajectory. The default is therefore 1.0.

TRAJBREAKSFILE

If any type of structural clustering is performed (→ CCOLLECT), or if the exact progress index-based algorithm is used (→ CMODE), the resultant trajectory is used to infer the properties of a network. Essentially, the sequence of events in the trajectory defines a transition matrix. However, not all transitions in a trajectory may be equally valid, as they may be caused by trajectory concatenation (e.g., when using structural clustering with the MPI averaging technique, by replica exchange swaps, by nonlocal Monte Carlo moves and so on). It may therefore be appropriate to remove such spurious transitions from the analysis in order to keep inferences regarding the underlying dynamics accurate. This is what this file accomplishes, and the input and its interpretation are described in detail elsewhere.
The removal of links is relevant for a number of output files, most obviously in STRUCT_CLUSTERING.graphml and TMAT_xxxxxx_yyy.dat (the mesostate (cluster) network and implied transition matrix). All output files that depend on the transition matrix (→ TMAT_MD) and the output of the progress index method are affected as well. There are two additional notes. First, CAMPARI will not remove any transitions by default, and it may sometimes be difficult to obtain or preserve the required information (e.g., the replica exchange trace file must be used to extract the exact history of accepted swaps). Second, there is no guarantee that the graph remains intact (it may fracture into multiple, disconnected subgraphs), and this may impact the interpretability of the data in the aforementioned output files. Conversely, the native processing of a PIGS trace via keyword TRACEFILE is both more convenient and more universally supported.

TRAJLINKSFILE

If any type of structural clustering is performed (→ CCOLLECT), or if the exact progress index-based algorithm is used (→ CMODE), the resultant trajectory is used to infer the properties of a network. Essentially, the sequence of events in the trajectory defines a transition matrix. However, trajectory concatenation may give rise to scenarios where some links are spurious (→ TRAJBREAKSFILE) and others are missing, e.g., if multiple trajectories are branched off from a common starting point and simply appended for analysis purposes. This keyword can be used to add such missing links at the snapshot (frame) level. This function can overlap with keyword CADDLINKMODE, which operates at the cluster level. It also overlaps with the use of keyword TRACEFILE for managing the reseeding operations of a PIGS calculation, which is a type of simulation yielding such a set of branched trajectories. The input format is described in detail elsewhere.
The addition of links is relevant for a number of output files, most obviously in STRUCT_CLUSTERING.graphml and TMAT_xxxxxx_yyy.dat (the mesostate (cluster) network and implied transition matrix). All output files that depend on the transition matrix (→ TMAT_MD) and the output of the progress index method are affected as well. We emphasize that considerable care is required to manage the links in a conformational space network through keywords (TRAJLINKSFILE, TRAJBREAKSFILE, CADDLINKMODE, TRACEFILE, and CLAGT_MSM). This is mostly due to the fact that data generation and post-processing (necessarily) are usually separate operations, which makes it difficult to achieve a compromise between controllability and ease of use.

BRKLNKREPORT

This is a simple keyword that allows the user to request information on the snapshot-to-snapshot connectivity map CAMPARI assumes for all network-based analyses (→ TMAT_MD and the output of the progress index method). Options are as follows:

0. No report is printed.
1. Rerouted snapshot-to-snapshot links with a step spacing that is different from the requested lag time are printed to log-output at the beginning of the run (before any data are read). Indexing both relative to the stored data and relative to the original input is provided (the latter depends on CCOLLECT and EQUIL and, possibly, the presence of a file with user-selected frames). During post-processing, for the same links, the geometric distance for the two snapshots in question is printed as well.
2. This is the same as the previous option only that all links are printed.

The main purpose of this keyword to allow the user an additional level of control that any rerouting of the snapshot connectivity by means of custom breaks, custom links, and a possible trace file is correct. The information being printed refers to the forward time setting and the map is simply reversed (columns switched) for the backward time case. BRKLNKREPORT does not report on other link modifications, e.g., by CADDLINKMODE.

CREWEIGHT

If structural clustering is performed (→ CCOLLECT), which includes the case of the approximate progress index method, the resultant coarse-grained trajectory serves to define a network (graph) of clusters (vertices). If the original trajectory carries strong initial state (but no energetic) bias (for example, if it is a concatenation of many short trajectories), it may be of interest to attempt to quantify the bias in the data. This is what this keyword is meant for, and it currently supports the following options:

0. No network-based reweighting is undertaken.
1. The steady state (equilibrium probability distribution) of the underlying (and assumed!) Markov state model is computed using an iterative algorithm. As alluded to, the resultant graph may not be strongly connected or even fractured. Any modification to the link (edge) structure of the network (→ CADDLINKMODE, TRAJBREAKSFILE, TRACEFILE, TRAJLINKSFILE, CLAGT_MSM) can influence the steady state and any other network-derived properties profoundly. Even for a single continuous trajectory, the observed probability distribution in cluster space does not exactly agree with the network-derived prediction due to the imbalance caused by having a beginning and an end. Consequently, a simultaneous use of network-dependent properties such as mean first passage times or synthetic (state-based) trajectories and the raw sampling weight per state will be inconsistent. This is why the steady state - if computed - will be used in the subsequent computation of cut-based free energy profiles. Note that the steady state can also be computed using linear algebra (→ EIGVAL_MD) and is required in the computation of the (-) committor.
2. This option is the same as the previous one only that all edges are first scaled by their geometric lengths. XXXXXXXXXXXXXXX

Like any method based on the transition matrix, this functionality is available for forward and backward time. In case of multiple strongly connected components, use of CREWEIGHT requests all the individual components to be equilibrated separately (preserving their relative weights set directly by the trajectory).
The computation of the steady state uses an iterative algorithm that can become quite time-consuming due to the slow convergence behavior. There is a time control for all iterative schemes of this type. The algorithm is also numerically weak in that the convergence measure is unable to estimate the deviation of the current from the exact solution accurately and in that the convergence properties can differ across the network. The algorithm does detect periodicity, which generally prevents convergence (the easiest example is a system of two mutually connected states with no self-transitions), and will eventually report this and terminate. Unfortunately, the difficult cases for the iterative scheme are the same as those for the linear algebra solution. It can be illustrative to compute both solutions if possible and compare them (→ STRUCT_CLUSTERING.graphml). The steady state also provides a route toward reweighting a set of simulation data biased by initial conditions, i.e., an ensemble of short trajectories. The resultant weights are written by default to dedicated output file(s) unless CREWEIGHT is 0, and these files can usually be used as an input to FRAMESFILE for subsequent weighted analysis. The iterative algorithm has the advantage over the linear algebra solution that it benefits from CAMPARI's shared memory (OpenMP) parallelization. Parallelization is such that the results should always be identical to serial execution.

MAXTIME_ITERS

If structural clustering is performed (→ CCOLLECT), which includes the approximate progress index method, this keyword can be set to define a maximum execution time (in seconds) of any iterative scheme computing convergent properties of/from the transition matrix, which are currently used for the steady state (→ CREWEIGHT), the mean first passage times (→ CMSMCFEP) to a reference cluster, and the iterative maximum likelihood inference (→ CADDLINKMODE is 6). The normal convergence threshold for these algorithms must for accuracy reasons be set to such a small number that the execution can easily time out (without a printed solution) on time-limited resources if the network is large and not well-connected. This is why this keyword, which defaults to an unlimited execution time, can be set to force a solution after a given time irrespective of convergence. Note that the execution time specified here refers to a single execution of an individual algorithm, and that multiple invocations as well as the remainder of CAMPARI's execution time must be estimated independently and corrected for. Note that all 3 of the aforementioned iterative algorithms can take advantage of CAMPARI's shared memory (OpenMP) parallelization. The efficiency of this depends on the size and connectedness of the network (larger is better for both).

INISYNSNAP

If any type of structural clustering is performed (→ CCOLLECT), the underlying trajectory is used to infer a transition network. With this keyword, the user indicates the snapshot that is used for the selection of the reference cluster (and reference strongly connected component) in a number of related analyses (SYNTRAJ_MD, EIGVAL_MD, DOPFOLD, and CMSMCFEP). The reference cluster is simply that cluster that contains the snapshot indicated by the value of this keyword and the reference component is the one the reference cluster belongs to. In the case of the generation of random walks on the network, the reference cluster will be the starting node for options 1 and 2. This keyword also becomes relevant when committor probabilities are requested (DOPFOLD) but no input file for the reference set B (see DOPFOLD for definitions) is specified or found (CLUFOLDFILE). In this case, CAMPARI reverts to use as the only cluster of the set B the cluster selected here. If no value is specified, the default will take the cluster with the largest number of frames and its component as reference (option 0 described below).
Because the keyword uses a snapshot index, it is important to point out that the value of this keyword must always be specified in absolute terms of the input data, i.e., generally speaking, no corrections must be applied in case CCOLLECT is greater than 1, a sequential access file with user-selected input frames is specified, or frames are discarded at the beginning. CAMPARI takes care of this automatically. The use of a frames file requires particular care. If the file accesses the trajectory in random access ("as is") mode, the snapshot index is assumed to refer to the line number in the frames file rather than the index of the frame on that line. This is a general change of interpretation inherent to FMCSC_FRAMESFILE with certain input file formats. Conversely, if the file accesses the trajectory in strictly sequential mode, step numbers continue to refer to the original trajectory. If the selected reference snapshot is not present in the data to be finally extracted, the program will terminate at the very beginning.


As special values we have:

• 0 (default) : The cluster with the largest number of frames is selected as reference one for SYNTRAJ_MD, EIGVAL_MD, and possibly reference set B.
  Only the pseudo free energy profile for the corresponding strongly connected component is calculated (depends also on TMAT_MD), if requested.
• -1 : The cluster with the largest number of snapshots is selected as reference one for SYNTRAJ_MD, EIGVAL_MD, and possibly reference set B.
  CAMPARI will (if possible) utilize all strongly connected components of the underlying graph and use the largest cluster within each component (subgraph) as reference for multiple, distinct pseudo free energy profiles (separate output files), if requested.
• -2 : The cluster with the largest number of snapshots within the largest strongly connected component is selected as reference one for SYNTRAJ_MD, EIGVAL_MD, and possibly reference set B.
  Only the pseudo free energy profile for the corresponding strongly connected component is calculated (depends also on TMAT_MD), if requested.

EIGVAL_MD

If any type of structural clustering is performed (→ CCOLLECT), and CAMPARI was compiled and linked with HSL support (→ installation instructions), it is possible to perform a spectral analysis of the transition matrix(ces) derived from clustering (→ TMAT_MD), providing that the rank N of the transition matrix is > 3. The HSL library deputed to this task is the FORTRAN double precision version of EB13, viz. calls to EB13ID, EB13AD, and possibly EB13BD are made in CAMPARI whenever required. Those routines implement the Arnoldi method for large sparse matrices and the user is invited to read up on the relevant documentation (EB13). CAMPARI hides, however, some of the functionality offered by the HSL library itself. For example, referring to the relevant documentation (EB13), the Arnoldi method used by CAMPARI is always the one with Chebychev acceleration of the starting vectors, i.e., ICNTL(9) is hard-coded to 2, which is the only option we have tested. Currently, this choice can be altered only by modifying the source code where the relevant initialization happens (subroutine calc_eigs_msm(...) in source file graph_algorithms.f90). With the present keyword, the user can decide whether or not to perform the spectral decomposition of the transition matrix and, in case it is performed, how to sort the eigenvalues of the transition matrix (with this keyword the "IND" variable of EB13AD is set to the same value with an offset of -1). The following options are available:

0. No spectral decomposition is performed (default).
1. A selected number (→ NEIGV) of eigenvalues with largest absolute values are computed.
2. A selected number (→ NEIGV) of right-most eigenvalues are computed. These are the eigenvalues with the largest real parts. This option is probably the only useful option for the spectral analysis of a transition matrix as complex eigenvalues are not generally interpretable to begin with.
3. A selected number (→ NEIGV) of eigenvalues with largest imaginary parts are computed.

The eigenvalues of the transition matrix (TMAT_MD), with the exception of the one with the largest real part (which is always 1), can provide information on the transition time scales of the Markov process and the trend of such implied time scales as a function of the lag-time (CLAGT_MSM) is often sought after to establish the (minimum) time scale at which the random walker dynamics may be truly Markovian on the state space defined by the clustering (see, e.g., CDISTANCE and CMODE). To achieve such an informative trend of the time scales (eigenvalues in decreasing order by their real part), this keyword must be set to 2, which is the only recommended option. Eigenvalues that are complex or negative obviously violate this interpretation as the time scale t associated with an eigenvalue is defined as t = -τ/ln(λ), where τ is the lag time (→ CLAGT_MSM) and λ the eigenvalue in question.
If the spectral analysis of the transition matrix is requested, several dependent keywords controlling the task to be solved as well as parameters of the Arnoldi method become relevant. The number of eigenvalues to be computed is set with NEIGV, while keyword DOEIGVECT lets the user request the computation of the eigenvectors associated with the NEIGV eigenvalues as well. The Arnoldi method is controlled by keywords NEIGBLOCKS, NEIGSTEPS, NEIGRST, and EIGTOL. The output produced by the use of this keyword is always written to a dedicated output file (EIGEN_xxx.dat). In addition, if the chosen option is 2 and the eigenvectors are available, output file STRUCT_CLUSTERING.graphml will contain the first eigenvector as well. Lastly, note that the same routines may be called in case the computation of the (-) committor was requested. In this particular case, the options are not directly controllable by the user, however.
Because the HSL routines are not (currently) threads-parallel, this functionality does not benefit from CAMPARI's shared memory (OpenMP) parallelization, which is a limitation.

NEIGV

If any type of structural clustering is performed (→ CCOLLECT), CAMPARI was compiled and linked with HSL support (→ installation instructions), and EIGVAL_MD is not zero, this integer value defines how many eigenvalues should be returned by the spectral decomposition (EIGVAL_MD) of the transition matrix(ces) (TMAT_MD). The returned eigenvalues are maximal in some sense, and this is defined by the choice for EIGVAL_MD. This keyword effectively sets the value of variable "NUMEIG" in the underlying HSL routine EB13. The value for this keyword influences the choice for NEIGSTEPS and NEIGBLOCKS, since it is required that min(N, NEIGV) ≤ NEIGSTEPS·NEIGBLOCKS ≤ N, where N is the rank of the transition matrix (N > 3). It is worth to note that the cost for the Arnoldi steps at each iteration scales as (NEIGBLOCKS·NEIGSTEPS)²·N, while the cost of computing the Hessenberg matrix is proportional to (NEIGBLOCKS·NEIGSTEPS)³ and the memory requirements are proportional to (NEIGBLOCKS·NEIGSTEPS)², as outlined in the documentation for EB13. Therefore, increasing the number of eigenvalues to be computed can impact both the achievement of the desired convergence criterion (EIGTOL), which may be addressed by keyword NEIGRST, and can have a dramatic effect on execution time and memory footprint.

DOEIGVECT

If any type of structural clustering is performed (→ CCOLLECT), CAMPARI was compiled and linked with HSL support (→ installation instructions), and EIGVAL_MD is not zero, this simple logical (1 is true) allows the user to request CAMPARI to compute eigenvectors along with eigenvalues, which are added to the same output file, viz., EIGEN_xxx.dat. If EIGVAL_MD is set to 2, the first eigenvector contains the steady state of the transition network (TMAT_MD), which is also reported in the output file STRUCT_CLUSTERING.graphml. In case the network is fractured into multiple, strongly connected components, the computation and output are limited to the strongly connected component the reference cluster (INISYNSNAP) resides in. Additional eigenvectors (→ NEIGV), which refer to the eigenvalues smaller than 1, are often interpreted to report on the involvement of each cluster in the transition associated with a characteristic time scale, which is given by the corresponding eigenvalue λ as t = - τ/ln(λ) where τ is the lag time (→ CLAGT_MSM).

NEIGBLOCKS

If any type of structural clustering is performed (→ CCOLLECT), CAMPARI was compiled and linked with HSL support (→ installation instructions), and EIGVAL_MD is not zero, this keyword lets the user set the number of blocks for the Arnoldi method. It corresponds to the variable "NBLOCKS" in the reference library documentation (EB13). NEIGBLOCKS must be ≥ 1 and the conditions min(N, NEIGV) ≤ NEIGSTEPS·NEIGBLOCKS ≤ N must always hold true, with N being the rank of the transition matrix (TMAT_MD), N > 3. If NEIGBLOCKS is set to 1, the unblocked Arnoldi method is used (EB13). If this keyword is not found, the current default choice is to set NEIGBLOCKS to NEIGV + 2. However, the best choice for this value together with the value for NEIGSTEPS depends on the problem. In the reference documentation (EB13), the suggestion is to set NEIGBLOCKS to at least the value of NEIGV and to set NEIGSTEPS such that NEIGSTEPS·NEIGBLOCKS lies in the range between 3·NEIGV and 10·NEIGV.

NEIGSTEPS

If any type of structural clustering is performed (→ CCOLLECT), CAMPARI was compiled and linked with HSL support (→ installation instructions), and EIGVAL_MD is not zero, this integer variable sets the number of steps for the Arnoldi method and corresponds to the variable "NSTEPS" in the reference library documentation (EB13). The minimum allowed value is 2 and the requirements min(N, NEIGV) ≤ NEIGSTEPS·NEIGBLOCKS ≤ N must always be respected, with N being the rank of the transition matrix (TMAT_MD), N > 3. The current default choice is to set this variable to ceiling((8.·NEIGV)/(NEIGV + 2)), if no specifications are given from the user. However, the best choice for this value together with the value for NEIGBLOCKS is dependent on the problem. In the reference documentation (EB13), the suggestion is to set NEIGBLOCKS to at least the value of NEIGV and to set NEIGSTEPS such that NEIGSTEPS·NEIGBLOCKS lies in the range between 3·NEIGV and 10·NEIGV.

NEIGRST

If any type of structural clustering is performed (→ CCOLLECT), CAMPARI was compiled and linked with HSL support (→ installation instructions), and EIGVAL_MD is not zero, this keyword lets the user select the number of restarts of the Arnoldi's method before the execution is terminated in case the wanted convergence (EIGTOL) has not been achieved in the previous set of steps. The default value is set to 10, which means that the execution is aborted after 10 restarts from the possible intermediate and not yet converged solution. For the sake of completeness and clarity, the hard-coded value for the number of iteration within EB13, viz. ICNTL(11), is 999, and that is not the value set by this keyword.

EIGTOL

If any type of structural clustering is performed (→ CCOLLECT), CAMPARI was compiled and linked with HSL support (→ installation instructions), and EIGVAL_MD is not zero, this keyword sets the tolerance on the residuals that needs to be achieved before the computed solution of the eigenvalue problem on the transition matrix(ces) (→ TMAT_MD) is deemed appropriate. It defaults to 10³·"machine precision" and corresponds to CNTL(1) in the library documentation (EB13). For completeness, we mention here that ICNTL(7) is hard-coded to 1, which means that convergence is checked against the Frobenius norm of the matrix, which is computed by default.

CMSMCFEP

If structural clustering is performed (→ CCOLLECT), which includes the case of the approximate progress index method, this keyword allows the user to select a type of cut-based pseudo free energy profile to be computed (reference). The target node for this profile can be chosen with keyword INISYNSNAP, which is snapshot-based and includes the selection of the largest cluster(s) (by sampling weight). Depending on the assumed direction of time (→ TMAT_MD) and the choice below more than 1 profile may be generated (separate output files). Currently, there are 4 fully supported options producing output (some hidden options exist, which will not be disabled):

0. No cut-based free energy profiles are computed. This is the default.
1. The mean-first passage times to the reference node in the Markov state model approximation are computed iteratively. After sorting all clusters according to these mean first passage times, partitions can be defined as a function of a threshold time. The cut-based pseudo free energy profile associates each threshold time with the total weight of edges (number of transitions) crossing this threshold along the trajectory, and plots the normalized weight in logarithmic fashion (see elsewhere for details). Because the iterative algorithm may be slow to converge, its maximum execution time can be controlled by keyword MAXTIME_ITERS. In this mode, a separate profile for each strongly connected component of a nonergodic graph can be produced if INISYNSNAP is -1. These profiles are referenced to the respective largest clusters (by sampling weight) in each component. The iterative algorithm used here benefits from CAMPARI's shared memory (OpenMP) parallelization (similar to network equilibration). Parallelization is such that the results should always be identical to serial execution.
8. The (+) committor probabilities for a set of clusters defining a target set and an unfolded set are used to sort all clusters (folded and unfolded set members have values of 1.0 and 0.0 by definition, and clusters are sorted in decreasing order). This requires having computed those committor probabilities separately (CMSMCFEP can not be used to enable this calculation) with the help of keyword DOPFOLD. Because the committor probabilities are only available for the reference component the sets reside in, INISYNSNAP has no direct influence (in particular, option -1 is not available). See elsewhere for details on the corresponding output file(s).
9. This is the same as the previous option only that the (-) committor probabilities are used instead, which additionally relies on keyword DOPFOLD_MINUS. See elsewhere for details on the corresponding output file(s).
10. This is the combination of the prior 2 options, i.e., separate profiles based on both (+) and (-) committor probabilities are produced. The same dependencies and restrictions apply.
11. In this case, clusters are ordered by the entries of the eigenvector(s) computed from the spectral decomposition of the transition matrix. In order to enable this mode, it is thus necessary to consider keyworkds EIGVAL_MD, which must be set to 2, DOEIGVECT, NEIGV, and CCOLLECT, and possibly related ones (INISYNSNAP, TMAT_MD, CMODE, etc.). This means that the required functionalities are not automatically enabled by the present keyword CMSMCFEP. Since the entries of the first eigenvector with EIGVAL_MD enforced to 2 are the steady state of the associated MSM, NEIGV must be ≥ 2 to possibly produce any output. The number of output files produced is at maximum equal to the number of converged eigenvectors. Note, however, that computations are stopped (with no crash) at the first occurrence of a complex eigenvector, as it is unclear how complex spectral properties should be interpreted. This may change in the future. As a final note, analogously to mode 8, 9 and 10, only the clusters belonging to the component identified with INISYNSNAP will compose the cut-profile(s) (see elsewhere for information on the output file(s)). This also means that setting INISYNSNAP to -1 will not produce multiple sets of output file(s) (one set of file(s) per component), but it will just amount to using the largest cluster by sampling weight to identify the one reference component (same as INISYNSNAP set to 0). The map between these component-local clusters and the original absolute numbering can be recovered, as usual, by the correspondig centroids annotateted in the output file(s), or by file STRUCT_CLUSTERING.graphml, or through the simplified transition matrix output if TMATREPORT is enabled.

Note that in general the deferred selection of reference clusters chooses by sampling weights, which are not the same as the steady state weights of the underlying transition matrix. This means that the largest cluster in steady state probability may not be the same. These effects become more pronounced with lower sampling quality and larger amounts of link structure modifications (see TMAT_MD for details).

SYNTRAJ_MD

If any type of structural clustering is performed (→ CCOLLECT), this keyword specifies whether random walks on a transition network should be performed (and recorded), and how the initial and termination conditions are chosen. Synthetic trajectories are always confined within the strongly connected component that contains the cluster that hosts the initial reference snapshot (INISYNSNAP). The values allowed for the present keyword and their associated outcomes are:

0. No synthetic trajectories are generated (default).
1. Random walks are initiated in the cluster that contains the reference initial snapshot (INISYNSNAP) and are terminated either when the walker hits the cluster that contains the target snapshot (ENDSYNSNAP) or when the target number of steps per trajectory is exceeded (NSYNSNAPS). In the latter scenario, the unsuccessful trajectory is not written to file (MSM_SYN_TRAJ_xxxxx_yyy.frames). The target number of trajectories to be generated is set by the keyword NSYNTRAJS. Since trajectories may fail to hit the target end node, it is possible that the number of successful trajectories is less than NSYNTRAJS. If trajectories fail repeatedly, it is advisable to increase the number of steps per trajectory (NSYNSNAPS). If the fraction of productive trajectories is small, their lengths will obviously be biased systematically toward shorter lengths.
2. Synthetic trajectories are started at the cluster that hosts the reference snapshot (INISYNSNAP) and propagated for NSYNSNAPS steps, regardless where they end. Therefore, the generation of a trajectory is always successful, viz., NSYNTRAJS trajectories are always written to file (MSM_SYN_TRAJ_xxxxx_yyy.frames).
3. Each NSYNTRAJS trajectory starts in a random cluster. The probability that a cluster is the starting one reflects its statistical weight, which is proportional to the raw population of the cluster if no equilibration of the transition network is performed or to the steady state of the Markov State Model otherwise (see CREWEIGHT and EIGVAL_MD). Each trajectory is propagated for NSYNSNAPS steps and written to file (MSM_SYN_TRAJ_xxxxx_yyy.frames). Keyword INISYNSNAP is used solely to identify the strongly connected component where the random walk takes place.

This keyword allows the user to generate synthetic trajectories, which are random walks on the state space defined by a coarse graining into clusters of the input MD trajectory (STRUCT_CLUSTERING.clu). The connectivity between the clusters, viz., the number of transitions between the nodes of the network, is inferred directly from the input data and is used to construct the so-called transition matrix, which is ultimately the propagator of the synthetic dynamics. Many keywords, when in use, have an impact on the transition matrix and therefore on the random walks (see elsewhere for a list). The actual connectivity is available from output files STRUCT_CLUSTERING.graphml and TMAT_xxxxxx_yyy.dat where the availability of the latter depends on TMATREPORT. The output files can be numerous and grow quickly, which is why keyword SYNTRAJOUT can be used to control the output frequency. Note that the shared memory (OpenMP) parallelization of CAMPARI supports generating these trajectories in parallel. It must be mentioned, however, that the main cost can easily be the file system bandwidth (the inherent cost of trajectory generation is marginal) consumed for writing the output files, which may limit or even eliminate any benefits from parallelization.

ENDSYNSNAP

If any type of structural clustering is performed (→ CCOLLECT), and the generation of synthetic trajectories with a target end point has been requested, this keyword lets the user select the target snapshot for these random walks. It works analogously to keyword INISYNSNAP, and it is up to the user to ensure that the reference end target node selected this way differs from the starting one and belongs to the same strongly connected component. If these conditions are not met, the relevant analyses will be skipped. In case committor probabilities are requested but no input clusters are provided (CLUUNFOLDFILE) for set A (see DOPFOLD for definitions), CAMPARI reverts to use the cluster selected here as the only one forming set A. If this keyword is not specified but needed, CAMPARI will use the last stored snapshot from the trajectory as reference end snapshot (default).
Because, like INISYNSNAP, the keyword uses a snapshot index, it is important to point out that the value of this keyword must always be specified in absolute terms of the input data, i.e., generally speaking, no corrections must be applied in case CCOLLECT is greater than 1, a sequential access file with user-selected input frames is specified, or frames are discarded at the beginning. CAMPARI takes care of this automatically. The use of a frames file requires particular care. If the file accesses the trajectory in random access ("as is") mode, the snapshot index is assumed to refer to the line number in the frames file rather than the index of the frame on that line. This is a general change of interpretation inherent to FMCSC_FRAMESFILE with certain input file formats. Conversely, if the file accesses the trajectory in strictly sequential mode, step numbers continue to refer to the original trajectory.

NSYNTRAJS

If any type of structural clustering is performed (→ CCOLLECT), and the generation of synthetic trajectories has been requested, this keyword specifies the target number of synthetic trajectories (random walks) to be generated. The default value is 10 and the upper limit is 10⁴. This number is guaranteed to be the actual number of generated trajectories only if SYNTRAJ_MD is not set to 1. For trajectories with requested start and end points (mode 1), this keyword specifies the total number of attempts instead. The fraction and average length of productive trajectories will be reported to log output, but only successful trajectories are written to file.

NSYNSNAPS

If any type of structural clustering is performed (→ CCOLLECT), and the generation of synthetic trajectories has been requested, this keyword sets the (maximum) number of steps per synthetic trajectory (random walk). All trajectories will have this length unless keyword SYNTRAJ_MD is set to 1. Note that in mode 1 where both a starting and an end point are used, too small a value for NSYNSNAPS will obviously bias the distribution of productive (reactive) trajectories to short ones.

SYNTRAJOUT

If any type of structural clustering is performed (→ CCOLLECT), and the generation of synthetic trajectories has been requested, this keyword sets the output frequency for the synthetic trajectories (random walks) themselves. These files are documented elsewhere, but they ultimately contain lists of integers, which can get large (in total file size) very quickly. This is why this keyword allows the user to print only every SYNTRAJOUT^th step of each random walk to the corresponding output file. If SYNTRAJ_MD is 1, the keyword can also be set to 0, in which case all output is suppressed (using a very large value instead causes the individual files and just their respective header lines to be written).

DOPFOLD

If any type of structural clustering is performed (→ CCOLLECT), and CAMPARI was compiled and liked with HSL support (→ installation instructions), this simple logical (1 is true) selects whether or not to compute (+) committor probabilities (or p_folds⁺ values) for the clusters that belong to the reference component of the graph inferred from the clustering. The underlying transition matrix can be modified in various ways (see TMAT_MD for details), which may weaken or fracture the graph into multiple strongly connected components.
A set of clusters to form the target set B (CLUFOLDFILE) and a set of clusters to form an alternative set A (CLUUNFOLDFILE) are required and must belong to the same component. If these input files are missing choices are deferred to keywords INISYNSNAP and ENDSYNSNAP. The remaining clusters in the same component constitute the intermediate set and for them the probability that a random walker started in that intermediate state reaches any cluster in the target set B before it reaches any cluster in the other set A can be calculated. By definition (as boundary condition), all the nodes that belong to the target set B have a p_fold⁺ value equal to 1, while all the clusters that belong to set A have a p_fold⁺ value equal to 0.
If DOPFOLD is set to 1, with the aid of HSL-provided (double precision) external routines (HSL_MA48), the solution is the solution of a linear system of equations for the clusters i in the intermediate set I (Noé et al.):
-p_foldi⁺ + Σ_j∈I T_ijp_foldj⁺ = - Σ_j∈BT_ij
Here, T is the underlying transition matrix (→ TMAT_MD). Once solved, the committor probabilities are written to a specific output file (PFOLD_PLUS_xxx.dat). The computed p_fold⁺ values are obviously sensitive to any modifications to the transition matrix. The time direction matters unless detailed balance holds (→ CADDLINKMODE), in which case the p_fold⁺ values become equivalent to 1.0-p_fold^- computed via keyword DOPFOLD_MINUS. In case detailed balance does not hold, the values for the (-) committors (p_folds^-) must be computed separately.
One of the reasons to compute committor probabilities may be probability flux analyses and decompositions of pathways according to transition path theory (Noé et al., Berezhkovskii et al.), and committors are indeed fundamental to these analyses.
Because the HSL routines are not (currently) threads-parallel, this functionality does not benefit from CAMPARI's shared memory (OpenMP) parallelization, which is a limitation.

DOPFOLD_MINUS

If any type of structural clustering is performed (→ CCOLLECT), CAMPARI was compiled and liked with HSL support (→ installation instructions), and (+) committor probabilities have been computed, this simple logical keyword (1 is true) lets the user request the computation of (-) committor probabilities or p_folds^- values as well. These committors are defined as the probability that a random walk that reaches an intermediate state i was last seen in the alternative set (A) rather than in the target set (B). Details on nomenclature and background are found in the description of keyword DOPFOLD. Their computation requires the solution of a linear system similar to the one specified for the (+) committors (p_fold⁺):
-p_foldi^- + Σ_j∈I X̄_ijp_foldj^- = - Σ_j∈AX̄_ij
Here, X̄ is defined as T̄_ij = (π_j/π_i) T_ji, π_i is the steady state probability of node i of the original transition matrix T. The underlying transition matrix is affected by a number of keywords (see TMAT_MD for details). The resultant (-) committor probabilities are written to a specific output file (PFOLD_MINUS_xxx.dat). If microscopic reversibility (detailed imbalance) holds (→ CADDLINKMODE), the (-) committor probabilities can simply be computed as 1.0-p_fold⁺, and there is no need to use this DOPFOLD_MINUS. If it does not hold, X̄ is not simply the backward time transition matrix (→ TMAT_MD). Therefore, if DOPFOLD_MINUS is used, CAMPARI always computes T̄ from the definition above, which may be numerically problematic in case state probabilities differ by some orders of magnitude. Since we require the steady state or first eigenvector, CAMPARI will check whether an acceptable solution is already available from the use of keywords EIGVAL_MD or CREWEIGHT (in this order). If not, CAMPARI attempts to solve the steady state using the HSL library EB13 similar to what would be done if EIGVAL_MD is 2, DOEIGVECT is 1, and NEIGV is 1. For this solution, keywords NEIGBLOCKS and NEIGSTEPS are not respected (values of 3 and 3 are used instead), but the settings for EIGTOL and NEIGRST remain relevant. If the solution is successful and acceptable, it will also be reported in output file STRUCT_CLUSTERING.graphml.

PFOLDREPORT

If this simple logical is enabled (1 is true) several files that inform on the linear system(s) relevant to the achievement of committor probabilities (DOPFOLD, DOPFOLD_MINUS) may be written. Those files are: fold_clus.out, unfold_clus.out, mat_pfold_XXX_YYY.dat, rhs_pfold_XXX_YYY.dat, and possibly tmat_pfold_XXX_minus.dat and ss_pfold_XXX.dat. Files fold_clus.out and unfold_clus.out simply replicate the clusters that make up set B and set A (see also DOPFOLD for definitions) respectively, while files mat_pfold_XXX_YYY.dat contain the coefficients of the linear system(s) solved to achieve committors, viz. T - I for DOPFOLD and/or T̄ - I for DOPFOLD_MINUS. These last two outputs obviously consider only the entries relevant to the edges between the intermediate states and the self transitions, similarly to the rhs_pfold_XXX_YYY.dat files, where the right hand side of the linear systems (DOPFOLD and/or DOPFOLD_MINUS) are written. Files tmat_pfold_XXX_minus.dat contain the entries of T̄ and are written only if DOPFOLD_MINUS is enabled, while files ss_pfold_XXX.dat contain the steady state that was used to achieve T̄. Those are written only in case the steady state was not available from other options (for details see DOPFOLD_MINUS).

CLUFOLDFILE

If any type of structural clustering is performed (→ CCOLLECT), CAMPARI was compiled and liked with HSL support (→ installation instructions), and the computation of at least (+) committor probabilities has been requested, this keyword let the user specify the path and name of the file that stores the reference snapshots for the selection of the clusters forming the target set B for all committor probabilities. Details on the format and interpretation of the input are provided elsewhere.
In case this file is not provided or not found, CAMPARI will revert to the cluster defined by keyword INISYNSNAP as the only representative of set B. In case keyword INISYNSNAP is not specified either, CAMPARI will use the cluster that contains the largest number of snapshots. Because the sets A and B have to reside in the same strongly connected component of the clustering graph, it may not be possible to know reasonable values a priori. It can therefore be helpful to use this analysis in conjunction with a previously generated clustering-derived graph. The graph can be analyzed to identify suitable values, and the committor probability analysis can be performed in a second step by reading the coarse-grained trajectory in conjunction with any link structure modifications back in by means of file-based clustering (modes 6-7 for CMODE).

CLUUNFOLDFILE

If any type of structural clustering is performed (→ CCOLLECT), CAMPARI was compiled and liked with HSL support (→ installation instructions), and the computation of at least (+) committor probabilities has been requested, this keyword let the user specify the path and name of the file that stores the reference snapshots for the selection of the clusters forming the alternative set A for all committor probabilities. Details on the format and interpretation of the input are provided elsewhere.
In case this file is not provided or not found, CAMPARI will revert to the cluster defined by keyword ENDSYNSNAP as the only representative of set A. In case keyword ENDSYNSNAP is not specified either, CAMPARI will use the cluster that contains the last snapshot of the trajectory, which is not generally meaningful. Because the sets A and B have to reside in the same strongly connected component of the clustering graph, it may not be possible to know reasonable values a priori. It can therefore be helpful to use this analysis in conjunction with a previously generated clustering-derived graph. The graph can be analyzed to identify suitable values, and the committor probability analysis can be performed in a second step by reading the coarse-grained trajectory in conjunction with any link structure modifications back in by means of file-based clustering (modes 6-7 for CMODE).

NetCDF Data Mining:

---

(back to top)

Preamble (this is not a keyword)

This mode is enabled by a separate executable that, however, rests on the same library as CAMPARI itself. The compilation of this executable is analogous to CAMPARI executables and described in the installation instructions. This executable provides functionality to analyse input data provided in NetCDF binary format. The conversion of compliant ASCII files to the required NetCDF standard is also possible. It is only available if the code was compiled and linked with NetCDF-support (see installation instructions). The available functionality is restricted to structural clustering of the input data (permissible values of CDISTANCE are currently limited to 1, 2, 7, 8 and 9) and downstream analyses such as, e.g., cut-based free energy profile, progress index, principal component analysis and other network analyses (see for instance CREWEIGHT, SYNTRAJ_MD etc.). In case the code was also compiled with HSL support (→ installation instructions), spectral decomposition of transition matrices and the computation of committor probabilities are also supported. The presence of the keyword trace file in the input key file is explicitly not allowed and results in a halt of the execution if detected.

---

NCDM_NCFILE

With this keyword the user specifies the path and name of the input file in NetCDF format that encodes the data to be analyzed. For the required file standard (dimensions, variables, attributes etc.) we refer the user to the relevant input file delineation and to the external NetCDF library documentation. Keyword NCDM_WRTINPUT can be used to produce a summary of the information that was processed from the input NetCDF data source file in the guise of a NetCDF output file. This output file, useful for debug, is in compliance with the internal standard, but since it reflects choices such as CCOLLECT, NCDM_FRAMESFILE and NCDM_CFILE, it should not be used as input for the present keyword. The reason lies in the fact that it may result incomplete if the same key file is used again (see NCDM_WRTINPUT). As a final note, it is important to mention that keyword NCDM_NCFILE is mutually exclusive with respect to NCDM_ASFILE: either the user provides a binary NetCDF as input or an ASCII file.

NCDM_ASFILE

This keyword is used to indicate the path and name of the input ASCII file that contains the data to be either converted to NetCDF format according to internal conventions, or analyzed with structural clustering and downstream routines, or both. This behavior is controlled by keywords NCDM_WRTINPUT (to explicitly write down all the contents of the ASCII file in a NetCDF data base compliant with the correct standard) and NCDM_ANONAS (to do the analysis on the input ASCII data) and either one, or both, should be specified. For the ASCII file standard required by the program see elsewhere. This keyword is mutually exclusive with respect to NCDM_NCFILE: either the user provides a binary NetCDF as input or an ASCII file. When an ASCII file is provided as input, there are more requirements from the user side than when a NetCDF file is used, and keywords NCDM_NRFEATS, NCDM_NRFRMS and NCDM_CHECKAS become relevant in addition to, possibly, NCDM_PRDCRNG.

NCDM_WRTINPUT

By setting this keyword to 1, it is possible to ask the program to write a NetCDF file that is either the converted input ASCII file (and in this case choices from keywords such as CCOLLECT, NCDM_FRAMESFILE, NCDM_CFILE, etc., have no influence on the output, only on the possible downstream analyses, see NCDM_ANONAS) or the key information of the input NetCDF database that have been inferred by the software (for debug). The output names are "BASENAME_converted.nc" and "BASENAME_checked.nc", respectively. It is important to mention here that only the converted ASCII file is safe to be used as input NetCDF database since the output named as "BASENAME_checked.nc" may not fully reflect the input NetCDF file which it corresponds to. This is because "BASENAME_checked.nc" is sensible to keywords such as CCOLLECT, NCDM_FRAMESFILE and NCDM_CFILE, differently from the output named "BASENAME_converted.nc".

NCDM_PRDCRNG

Needed only when conversion and/or analysis of an input ASCII file that contains periodic variables is requested, this keyword lets the user specify the left and right boundaries of the periodic range of the degrees of freedom as two consecutive real values, respectively. The program will possibly use this information in analysis if CDISTANCE is compatible with periodic data (set to either 1 or 2) and always adds the "periodic_range" attribute to the NetCDF variable that contains the degrees of freedom if conversion is requested (see also elsewhere).
For periodic variables CAMPARI uses the interval [-180°:180°] as reference. This can be tricky if periodic variables are defined on a different interval, e.g., [0°:360°]. In that case NCDM_PRDCRNG should still be set to -180 180 as the correct remapping happens automatically. In other words, even if the periodic variables take values in [0°:360°], setting NCDM_PRDCRNG to 0 360, or having the periodic attribute of the NetCDF variable (see also elsewhere) to 0 360, would generate wrong results. These aspects are presented and discussed in Part B of Tutorial 14, especially in Step B.4.

NCDM_NMFV

This keyword is useful to inform the program on the name of the variable in the input NetCDF file that contains the values of the coordinates per frame to be analyzed. The default choice is "featuresvals". It is important to note that there are tools that allow renaming variables, dimensions and attributes of a NetCDF database (see NCDM_NCFILE, NetCDF documentation and the Internet) as the software does not offer the possibility to specify names for all the required specifications of the standard it expects. It is also used to turn the name of the same variable from the default ("featuresvals") in case conversion of an input ASCII file is requested.

NCDM_ANONAS

This simple logical (1 is true) allows the user to activate the analysis (structural clustering and possibly downstream routines) on the input ASCII file according to the specifications in the key file.

NCDM_NRFEATS

Number of features contained in the input ASCII file, required for conversion and/or analysis. This number has to strictly correspond to the number of columns of the input ASCII file (see also elsewhere). The only way to subsample the provided degrees of freedom is to use the dedicated analysis input file. Disabled by default, the user can request specific (but slow) row-by-row checks of the integrity of the input ASCII file (see NCDM_CHECKAS).

NCDM_NRFRMS

Number of frames contained in the input ASCII file, required for conversion and/or analysis. This keyword corresponds to the number of rows in the input ASCII file that contain the degrees of freedom (number of frames). This means that the possible presence of feature weights in the ASCII file must not be accounted for here (see elsewhere for the ASCII standard that the data mining executable expects).

NCDM_CFILE

This keyword provides the path and location to an input file selecting a subset of the system coordinates for structural clustering and dependent analyses. It is always a column list of integer indices specifying a set of the system degrees of freedom encoded in the input files (NCDM_NCFILE or NCDM_ASFILE).

NCDM_FRAMESFILE

It is possible to analyze just a specific set of frames from the input file (NCDM_NCFILE or NCDM_ASFILE). The entries in NCDM_FRAMESFILE always refer to the frames, viz., possible features weights are adjusted automatically to match the specified frames, regardless input file of origin (ASCII file or NetCDF file). Referring to the specular keyword FRAMESFILE, the frames file for the NetCDF analysis mode is always read "as is" (it is not sorted and duplicates are allowed). Therefore, frames weights are not allowed and the contents of TRAJBREAKSFILE and/or TRAJLINKSFILE have to be treated accordingly. This means that the numbers specified in TRAJLINKSFILE and/or TRAJBREAKSFILE are interpreted as referring to the lines of the frames file. This is because the frames file becomes the actual trajectory. For example, if the first two frames in the frames file are 1541 and 760, then specifying a 2 in the break file entails enforcing a break after the second snapshot of the frames file, i.e. of the actual trajectory (here snapshot 760 of the original trajectory) with respect to everything that follows in the actual trajectory (i.e. in the frames file after the second line). These changes in connectivity are reflected in network analyses (see for example TMAT_MD), and in the relevant output files (e.g., STRUCT_CLUSTERING.graphml and TMAT_xxxxxx_yyy.dat). The same behavior involves all that keyords that specify frames numbering, e.g. INISYNSNAP. For example, if frames 760 of the original trajectory has to be served as INISYNSNAP and its position in the frames file is in the second line, than a 2 has to be specified as INISYNSNAP. The other keywords affetcted are: ENDSYNSNAP, folded set, unfolded set and CPROGINDSTART. The format of the NCDM_FRAMESFILE file is a single column of integers and is detailed elsewhere. The choices made with NCDM_FRAMESFILE are not reflected in the possible conversion of an ASCII file, but are reflected in the output database in case an input NetCDF file is provided and debug output requested (see NCDM_WRTINPUT). As a final note, the use of NCDM_FRAMESFILE with CCOLLECT not equal to 1 is explicitly disabled.

NCDM_CHECKAS

This simple logical (disabled by default, 1 is true) allows the user to check the integrity (appropriateness) of the numbers contained in the colums of the input ASCII file. This considerably slows down the reading of the input ASCII file and should be enabled only for debug purposes.


(back to top)