DOCSEARCHbyAlgolia
Submit Docs

ForceBalance

repository·master·Indexed 41 days ago

https://github.com/leeping/forcebalance

A tool for the systematic and reproducible parametrization of force fields from quantum chemistry data. It utilizes a 'trinity' of components—the Force Field (FF), Objective Function, and Optimizer—to perform optimizations. ForceBalance supports various target types, including energy and force matching, electrostatic potential fitting (RESP), and condensed-phase properties, with compatibility for GROMACS, OpenMM, TINKER, AMBER, and psi4.

Tokens
17.7K
Snippets
49
Records
90
Agent score
51%

What's inside ForceBalance

  1. Set up the ForceBalance directory structure

    master

    ForceBalance requires a specific directory layout. The names forcefield and targets are fixed and cannot be changed.

    • forcefield/: Contains the force field files being optimized (e.g., .itp files).
    • targets/: Contains subdirectories for each target. Each subdirectory must match a target name from your input file.
    • temp/: A workspace for runtime files (created automatically).
    • result/: Where optimized force field files are placed upon successful completion (created automatically).

    Target Subdirectory Requirements: Each target directory (e.g., targets/cluster-02/) typically requires:

    • settings/: Contains simulation setup files (e.g., .mdp and .top for GROMACS).
    • A coordinate trajectory file (e.g., all.gro).
    • A quantum data file (e.g., qdata.txt).
    <root>
  +- forcefield
  |   |- water.itp
  +- targets
  |   +- cluster-02
  |   |   +- settings
  |   |   |   |- shot.mdp
  |   |   |   |- topol.top
  |   |   |- all.gro
  |   |   |- qdata.txt
  |   +- cluster-03
  |   |   +- settings
  |   |   |   |- shot.mdp
  |   |   |   |- topol.top
  |   |   |- all.gro
  |   |   |- qdata.txt
  |- input.in
  +- temp
  +- result

  2. Create a ForceBalance input file

    master

    ForceBalance input files use specific section headers to define global settings and individual targets. The two primary section types are $options and $target.

    • $options: Defines global job settings.
    • $target: Defines settings for a specific reference data set (target).

    Use MakeInputFile.py to generate a template input file containing all available options, their default values, and descriptions.

    $options
jobtype newton
forcefield water.itp
$end

$target
name cluster-02
type abinitio_gmx
$end

$target
name cluster-03
type abinitio_gmx
$end

  3. Generate target data from a geomeTRIC scan

    master

    To generate the 'target' data required for ForceBalance from a geomeTRIC scan-final.xyz file, follow these steps:

    1. Prepare the XYZ file: Copy your scan-final.xyz file into the working directory and rename it to all.xyz.
    2. Extract QM energies: Run make-qdata.py. This script parses the QM energies stored in the comments of all.xyz and saves them to qdata.txt.
    3. Provide molecular structures: Add .mol2 files for every individual molecule in the system.
    4. Provide system topology: Add a .pdb file containing the entire system. This file must contain the same atoms as all.xyz, but must include atom names and residue names.
    5. Verify parameters: Run make-labels.py to identify which force field parameters are being loaded for the system.
    6. Configure the force field: Update your force field file (e.g., forcefield/smirnoff99Frosst.xml) by adding parameterize attributes that match the output from make-labels.py.

    Note: Only add parameters that are relevant to the optimization (i.e., those corresponding to the degrees of freedom being scanned).

    # 1. Prepare file
cp scan-final.xyz all.xyz

# 2. Extract QM data
python make-qdata.py

# 5. Check parameters
python make-labels.py

  4. Run ForceBalance optimization

    master

    To start a force field optimization, ensure your directory structure and input file are correctly configured, then execute the main script from the command line:

    ForceBalance.py input.in

    If the calculation fails, ForceBalance will attempt to provide error messages to help you correct your setup.

  7. Install ForceBalance via Conda

    master

    You can install ForceBalance using the conda-forge channel. This method installs ForceBalance and its required dependencies.

    Note: This installation does not include optional dependencies such as OpenMM, Gromacs, AMBER, Tinker, CCTools/Work Queue, or the Open Force Field toolkit. You must install these separately if needed.

    Prerequisites:

    • Use an Anaconda or Miniconda Python distribution.
    • Supported Python versions: 2.7, 3.5, 3.6, or 3.7.

    If you previously installed ForceBalance from the omnia repository, you may need to clear your index cache before installing using conda clean -i.

    conda install --strict-channel-priority -c conda-forge forcebalance

  8. Build and install ForceBalance from source

    master

    If you prefer to build from the source code, use the setup.py script.

    Standard Build and Install

    To build the package:

    python setup.py build

    To install the package:

    python setup.py install

    Local Installation (No Root Permissions)

    If you do not have root/administrator permissions, use one of the following methods:

    1. User install:
      python setup.py install --user
    2. Prefix install:
      python setup.py install --prefix=$HOME/.local
