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

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

There are no required fields for the Molecule specification.

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

The following keys are optional for the Molecule specification.
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | Key Name                                                                                        | Description                                                                                                              | Field Type                                                                       |
   +=================================================================================================+==========================================================================================================================+==================================================================================+
   | atom_labels                                                                                     | Additional per-atom labels as an array of strings. Typical use is in model conversions, such as Elemental <-> Molpro and | array[string]                                                                    |
   |                                                                                                 | not typically something which should be user assigned. See the ``comments`` field for general human-consumable text to   |                                                                                  |
   |                                                                                                 | affix to the molecule.                                                                                                   |                                                                                  |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | 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`` and ``real``. Values are inferred from the ``symbols`` list if not explicitly   |                                                                                  |
   |                                                                                                 | set. Ghostedness should be indicated through ``real`` field, not zeros here.                                             |                                                                                  |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | comment                                                                                         | Additional comments for this molecule. Intended for pure human/user consumption and clarity.                             | string                                                                           |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | connectivity                                                                                    | A list of bonds within the molecule. Each entry is a tuple of ``(atom_index_A, atom_index_B, bond_order)`` where the     | array[array]                                                                     |
   |                                                                                                 | ``atom_index`` matches the 0-indexed indices of all other per-atom settings like ``symbols`` and ``real``. Bonds may be  |                                                                                  |
   |                                                                                                 | freely reordered and inverted.                                                                                           |                                                                                  |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | extras                                                                                          | Additional information to bundle with the molecule. Use for schema development and scratch space.                        | object                                                                           |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | geometry                                                                                        | An ordered (natom*ndim,) array for XYZ atomic coordinates. Default unit is Angstrom.                                     | array[number]                                                                    |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | geometry_units                                                                                  | Units for atomic geometry. Defaults to Angstroms.                                                                        | string                                                                           |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | identifiers                                                                                     | An optional dictionary of additional identifiers by which this molecule can be referenced, such as INCHI, canonical      | object                                                                           |
   |                                                                                                 | SMILES, etc. See the :class:``Identifiers`` model for more details.                                                      |                                                                                  |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | mass_numbers                                                                                    | An optional ordered 1-D array-like object of atomic *mass* numbers of shape (nat). Index matches the 0-indexed indices   | array[number]                                                                    |
   |                                                                                                 | of all other per-atom settings like ``symbols`` and ``real``. Values are inferred from the most common isotopes of the   |                                                                                  |
   |                                                                                                 | ``symbols`` list if not explicitly set. If single isotope not (yet) known for an atom, -1 is placeholder.                |                                                                                  |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | masses                                                                                          | The ordered array of particle masses. Index order matches the 0-indexed indices of all other per-atom fields like        | array[number]                                                                    |
   |                                                                                                 | ``symbols`` and ``real``. If this is not provided, the mass of each atom is inferred from its most common isotope. If    |                                                                                  |
   |                                                                                                 | this is provided, it must be the same length as ``symbols`` but can accept ``None`` entries for standard masses to infer |                                                                                  |
   |                                                                                                 | from the same index in the ``symbols`` field.                                                                            |                                                                                  |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | masses_units                                                                                    | Units for atomic masses. Defaults to unified atomic mass unit.                                                           | string                                                                           |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | molecular_charge                                                                                | The net electrostatic charge of the molecule. Default unit is elementary charge.                                         | number                                                                           |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | molecular_charge_units                                                                          | Units for molecular charge. Defaults to elementary charge.                                                               | string                                                                           |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | name                                                                                            | Common or human-readable name to assign to this molecule. This field can be arbitrary; see ``identifiers`` for well-     | string                                                                           |
   |                                                                                                 | defined labels.                                                                                                          |                                                                                  |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | ndim                                                                                            | Number of spatial dimensions.                                                                                            | integer                                                                          |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | 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_molecule.                          | string                                                                           |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | schema_version                                                                                  | The version number of ``schema_name`` to which this model conforms.                                                      | integer                                                                          |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | substructs                                                                                      | A list of (name, num) of connected atoms constituting the building block (e.g. monomer) of the structure (e.g. a         | array[array]                                                                     |
   |                                                                                                 | polymer). Order follows atomic indices from 0 till Natoms-1. E.g. [('ALA', 4), ...] means atom1 belongs to aminoacid     |                                                                                  |
   |                                                                                                 | alanine with residue number 4. Substruct name is max 4 characters.                                                       |                                                                                  |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | symbols                                                                                         | An ordered (natom,) array-like object of particle symbols. The index of this attribute sets the order for all other per- | array[string]                                                                    |
   |                                                                                                 | particle setting like ``geometry`` and the first dimension of ``geometry``.                                              |                                                                                  |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | velocities                                                                                      | An ordered (natoms*ndim,) array for XYZ atomic velocities. Default unit is Angstroms/femtoseconds.                       | array[number]                                                                    |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
   | velocities_units                                                                                | Units for atomic velocities. Defaults to Angstroms/femtoseconds.                                                         | string                                                                           |
   +-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+