Forcefield schema
=================
A full description of the overall Forcefield model.

Required Keys
-------------

The following properties are required for the Forcefield specification.
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | Key Name                                                                                        | Description                                                                                                              | Field Type                                                                       |
   +=================================================================================================+==========================================================================================================================+==================================================================================+
   | symbols                                                                                         | An ordered (natom,) list of particle (e.g. atomic elemental) symbols.                                                    | array[string]                                                                    |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+

Optional Keys
-------------

The following keys are optional for the Forcefield specification.
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | Key Name                                                                                        | Description                                                                                                              | Field Type                                                                       |
   +=================================================================================================+==========================================================================================================================+==================================================================================+
   | angles                                                                                          | No description provided.                                                                                                 | array[#/definitions/Angles]                                                      |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | atomic_numbers                                                                                  | An optional ordered 1-D array-like object of atomic numbers of shape (nat,). Index matches the 0-indexed indices of all  | array[number]                                                                    |
   |                                                                                                 | other per-atom settings like ``symbols``. Values are inferred from the ``symbols`` list if not explicitly set.           |                                                                                  |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | bonds                                                                                           | No description provided.                                                                                                 | array[#/definitions/Bonds]                                                       |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | charge_groups                                                                                   | Charge groups per atom. Length of the array must be natoms.                                                              | array[number]                                                                    |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | charges                                                                                         | Atomic charges. Default unit is in elementary charge units.                                                              | array[number]                                                                    |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | charges_units                                                                                   | Atomic charge unit.                                                                                                      | string                                                                           |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | combination_rule                                                                                | Combination rule for the force field.                                                                                    | string                                                                           |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | comment                                                                                         | Additional comments for this model. Intended for pure human/user consumption and clarity.                                | string                                                                           |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | defs                                                                                            | Particle definition. For atomic forcefields, this could be the atom type (e.g. HH31) or SMIRKS (OFF) representation. The | array[string]                                                                    |
   |                                                                                                 | type names are associated with the atomic elements defined in other objects e.g. see the :class:``Molecule`` model.      |                                                                                  |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | dihedrals                                                                                       | No description provided.                                                                                                 | array[#/definitions/Dihedrals]                                                   |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | exclusions                                                                                      | Which pairs of bonded atoms to exclude from non-bonded calculations. The rules to apply in choosing bonded exclusions    | string                                                                           |
   |                                                                                                 | are specifed in the configuration file using the exclude parameter. The choices for exclusions are None, 1-2, 1-3, 1-4,  |                                                                                  |
   |                                                                                                 | etc. With None, no atom pairs are excluded. With 1-2, only atoms that are connected via a linear bond are excluded. With |                                                                                  |
   |                                                                                                 | 1-3, any pair of atoms connected via a bond or bonded to a common third atom are excluded. With 1-4, any atoms that are  |                                                                                  |
   |                                                                                                 | connected by a linear bond, or a sequence of two bonds, or a sequence of three bonds, are excluded. With scaled1-4,      |                                                                                  |
   |                                                                                                 | exclusions are applied in the same manner as the 1-3 setting, but those pairs that are connected by a sequence of bonds  |                                                                                  |
   |                                                                                                 | are calculated using the modified 1-4 methods described rather than the standard force calculations.                     |                                                                                  |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | extras                                                                                          | Additional information to bundle with the object. Use for schema development and scratch space.                          | object                                                                           |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | identifier                                                                                      | Forcefield unique identifier e.g. charmm27, amber99, etc.                                                                | string                                                                           |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | inclusions                                                                                      | Which pairs of 1-4 excluded bonded atoms to include in non-bonded calculations.                                          | string                                                                           |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | masses                                                                                          | List of atomic masses. If not provided, the mass of each atom is inferred from its most common isotope. If this is       | array[number]                                                                    |
   |                                                                                                 | provided, it must be the same length as ``symbols``.                                                                     |                                                                                  |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | masses_units                                                                                    | Units for atomic masses. Defaults to unified atomic mass unit.                                                           | string                                                                           |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | name                                                                                            | Common or human-readable name to assign to this model. This field can be arbitrary.                                      | string                                                                           |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | nonbonded                                                                                       | No description provided.                                                                                                 | array[#/definitions/NonBonded]                                                   |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | provenance                                                                                      | The provenance information about how this object (and its attributes) were generated, provided, and manipulated.         | object                                                                           |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | schema_name                                                                                     | The MMSchema specification to which this model conforms. Explicitly fixed as mmschema_forcefield.                        | string                                                                           |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | schema_version                                                                                  | The version number of ``schema_name`` to which this model conforms.                                                      | integer                                                                          |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | substructs                                                                                      | A list of substructure names the particles belong to. E.g. [('ALA', 4), ('ACE', 0)] means atom1 belong to residue ALA    | array[array]                                                                     |
   |                                                                                                 | (alanine) with residue number 4, while atom2 belongs to residue ACE (acetyl) with residue number 0.                      |                                                                                  |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+