# OR
python setup.py install --prefix=/your/favorite/directory
export PYTHONPATH=/your/favorite/directory

    Create a distributable archive

    To turn the package into a .tar.bz2 source distribution:

    python setup.py sdist
    python setup.py build
python setup.py install

  9. Parse PDB files using PDB record classes

    master

    The PDB.py module provides a set of classes designed to parse Protein Data Bank (PDB) files according to the PDB Format Description Version 2.2 (1996). Each class corresponds to a specific PDB record type. Note that the parser is strict and not very forgiving of format deviations.

    Key record classes include:

    • ATOM: Represents atomic coordinates for standard residues.
    • HETATM: Represents atomic coordinates for non-standard groups (e.g., water, ligands).
    • MASTER: A control record for bookkeeping (e.g., number of other record types).
    • CONECT: Specifies connectivity between atoms.
    • TER: Indicates the end of a chain.
    • MODEL / END / ENDMDL: Used for grouping individual structures in multi-model entries (e.g., NMR).
    • SIGUIJ / ANISOU: Present anisotropic temperature factors.
    • TVECT / MTRIX2 / MTRIX3: Present coordinate transformations and symmetry information.

  10. How ForceBalance components work together

    master

    The ForceBalance execution model relies on a 'trinity' of components that are instantiated and linked during the Run_ForceBalance process:

    1. Force Field (FF): Defined in forcefield.py, this component handles the physical model and force calculations. It is initialized using the options parsed from the input file.
    2. Objective Function (Objective): A combination of target classes and a penalty function class. It uses the forcefield and the target options (tgt_opts) to evaluate how well the model performs.
    3. Optimizer (Optimizer): The engine that drives the optimization process. It takes the options, the objective, and the forcefield as inputs and executes the Run() method to perform the optimization.

    Data flows from the input file through a parser (parse_inputs), which generates the configuration options used to construct these three objects.

  11. Use the Quantity base class for fitting

    master

    The Quantity class is the base class for thermodynamical quantities used in force field fitting. It represents experimental data that can be calculated as an ensemble average from a simulation.

    When implementing a custom quantity, you must subclass Quantity and implement the extract method.

    Attributes:

    • name (string): Identifier for the quantity (specified in Target options).
    • engname (string): The engine used to extract the quantity (e.g., gromacs).
    • temperature (float): The temperature at which to calculate the quantity (in K).
    • pressure (float): The pressure at which to calculate the quantity (in bar).
    from forcebalance.quantity import Quantity

# Example initialization
my_quantity = Quantity(engname='gromacs', temperature=298.15, pressure=1.0, name='my_custom_quantity')

  12. Understand the OptGeoTarget objective function

    master

    The OptGeoTarget class is a Target subclass designed to fit Molecular Mechanics (MM) optimized geometries to Quantum Mechanics (QM) optimized geometries.

    How it works

    1. Internal Coordinates: It builds internal coordinates (bonds, angles, dihedrals, impropers) from the provided topology and geometry files.
    2. Optimization: It uses an engine (like OpenMM or SMIRNOFF) to perform an MM optimization.
    3. Objective Calculation: The objective value $X$ is the sum of squared scaled differences between the MM-optimized internal coordinates and the QM reference values: $$X = ext{sum}( ext{scaled_diff}^2)$$ where $ ext{scaled_diff} = ( ext{ref} - ext{target}) / ext{denom}$.
    4. Output: When writelevel > 0, it generates an rmsd_decomposition.txt file detailing the differences for every internal coordinate and saves the MM-optimized geometry as {sysname}_mmopt.xyz.