Glossary

This is a glossary page containing scientific concepts for the discussion of potential optimization, as well as the (automatically generated) documentation of ForceBalance keywords.

Scientific concepts

• Empirical parameter : Any adjustable parameter in the empirical potential that affects the potential energy, such as the partial charge on an atom, the equilibrium length of a chemical bond, or the fraction of Hartree-Fock exchange in a density functional.

• Empirical Potential : A formula that contains empirical parameters and computes the potential energy of a collection of atoms. Note that in ForceBalance this is used very loosely; even a DFT functional may contain many empirical parameters, and ForceBalance has the ability to optimize these as well!

• Target : A reference data set from high-level theoretical calculations or experimental measurements, paired with a procedure to simulate the same quantity using the force field. The objective function is the sum of one or more targets.

• Force field : This term is used interchangeably with empirical potential.

• Functional form : The mathematical functions in the force field. For instance, a CHARMM-type functional form has harmonic interactions for bonds and angles, a cosine expansion for the dihedrals, Coulomb interactions between point charges and Lennard-Jones terms for van der Waals interactions.

• Reference data : In general, any accurately known quantity that the force field is optimized to reproduce. Reference data can come from either theory or experiment. For instance, energies and forces from a high-level QM method can be used as reference data (for instance, a CHARMM-type force field can be fitted to reproduce forces from a DFT or MP2 calculation), or a force field can be optimized to reproduce the experimental density of a liquid, its enthalpy of vaporization or the solvation free energy of a solute.

Note: Failed to import the optional openff.evaluator package. Note: Failed to import the optional openforcefield package.

Option index: General options

This section contains a listing of the general options available when running a ForceBalance job, which go into the $options section. The general options are global for the ForceBalance job, in contrast to 'Target options' which apply to one target within a job (described in the next section). The option index is generated by running make-option-index.py.

• ADAPTIVE_DAMPING (Float)
  One-line description : Damping factor that ties down the trust radius to trust0; decrease for a more variable step size.
  Default Value : 0.5
  Scope : Main optimizer (Optional)
  Full description : See documentation for adaptive_factor.
  Recommendation : A larger value will ensure that the trust radius never exceeds the original value by more than a small percentage. 0.5 is a reasonable value to start from.

• ADAPTIVE_FACTOR (Float)
  One-line description : The step size is increased / decreased by up to this much in the event of a good / bad step; increase for a more variable step size.
  Default Value : 0.25
  Scope : Main optimizer (Optional)
  Full description : Adaptive adjustment of the step size in trust-radius Newton Raphson. If the optimizer takes a good step, the step is increased as follows:

   trust += adaptive_factor*trust*np.exp(-adaptive_damping*(trust/self.trust0 - 1))

  Note that the adaptive_damping option makes sure that the trust radius increases by a smaller factor the further it deviates from the original trust radius (trust0). On the other hand, if the optimizer takes a bad step, the step is reduced as follows:

   trust = max(ndx*(1./(1+adaptive_factor)), self.mintrust)

Recommendation : 0.2 is a conservative value, 0.5 for big step size adjustments.

• AMBERHOME (String)
  One-line description : Path to AMBER installation directory (leave blank to use AMBERHOME environment variable.
  Default Value : None
  (Needs full documentation)

• AMOEBA_EPS (Float)
  One-line description : The AMOEBA mutual polarization criterion.
  Default Value : None
  (Needs full documentation)

• AMOEBA_POL (String)
  One-line description : The AMOEBA polarization type, either direct, mutual, or nonpolarizable.
  Default Value : None
  (Needs full documentation)

• ASYNCHRONOUS (Bool)
  One-line description : Execute Work Queue tasks and local calculations asynchronously for improved speed
  Default Value : 0
  Scope : Targets that use Work Queue (Optional)
  Full description : When using Work Queue to distribute computationally intensive tasks (e.g. condensed phase simulations), it is computationally efficient to run the local jobs concurrently rather than wait for the tasks to finish. Setting this flag allows local evaluation of targets to proceed while the Work Queue runs in the background, which speeds up the calculation compared to waiting idly for the Work Queue tasks to complete.
  Recommendation : If using Work Queue to distribute tasks for some targets, set to True.

• BACKUP (Bool)
  One-line description : Write temp directories to backup before wiping them
  Default Value : 1
  Scope : All force field optimizations (Optional)

• CONSTRAIN_CHARGE (Bool)
  One-line description : Specify whether to constrain the charges on the molecules.
  Default Value : 0
  Scope : Force fields with point charges (Optional)
  Full description : It is important for force fields with point charges to not change the overall charge on the molecule or ion. Setting this option will activate a linear transformation which projects out the direction in parameter space that changes the net charge.
  Recommendation : Either set to true and check your output carefully, or use "eval" statements in the force field file for finer control.

• CONSTRAIN_H (Bool)
  One-line description : Perform calculations with contrained hydrogen bond lengths.
  Default Value : 0
  (Needs full documentation)

• CONTINUE (Bool)
  One-line description : Continue the current run from where we left off (supports mid-iteration recovery).
  Default Value : 0
  (Needs full documentation)

• CONVERGE_LOWQ (Bool)
  One-line description : Allow convergence on "low quality" steps
  Default Value : 0
  (Needs full documentation)

• CONVERGENCE_GRADIENT (Float)
  One-line description : Convergence criterion of gradient norm
  Default Value : 0.001
  Scope : Main optimizer (Optional)
  Full description : The main optimizer will quit when the objective function gradient falls below this number. Since this is a newly implemented option, I can't say when this option will fail.
  Recommendation : Leave at the default, or set to several orders of magnitude below a typical value of the gradient (perhaps the gradient at the start of the optimization.)

• CONVERGENCE_OBJECTIVE (Float)
  One-line description : Convergence criterion of objective function (in MainOptimizer this is the stdev of X2 over [objective_history] steps)
  Default Value : 0.0001
  Scope : Main optimizer (Optional)
  Full description : The main optimizer will quit when the last ten good values of the objective function have a standard deviation that falls below this number. We use the last ten good values (instead of the latest change in the objective function), otherwise this condition would be triggered by taking tiny steps.
  Recommendation : Decrease this value if it's being triggered by small step sizes.

• CONVERGENCE_STEP (Float)
  One-line description : Convergence criterion of step size (just needs to fall below this threshold)
  Default Value : 0.0001
  Scope : Main optimizer (Optional)
  Full description : The main optimizer will quit when the step size falls below this number. This happens if we are approaching a local minimum, or if the optimizer is constantly taking bad steps and the trust radius is reduced until it falls below this number. In the latter case, this usually means that the derivatives are wrong.
  Recommendation : Make sure that this value is much smaller than trust0.

• CRITERIA (Int)
  One-line description : The number of convergence criteria that must be met for main optimizer to converge
  Default Value : 1
  (Needs full documentation)

• DUPLICATE_PNAMES (Bool)
  One-line description : Allow duplicate parameter names (only if you know what you are doing!
  Default Value : 0
  (Needs full documentation)

• EIG_LOWERBOUND (Float)
  One-line description : Minimum eigenvalue for applying steepest descent correction
  Default Value : 0.0001
  Scope : Main optimizer (Optional)
  Full description : The main optimizer will misbehave if there are negative or very small eigenvalues in the objective function Hessian. In the former case the optimizer will travel toward a saddle point (or local maximum), and in the latter case the matrix inversion will fail because of the matrix singularity. If the smallest eigenvalue is below this value, then a multiple of the identity matrix is added to the Hessian to increase the smallest eigenvalue to at least this value.
  Recommendation : Shouldn't have to worry about this setting, unless the optimizer appears to be taking bad steps or inverting nearly singular matrices.

• ERROR_TOLERANCE (Float)
  One-line description : Error tolerance; the optimizer will only reject steps that increase the objective function by more than this number.
  Default Value : 0.0
  Scope : Main optimizer (Optional)
  Full description : In some targets (e.g. condensed phase properties), the contribution to the objective function may contain statistical noise and cause the optimization step to be rejected. Introducing an error tolerance allows the optimization to continue despite some apparent roughness in the objective function surface.
  Recommendation : Set to zero for targets that don't have statistical noise. Otherwise, choose a value based on the rough size of the objective function and the weight of the statistically noisy targets.

• FFDIR (String)
  One-line description : Directory containing force fields, relative to project directory
  Default Value : forcefield
  Scope : All force field optimizations (Optional)
  Recommendation : Unless you're using a nonstandard location for force field files, you probably shouldn't change this.

• FINITE_DIFFERENCE_FACTOR (Float)
  One-line description : Make sure that the finite difference step size does not exceed this multiple of the trust radius.
  Default Value : 0.1
  (Needs full documentation)

• FINITE_DIFFERENCE_H (Float)
  One-line description : Step size for finite difference derivatives in many functions
  Default Value : 0.001
  Scope : fdcheck_G or fdcheck_H job types, or whenever the objective function is evaluated using finite difference (Optional)
  Full description : When the objective function derivatives are checked using finite difference, or when the objective function derivative requires finite difference, this is the step size that is used (in the mathematical space). The actual parameter in the force field is changed by this amount times the rescaling factor.
  Recommendation : 1e-2 to 1e-4; run FDCheckG to see if derivatives are accurate; if derivatives are inaccurate then adjust accordingly. If the objective function itself requires finite difference, there will still be a difference because FDCheckG(H) uses an accurate seven-point (five-point) stencil. Make sure that the derivatives agree before settling on a value to use.

• FORCEFIELD (List)
  One-line description : The names of force fields, corresponding to directory forcefields/file_name.(itp,xml,prm,frcmod,mol2)
  Default Value : []
  Scope : All force field optimizations (Required)

• GMXPATH (String)
  One-line description : Path for GROMACS executables (if not the default)
  Default Value :
  Scope : Targets that use GROMACS (Required)
  Full description : Specify the path where GROMACS executables are installed, most likely ending in 'bin'. Note that executables are only installed 'bin' if the program is installed using 'make install'; this will NOT be the case if you simply ran 'make'.
  Recommendation : Depends on your local installation and environment.

• GMXSUFFIX (String)
  One-line description : The suffix of GROMACS executables
  Default Value :
  Scope : Targets that use GROMACS (Optional)
  Full description : Depending on how GROMACS is configured and installed, a suffix may be appended to executable names. If there is a suffix, it needs to be specified here (or else ForceBalance will not find the GROMACS executable and it will crash.
  Recommendation : Depends on your local installation and environment.

• HAVE_VSITE (Bool)
  One-line description : Specify whether there are virtual sites in the simulation (being fitted or not). Enforces calculation of vsite positions.
  Default Value : 0
  (Needs full documentation)

• JOBTYPE (Allcap)
  One-line description : The calculation type, defaults to a single-point evaluation of objective function.
  Default Value : single
  Scope : All force field optimizations (Required)
  Full description : Here you may specify the type of ForceBalance job. This ranges from gradient-based and stochastic optimizations to simple scans over the parameter space and finite difference checking of gradients.
  Recommendation : See the Optimizer class documentation for which optimizer is best suited for you.

• LM_GUESS (Float)
  One-line description : Guess value for bracketing line search in trust radius algorithm
  Default Value : 1.0
  (Needs full documentation)

• LOGARITHMIC_MAP (Bool)
  One-line description : Optimize in the space of log-variables
  Default Value : 0
  (Needs full documentation)

• MAXSTEP (Int)
  One-line description : Maximum number of steps in an optimization
  Default Value : 100
  Scope : All iterative optimization jobs (Optional)
  Recommendation : At least 100 optimization steps are recommended.

• MINTRUST (Float)
  One-line description : Minimum trust radius (if the trust radius is tiny, then noisy optimizations become really gnarly)
  Default Value : 0.0
  (Needs full documentation)

• NORMALIZE_WEIGHTS (Bool)
  One-line description : Normalize the weights for the fitting targets
  Default Value : 1
  (Needs full documentation)

• OBJECTIVE_HISTORY (Int)
  One-line description : Number of good optimization steps to average over when checking the objective convergence criterion
  Default Value : 2
  (Needs full documentation)

• PENALTY_ADDITIVE (Float)
  One-line description : Factor for additive penalty function in objective function
  Default Value : 0.0
  Scope : Objective function (Optional)
  Full description : Add a penalty to the objective function (e.g. L2 or L1 norm) with this prefactor. Using an additive penalty requires an assessment of the order of magnitude of the objective function, but it is closer to the statistical concept of ridge or LASSO regression.
  Recommendation : No recommendation; run a single-point calculation to choose a prefactor. Consider 0.01 for an objective function of order 1.

• PENALTY_ALPHA (Float)
  One-line description : Extra parameter for fusion penalty function. Dictates position of log barrier or L1-L0 switch distance
  Default Value : 0.001
  (Needs full documentation)

• PENALTY_HYPERBOLIC_B (Float)
  One-line description : Cusp region for hyperbolic constraint; for x=0, the Hessian is a/2b
  Default Value : 1e-06
  (Needs full documentation)

• PENALTY_MULTIPLICATIVE (Float)
  One-line description : Factor for multiplicative penalty function in objective function
  Default Value : 0.0
  Scope : Objective function (Optional)
  Full description : Multiply the objective function by (1+X) where X is this value. Using an multiplicative penalty works well for objective functions of any size but it is not equivalent to statistical regularization methods.
  Recommendation : A value of 0.01 tends to keep the length of the parameter vector from exceeding 1.

• PENALTY_POWER (Float)
  One-line description : Power of the Euclidean norm of the parameter vector (default 2.0 is normal L2 penalty)
  Default Value : 2.0
  (Needs full documentation)

• PENALTY_TYPE (String)
  One-line description : Type of the penalty: L2, L1 or Box
  Default Value : L2
  Scope : All force field optimizations (Optional)
  Full description : To prevent the optimization from changing the parameters too much, an additional penalty is applied to the objective function that depends linearly (L1) or quadratically (L2) on the norm of the parameter displacement vector. L1 corresponds to LASSO regularization while L2 is known as Tikhonov regularization or ridge regression.
  Recommendation : L2; tested and known to be working. Implementation of L1 in progress.

• PRINT_GRADIENT (Bool)
  One-line description : Print the objective function gradient at every step
  Default Value : 1
  (Needs full documentation)

• PRINT_HESSIAN (Bool)
  One-line description : Print the objective function Hessian at every step
  Default Value : 0
  (Needs full documentation)

• PRINT_PARAMETERS (Bool)
  One-line description : Print the mathematical and physical parameters at every step
  Default Value : 1
  (Needs full documentation)

• PRIORS (Section)
  One-line description : Paste priors into the input file for them to be read in directly
  Default Value : OrderedDict()
  (Needs full documentation)

• READ_MVALS (Section)
  One-line description : Paste mathematical parameters into the input file for them to be read in directly
  Default Value : None
  Scope : All force field optimizations (Optional)
  Full description : Read in mathematical parameters before starting the optimization. There is a standardized syntax, given by:

  read_mvals
   0 [ -2.9766e-01 ] : VDWSOW
   1 [  2.2283e-01 ] : VDWTOW
   2 [ -1.1138e-03 ] : BONDSBHWOW
   3 [ -9.0883e-02 ] : BONDSKHWOW
   \read_mvals 

  
  Recommendation : If you run the main optimizer, it will print out this block at the very end for you to use and/or modify.

• READ_PVALS (Section)
  One-line description : Paste physical parameters into the input file for them to be read in directly
  Default Value : None
  Scope : All force field optimizations (Optional)
  Full description : Read in physical parameters before starting the optimization. There is a standardized syntax, given by:

  read_pvals
    0 [  2.9961e-01 ] : VDWSOW
    1 [  1.2009e+00 ] : VDWTOW
    2 [  9.5661e-02 ] : BONDSBHWOW
    3 [  4.1721e+05 ] : BONDSKHWOW
    \read_pvals 

  These are the actual numbers that go into the force field file, so note the large changes in magnitude.
  Recommendation : If you run the main optimizer, it will print out this block at the very end for you to use and/or modify.

• READCHK (String)
  One-line description : Name of the restart file we read from
  Default Value : None
  Scope : Main optimizer (Optional)
  Full description : The main optimizer has the ability to pick up where it left off by reading / writing checkpoint files. Here you may specify the checkpoint file to read in from a previous optimization run. This is equivalent to reading in stored parameter values, except the gradient and Hessian (which contains memory from previous steps) is recorded too.

• REEVALUATE (Bool)
  One-line description : Re-evaluate the objective function and gradients when the step is rejected (for noisy objective functions).
  Default Value : None
  (Needs full documentation)

• RIGID_WATER (Bool)
  One-line description : Perform calculations using rigid water molecules.
  Default Value : 0
  (Needs full documentation)

• RPMD_BEADS (Int)
  One-line description : Number of beads in ring polymer MD (zero to disable)
  Default Value : 0
  (Needs full documentation)

• SCAN_VALS (String)
  One-line description : Values to scan in the parameter space, given like this: -0.1:0.1:11
  Default Value : None
  Scope : scan_mvals and scan_pvals job types (Optional)
  Full description : This specifies a range of parameter values to scan in a uniform grid. scan_mvals works in the mathematical parameter space while scan_pvals works in the physical parameter space. The syntax is lower:upper:nsteps (just like numpy.linspace) . Both lower and upper limits are included in the range.
  Recommendation : For scan_mvals, a range of values between -1 and +1 is recommended; for scan_pvals, choose values close to the physical parameter value.

• SCANINDEX_NAME (List)
  One-line description : Parameter name to scan over (should convert to a numerical index)
  Default Value : []
  Scope : scan_mvals and scan_pvals job types (Optional)
  Full description : ForceBalance assigns to each adjustable parameter a 'parameter name'. By specifying this option, this tells the parameter scanner to locate the correct parameter with the specified name and then scan over it.
  Recommendation : Look at the printout from a single-point job to determine the parameter names.

• SCANINDEX_NUM (List)
  One-line description : Numerical index of the parameter to scan over
  Default Value : []
  Scope : scan_mvals and scan_pvals job types (Optional)
  Full description : ForceBalance assigns to each adjustable parameter a 'parameter number' corresponding to its position in the parameter vector. This tells the parameter scanner which number to scan over.
  Recommendation : Look at the printout from a single-point job to decide which parameter number you wish to scan over.

• SEARCH_TOLERANCE (Float)
  One-line description : Search tolerance; used only when trust radius is negative, dictates convergence threshold of nonlinear search.
  Default Value : 0.0001
  (Needs full documentation)

• STEP_LOWERBOUND (Float)
  One-line description : Optimization will "fail" if step falls below this size
  Default Value : 1e-06
  (Needs full documentation)

• TINKERPATH (String)
  One-line description : Path for TINKER executables (if not the default)
  Default Value : /home/leeping/opt/tinker/current/bin
  Scope : Targets that use TINKER (Required)
  Recommendation : Depends on your local installation and environment.

• TRUST0 (Float)
  One-line description : Levenberg-Marquardt trust radius; set to negative for nonlinear search
  Default Value : 0.1
  Scope : Main optimizer (Optional)
  Full description : The main optimizer uses a trust radius which 'adapts' (i.e. increases or decreases) based on whether the last step was a good or bad step. 'trust0' provides the starting trust radius, and the trust radius is not allowed to increase too much from trust0.
  Recommendation : Increase from the default if the optimizer takes many good steps but takes too long; decrease if the optimizer takes many bad steps.

• USE_PVALS (Bool)
  One-line description : Bypass the transformation matrix and use the physical parameters directly
  Default Value : 0
  (Needs full documentation)

• VERBOSE_OPTIONS (Bool)
  One-line description : Set to false to suppress printing options that are equal to their defaults
  Default Value : 0
  (Needs full documentation)

• VSITE_BONDS (Bool)
  One-line description : Generate bonds from virtual sites to host atom bonded atoms.
  Default Value : 0
  (Needs full documentation)

• WQ_PORT (Int)
  One-line description : The port number to use for Work Queue
  Default Value : 0
  (Needs full documentation)

• WRITECHK (String)
  One-line description : Name of the restart file we write to (can be same as readchk)
  Default Value : None
  Scope : Main optimizer (Optional)
  Full description : The main optimizer has the ability to pick up where it left off by reading / writing checkpoint files. Here you may specify the checkpoint file to write after the job is finished.
  Recommendation : Writing the checkpoint file is highly recommended.

• WRITECHK_STEP (Bool)
  One-line description : Write the checkpoint file at every optimization step
  Default Value : 1
  Scope : Main optimizer when 'writechk' is turned on (Optional)
  Full description : Write a checkpoint file every single step, not just after the job is finished.
  Recommendation : Useful if you want to quit an optimization before it finishes and restart, but make sure you don't overwrite existing checkpoint files by accident.

• ZEROGRAD (Int)
  One-line description : Set to a nonnegative number to turn on zero gradient skipping at that optimization step.
  Default Value : -1
  (Needs full documentation)

Option index: Target options

This section contains a listing of the target options available when running a ForceBalance job, which go into the $tgt_opts section. There can be multiple $tgt_opts sections in a ForceBalance input file, one for each target.

• ABSOLUTE (Bool)
  One-line description : When matching energies in AbInitio, do not subtract the mean energy gap.
  Default Value : 0
  (Needs full documentation)

• ADAPT_ERRORS (Bool)
  One-line description : Adapt to simulation uncertainty by combining property estimations and adjusting simulation length.
  Default Value : 0
  (Needs full documentation)

• ALL_AT_ONCE (Bool)
  One-line description : Compute all energies and forces in one fell swoop where possible(as opposed to calling the simulation code once per snapshot)
  Default Value : 1
  (Needs full documentation)

• AMBER_LEAPCMD (String)
  One-line description : File containing commands for "tleap" when setting up AMBER simulations.
  Default Value : None
  (Needs full documentation)

• ANISOTROPIC_BOX (Bool)
  One-line description : Enable anisotropic box scaling (e.g. for crystals or two-phase simulations) in external npt.py script
  Default Value : 0
  (Needs full documentation)

• ATTENUATE (Bool)
  One-line description : Normalize interaction energies using 1/(denom**2 + reference**2) only for repulsive interactions greater than denom.
  Default Value : 0
  (Needs full documentation)

• CAUCHY (Bool)
  One-line description : Normalize interaction energies each using 1/(denom**2 + reference**2) which resembles a Cauchy distribution
  Default Value : 0
  (Needs full documentation)

• COORDS (String)
  One-line description : Coordinates for single point evaluation; if not provided, will search for a default.
  Default Value : None
  (Needs full documentation)

• DIPOLE_DENOM (Float)
  One-line description : Dipole normalization (Debye) ; set to 0 if a zero weight is desired
  Default Value : 1.0
  (Needs full documentation)

• DO_COSMO (Bool)
  One-line description : Call Q-Chem to do MM COSMO on MM snapshots.
  Default Value : 0
  (Needs full documentation)

• ENERGY (Bool)
  One-line description : Enable the energy objective function
  Default Value : 1
  (Needs full documentation)

• ENERGY_ASYMMETRY (Float)
  One-line description : Snapshots with (E_MM - E_QM) < 0.0 will have their weights increased by this factor.
  Default Value : 1.0
  (Needs full documentation)

• ENERGY_DENOM (Float)
  One-line description : Energy normalization for binding energies in kcal/mol (default is to use stdev)
  Default Value : 1.0
  (Needs full documentation)

• ENERGY_RMS_OVERRIDE (Float)
  One-line description : If nonzero, override the Energy RMS used to normalize the energy part of the objective function term
  Default Value : 0.0
  (Needs full documentation)

• ENERGY_UPPER (Float)
  One-line description : Upper energy cutoff (in kcal/mol); super-repulsive interactions are given zero weight
  Default Value : 30.0
  (Needs full documentation)

• ENGINE (Allcap)
  One-line description : The external code used to execute the simulations (GMX, TINKER, AMBER, OpenMM)
  Default Value : None
  (Needs full documentation)

• EPSGRAD (Float)
  One-line description : Gradient below this threshold will be set to zero.
  Default Value : 0.0
  (Needs full documentation)

• EQ_STEPS (Int)
  One-line description : Number of time steps for the equilibration run.
  Default Value : 20000
  (Needs full documentation)

• EVALUATOR_INPUT (String)
  One-line description : JSON file containing options for the OpenFF Evaluator target. If not provided, will search for a default.
  Default Value : evaluator_input.json
  (Needs full documentation)

• EXPDATA_TXT (String)
  One-line description : Text file containing experimental data.
  Default Value : expset.txt
  (Needs full documentation)

• FD_PTYPES (List)
  One-line description : The parameter types that are differentiated using finite difference
  Default Value : []
  Scope : All target types (Optional)
  Full description : To compute the objective function derivatives, some components may require numerical finite difference in the derivatives. Here you may specify the parameter types that finite difference is applied to, or write 'ALL' to take finite-difference derivatives in all parameter types.
  Recommendation : If you aren't sure, either use 'ALL' to do finite difference in each component (this is costly), or run a fdcheckG(H) job with this option set to 'NONE' to check which analytic derivatives are missing.

• FDGRAD (Bool)
  One-line description : Finite difference gradient of objective function w/r.t. specified parameters
  Default Value : 0
  Scope : All target types (Optional)
  Full description : When this option is enabled, finite difference gradients will be enabled for selected parameter types (using the fd_ptypes option). Gradients are computed using two-point finite difference of the objective function.
  Recommendation : If analytic derivatives are implemented (and correct), then they are much faster than finite difference derivatives. Run the 'fdcheckG' routine with this option set to Off to check which finite difference derivatives you need.

• FDHESS (Bool)
  One-line description : Finite difference Hessian of objective function w/r.t. specified parameters
  Default Value : 0
  Scope : All target types (Optional)
  Full description : When this option is enabled, finite difference Hessians will be enabled for selected parameter types (using the fd_ptypes option). Hessians are computed using two-point finite difference of the gradient.
  Recommendation : Run the 'fdcheckH' routine with this option set to Off to check which finite difference Hessian elements you need. Note that this requires a very large number of objective function evaluations, so use sparingly.

• FDHESSDIAG (Bool)
  One-line description : Finite difference Hessian diagonals w/r.t. specified parameters (costs 2np times a objective calculation)
  Default Value : 0
  Scope : All target types (Optional)
  Full description : When this option is enabled, finite difference gradients and Hessian diagonal elements will be enabled for selected parameter types (using the fd_ptypes option). This is done using a three-point finite difference of the objective function.
  Recommendation : Use this as a substitute for 'fdgrad'; it doubles the cost but provides more accurate derivatives plus the Hessian diagonal values (these are very nice for quasi-Newton optimizers like BFGS).

• FITATOMS (String)
  One-line description : Number of fitting atoms; defaults to all of them. Use a comma and dash style list (1,2-5), atoms numbered from one, inclusive
  Default Value : 0
  Scope : Force and energy matching (Optional)
  Full description : Choose a subset of atoms to fit forces to. This is useful in situations where it is undesirable to fit the forces on part of the system (e.g. the part that is described by another force field.) Currently, you are only allowed to choose from the atoms in the front of the trajectory; soon this will be expanded for random flexibility (see 'shots'). However, random coordinate selections are not allowed. ;)
  Recommendation : Situation-dependent; this should be based on the part of the system that you're fitting, or leave blank if you're fitting the whole system.

• FORCE (Bool)
  One-line description : Enable the force objective function
  Default Value : 1
  (Needs full documentation)

• FORCE_AVERAGE (Bool)
  One-line description : Average over all atoms when normalizing force errors.
  Default Value : 0
  (Needs full documentation)

• FORCE_CUDA (Bool)
  One-line description : Force the external npt.py script to crash if CUDA Platform not available
  Default Value : 0
  (Needs full documentation)

• FORCE_MAP (String)
  One-line description : The resolution of mapping interactions to net forces and torques for groups of atoms. In order of resolution: molecule > residue > charge-group
  Default Value : residue
  (Needs full documentation)

• FORCE_RMS_OVERRIDE (Float)
  One-line description : If nonzero, override the Force RMS used to normalize the energy part of the objective function term
  Default Value : 0.0
  (Needs full documentation)

• FRAGMENT1 (String)
  One-line description : Interaction fragment 1: a selection of atoms specified using atoms and dashes, e.g. 1-6 to select the first through sixth atom (i.e. list numbering starts from 1)
  Default Value :
  (Needs full documentation)

• FRAGMENT2 (String)
  One-line description : Interaction fragment 2: a selection of atoms specified using atoms and dashes, e.g. 7-11 to select atoms 7 through 11.
  Default Value :
  (Needs full documentation)

• GAS_COORDS (String)
  One-line description : Provide file name for gas phase coordinates.
  Default Value : None
  (Needs full documentation)

• GAS_EQ_STEPS (Int)
  One-line description : Number of time steps for the gas equilibration run, if different from default.
  Default Value : 10000
  (Needs full documentation)

• GAS_INTERVAL (Float)
  One-line description : Time interval for saving coordinates for the gas production run (if zero, use default in external script.)
  Default Value : 0.1
  (Needs full documentation)

• GAS_MD_STEPS (Int)
  One-line description : Number of time steps for the gas production run, if different from default.
  Default Value : 100000
  (Needs full documentation)

• GAS_TIMESTEP (Float)
  One-line description : Time step size for the gas simulation (if zero, use default in external script.).
  Default Value : 1.0
  (Needs full documentation)

• GMX_EQ_BAROSTAT (String)
  One-line description : Name of the barostat to use for equilibration.
  Default Value : berendsen
  (Needs full documentation)

• GMX_MDP (String)
  One-line description : Gromacs .mdp files. If not provided, will search for default.
  Default Value : None
  (Needs full documentation)

• GMX_NDX (String)
  One-line description : Gromacs .ndx files. If not provided, will search for default.
  Default Value : None
  (Needs full documentation)

• GMX_TOP (String)
  One-line description : Gromacs .top files. If not provided, will search for default.
  Default Value : None
  (Needs full documentation)

• HFE_PRESSURE (Float)
  One-line description : Simulation temperature for hydration free energies (atm)
  Default Value : 1.0
  (Needs full documentation)

• HFE_TEMPERATURE (Float)
  One-line description : Simulation temperature for hydration free energies (Kelvin)
  Default Value : 298.15
  (Needs full documentation)

• HFEDATA_TXT (String)
  One-line description : Text file containing experimental data.
  Default Value : hfedata.txt
  (Needs full documentation)

• HFEMODE (String)
  One-line description : Method for calculating hydration energies (single point, FEP, TI).
  Default Value : single
  (Needs full documentation)

• HVAP_SUBAVERAGE (Bool)
  One-line description : Don't target the average enthalpy of vaporization and allow it to freely float (experimental)
  Default Value : 0
  (Needs full documentation)

• INTER_TXT (String)
  One-line description : Text file containing interacting systems. If not provided, will search for a default.
  Default Value : interactions.txt
  (Needs full documentation)

• LIPID_COORDS (String)
  One-line description : Provide file name for lipid coordinates.
  Default Value : None
  (Needs full documentation)

• LIPID_EQ_STEPS (Int)
  One-line description : Number of time steps for the lipid equilibration run.
  Default Value : 1000
  (Needs full documentation)

• LIPID_INTERVAL (Float)
  One-line description : Time interval for saving coordinates for the lipid production run.
  Default Value : 0.1
  (Needs full documentation)

• LIPID_MD_STEPS (Int)
  One-line description : Number of time steps for the lipid production run.
  Default Value : 10000
  (Needs full documentation)

• LIPID_TIMESTEP (Float)
  One-line description : Time step size for the lipid simulation.
  Default Value : 1.0
  (Needs full documentation)

• LIQUID_COORDS (String)
  One-line description : Provide file name for condensed phase coordinates.
  Default Value : None
  (Needs full documentation)

• LIQUID_EQ_STEPS (Int)
  One-line description : Number of time steps for the liquid equilibration run.
  Default Value : 1000
  (Needs full documentation)

• LIQUID_FDIFF_H (Float)
  One-line description : Step size for finite difference derivatives for liquid targets in pure_num_grad
  Default Value : 0.01
  (Needs full documentation)

• LIQUID_INTERVAL (Float)
  One-line description : Time interval for saving coordinates for the liquid production run.
  Default Value : 0.1
  (Needs full documentation)

• LIQUID_MD_STEPS (Int)
  One-line description : Number of time steps for the liquid production run.
  Default Value : 10000
  (Needs full documentation)

• LIQUID_TIMESTEP (Float)
  One-line description : Time step size for the liquid simulation.
  Default Value : 1.0
  (Needs full documentation)

• MANUAL (Bool)
  One-line description : Give the user a chance to fill in condensed phase stuff on the zeroth step
  Default Value : 0
  (Needs full documentation)

• MD_STEPS (Int)
  One-line description : Number of time steps for the production run.
  Default Value : 50000
  (Needs full documentation)

• MD_THREADS (Int)
  One-line description : Set the number of threads used by Gromacs or TINKER processes in MD simulations
  Default Value : 1
  (Needs full documentation)

• MINIMIZE_ENERGY (Bool)
  One-line description : Minimize the energy of the system prior to running dynamics
  Default Value : 1
  (Needs full documentation)

• MOL2 (List)
  One-line description : List of .mol2 files needed to set up the system (in addition to any specified under forcefield)
  Default Value : []
  (Needs full documentation)

• MTS_INTEGRATOR (Bool)
  One-line description : Enable multiple-timestep integrator in external npt.py script
  Default Value : 0
  (Needs full documentation)

• N_MCBAROSTAT (Int)
  One-line description : Number of steps in the liquid simulation between MC barostat volume adjustments.
  Default Value : 25
  (Needs full documentation)

• N_MOLECULES (Int)
  One-line description : Provide the number of molecules in the structure (defaults to auto-detect).
  Default Value : -1
  (Needs full documentation)

• N_SIM_CHAIN (Int)
  One-line description : Number of simulations required to calculate quantities.
  Default Value : 1
  (Needs full documentation)

• NAME (List)
  One-line description : The name of the target, corresponding to the directory targets/name ; may provide a list if multiple targets have the same settings
  Default Value : []
  Scope : All targets (Required)
  Recommendation : Choose a descriptive name and make sure all targets have different names.

• NONBONDED_CUTOFF (Float)
  One-line description : Cutoff for nonbonded interactions (passed to engines).
  Default Value : None
  (Needs full documentation)

• NORMALIZE (Bool)
  One-line description : Divide objective function by the number of snapshots / vibrations
  Default Value : 0
  (Needs full documentation)

• NVT_COORDS (String)
  One-line description : Provide file name for condensed phase NVT coordinates.
  Default Value : None
  (Needs full documentation)

• NVT_EQ_STEPS (Int)
  One-line description : Number of time steps for the liquid NVT equilibration run.
  Default Value : 10000
  (Needs full documentation)

• NVT_INTERVAL (Float)
  One-line description : Time interval for saving coordinates for the NVT simulation production run.
  Default Value : 0.1
  (Needs full documentation)

• NVT_MD_STEPS (Int)
  One-line description : Number of time steps for the liquid NVT production run.
  Default Value : 100000
  (Needs full documentation)

• NVT_TIMESTEP (Float)
  One-line description : Time step size for the NVT simulation.
  Default Value : 1.0
  (Needs full documentation)

• OPENMM_PLATFORM (String)
  One-line description : OpenMM platform. Choose either Reference, CUDA or OpenCL. AMOEBA is on Reference or CUDA only.
  Default Value : None
  (Needs full documentation)

• OPENMM_PRECISION (String)
  One-line description : Precision of OpenMM calculation if using CUDA or OpenCL platform. Choose either single, double or mixed ; defaults to the OpenMM default.
  Default Value : None
  (Needs full documentation)

• OPTGEO_OPTIONS_TXT (String)
  One-line description : Text file containing extra options for Optimized Geometry target. If not provided, will search for a default.
  Default Value : optgeo_options.txt
  (Needs full documentation)

• OPTIMIZE_GEOMETRY (Bool)
  One-line description : Perform a geometry optimization before computing properties
  Default Value : 1
  (Needs full documentation)

• PDB (String)
  One-line description : PDB file mainly used for building OpenMM and AMBER systems.
  Default Value : None
  (Needs full documentation)

• POLARIZABILITY_DENOM (Float)
  One-line description : Dipole polarizability tensor normalization (cubic Angstrom) ; set to 0 if a zero weight is desired
  Default Value : 1.0
  (Needs full documentation)

• PURE_NUM_GRAD (Bool)
  One-line description : Pure numerical gradients – launch two additional simulations for each perturbed forcefield parameter, and compute derivatives using 3-point formula. (This is very expensive and should only serve as a sanity check)
  Default Value : 0
  (Needs full documentation)

• QDATA_TXT (String)
  One-line description : Text file containing quantum data. If not provided, will search for a default (qdata.txt).
  Default Value : None
  (Needs full documentation)

• QUADRUPOLE_DENOM (Float)
  One-line description : Quadrupole normalization (Buckingham) ; set to 0 if a zero weight is desired
  Default Value : 1.0
  (Needs full documentation)

• QUANTITIES (List)
  One-line description : List of quantities to be fitted, each must have corresponding Quantity subclass
  Default Value : []
  (Needs full documentation)

• READ (String)
  One-line description : Provide a temporary directory ".tmp" to read data from a previous calculation on the initial iteration (for instance, to restart an aborted run).
  Default Value : None
  (Needs full documentation)

• REASSIGN_MODES (String)
  One-line description : Reassign modes before fitting frequencies, using either linear assignment "permute" or maximum overlap "overlap".
  Default Value : None
  (Needs full documentation)

• REMOTE (Bool)
  One-line description : Evaluate target as a remote work_queue task
  Default Value : 0
  (Needs full documentation)

• REMOTE_BACKUP (Bool)
  One-line description : When running remote target, back up files at the remote location.
  Default Value : 0
  (Needs full documentation)

• REMOTE_PREFIX (String)
  One-line description : Specify an optional prefix script to run in front of rtarget.py, for loading environment variables
  Default Value :
  (Needs full documentation)

• RESP (Bool)
  One-line description : Enable the RESP objective function
  Default Value : 0
  (Needs full documentation)

• RESP_A (Float)
  One-line description : RESP "a" parameter for strength of penalty; 0.001 is strong, 0.0005 is weak
  Default Value : 0.001
  (Needs full documentation)

• RESP_B (Float)
  One-line description : RESP "b" parameter for hyperbolic behavior; 0.1 is recommended
  Default Value : 0.1
  (Needs full documentation)

• RESTRAIN_K (Float)
  One-line description : Force constant for harmonic positional energy restraints
  Default Value : 1.0
  (Needs full documentation)

• RMSD_DENOM (Float)
  One-line description : RMSD normalization for optimized geometries in Angstrom
  Default Value : 0.1
  (Needs full documentation)

• RUN_INTERNAL (Bool)
  One-line description : For OpenMM or other codes with Python interface: Compute energies and forces internally
  Default Value : 1
  (Needs full documentation)

• SAVE_TRAJ (Int)
  One-line description : Whether to save trajectories. 0 = Never save; 1 = Delete if optimization step is good; 2 = Always save
  Default Value : 0
  (Needs full documentation)

• SELF_POL_ALPHA (Float)
  One-line description : Polarizability parameter for self-polarization correction (in debye).
  Default Value : 0.0
  (Needs full documentation)

• SELF_POL_MU0 (Float)
  One-line description : Gas-phase dipole parameter for self-polarization correction (in debye).
  Default Value : 0.0
  (Needs full documentation)

• SHOTS (Int)
  One-line description : Number of snapshots; defaults to all of the snapshots
  Default Value : -1
  Scope : Force and energy matching (Optional)
  Full description : This option allows you to choose a subset from the snapshots available in the force matching 'targets' directory. The subset is simply taken from the front of the trajectory. In the future this option will be expanded to allow a random selection of snapshots, or a specific selection
  Recommendation : 100-10,000 snapshots are recommended. Note that you need at least 3x (number of atoms) if the covariance matrix is turned on.

• SLEEPY (Int)
  One-line description : Wait a number of seconds every time this target is visited (gives me a chance to ctrl+C)
  Default Value : 0
  (Needs full documentation)

• SUBSET (String)
  One-line description : Specify a subset of molecules to fit. The rest are used for cross-validation.
  Default Value : None
  (Needs full documentation)

• TINKER_KEY (String)
  One-line description : TINKER .key files. If not provided, will search for default.
  Default Value : None
  (Needs full documentation)

• TYPE (Allcap)
  One-line description : The type of fitting target, for instance AbInitio_GMX ; this must correspond to the name of a Target subclass.
  Default Value : None
  Scope : All targets (Required)
  Full description : This is the type of target that you are running. The current accepted values for the target type are given in the beginning of the objective.py file: ABINITIO_GMX, ABINITIO_TINKER, ABINITIO_OPENMM, ABINITIO_SMIRNOFF, ABINITIO_AMBER, ABINITIO_INTERNAL, VIBRATION_TINKER, VIBRATION_GMX, VIBRATION_AMBER, VIBRATION_OPENMM, VIBRATION_SMIRNOFF, THERMO_GMX, LIQUID_OPENMM, LIQUID_SMIRNOFF, LIQUID_TINKER, LIQUID_GMX, LIQUID_AMBER, LIPID_GMX, COUNTERPOISE, THCDF_PSI4, RDVR3_PSI4, INTERACTION_AMBER, INTERACTION_GMX, INTERACTION_TINKER, INTERACTION_OPENMM, BINDINGENERGY_TINKER, BINDINGENERGY_GMX, BINDINGENERGY_OPENMM, MOMENTS_TINKER, MOMENTS_GMX, MOMENTS_OPENMM, HYDRATION_OPENMM, OPTGEO_OPENMM, OPTGEO_SMIRNOFF, OPTGEOTARGET_OPENMM, OPTGEOTARGET_SMIRNOFF, TORSIONPROFILE_OPENMM, TORSIONPROFILE_SMIRNOFF, EVALUATOR_SMIRNOFF, REMOTE_TARGET.
  Recommendation : Choose the appropriate type, and if the target type is missing, feel free to implement your own (or ask me for help).

• VDW_CUTOFF (Float)
  One-line description : Cutoff for vdW interactions if different from other nonbonded interactions
  Default Value : None
  (Needs full documentation)

• W_AL (Float)
  One-line description : Weight of average area per lipid
  Default Value : 1.0
  (Needs full documentation)

• W_ALPHA (Float)
  One-line description : Weight of thermal expansion coefficient
  Default Value : 1.0
  (Needs full documentation)

• W_CP (Float)
  One-line description : Weight of isobaric heat capacity
  Default Value : 1.0
  (Needs full documentation)

• W_ENERGY (Float)
  One-line description : Weight of energy
  Default Value : 1.0
  (Needs full documentation)

• W_EPS0 (Float)
  One-line description : Weight of dielectric constant
  Default Value : 1.0
  (Needs full documentation)

• W_FORCE (Float)
  One-line description : Weight of atomistic forces
  Default Value : 1.0
  (Needs full documentation)

• W_HVAP (Float)
  One-line description : Weight of enthalpy of vaporization
  Default Value : 1.0
  (Needs full documentation)

• W_KAPPA (Float)
  One-line description : Weight of isothermal compressibility
  Default Value : 1.0
  (Needs full documentation)

• W_NETFORCE (Float)
  One-line description : Weight of net forces (condensed to molecules, residues, or charge groups)
  Default Value : 0.0
  (Needs full documentation)

• W_NORMALIZE (Bool)
  One-line description : Normalize the condensed phase property contributions to the liquid / lipid property target
  Default Value : 0
  (Needs full documentation)

• W_RESP (Float)
  One-line description : Weight of RESP
  Default Value : 0.0
  (Needs full documentation)

• W_RHO (Float)
  One-line description : Weight of experimental density
  Default Value : 1.0
  (Needs full documentation)

• W_SCD (Float)
  One-line description : Weight of deuterium order parameter
  Default Value : 1.0
  (Needs full documentation)

• W_SURF_TEN (Float)
  One-line description : Weight of surface tension
  Default Value : 0.0
  (Needs full documentation)

• W_TORQUE (Float)
  One-line description : Weight of torques (condensed to molecules, residues, or charge groups)
  Default Value : 0.0
  (Needs full documentation)

• WAVENUMBER_TOL (Float)
  One-line description : Frequency normalization (in wavenumber) for vibrational frequencies
  Default Value : 10.0
  (Needs full documentation)

• WEIGHT (Float)
  One-line description : Weight of the target (determines its importance vs. other targets)
  Default Value : 1.0
  Scope : All target types (Optional)
  Full description : This option specifies the weight that the target will contribute to the objective function. A larger weight for a given target means that the optimizer will prioritize it over the others. When several targets are used, the weight should be chosen carefully such that all targets contribute a finite amount to the objective function. Note that the choice of weight determines the final outcome of the force field, although we hope not by too much.
  Recommendation : It is important to specify something here (giving everything equal weight is unlikely to work.) Run a single-point objective function evaluation with all weights set to one to get a handle on the natural size of each target's contribution, and then add weights accordingly.

• WRITELEVEL (Int)
  One-line description : Affects the amount of data being printed to the temp directory.
  Default Value : 0
  (Needs full documentation)