.. _topologies:

-------------------------
topologies
-------------------------

The `"topologies"` object in the json is an array of `"topology"` 
objects. Each `"topology"` contains the key aspects of the 
molecule or molecules you wish to study. Inside a `"topology"` the 
following fields are specified

.. _topology:

topology
^^^^^^^^

.. list-table:: Molecular Data keywords
   :header-rows: 1

   * - Keyword
     - Brief
   * - :ref:`geometry`
     - An array that contains the xyz coordinates of the molecular system
   * - :ref:`symbols`
     - An array that contains the atomic symbols of each atom specified
   * - :ref:`fragment_formal_charges`
     - An array of charges for each fragment, for a single molecule, this is a one element array [0]
   * - :ref:`fragment_multiplicities`
     - Similar to :ref:`fragment_formal_charges`, an array of multiplicities, or a one element array for non-fragmented calculation
   * - :ref:`fragments`
     - An array of arrays, each containing the indices of atoms belonging to a fragment. These indices are ZERO-INDEXED
   * - :ref:`connectivity`
     - An array of three element arrays that specify the connectivity of the molecule.
   * - :ref:`xyz`
     - A string that points to a standard format xyz file to use in place of the :ref:`geometry` and :ref:`symbols` structures. It is compatible with the fragmentation keywords.


.. _geometry:

geometry
"""""""""
An array that contains the xyz coordinates of the :ref:`topology`. The coordinates are arranged per atom, for example:

.. code-block:: JSON 
  
            "geometry": [
              -4.3997, 1.0764, 7.7009,   // atom 0 -> (x0,y0,z0)
              -3.9597, 0.2664, 7.3109,  // atom 1 -> (x1,y1,z1)
              -4.4297, 0.9964, 8.7009  // atom 2 -> (x2,y2,z2)
            ],



.. _symbols:

symbols
"""""""""
An array that contains the atomic symbols of each atom specified. For example:

.. code-block:: JSON 
  
            "symbols": ["O", "H", "H"]


.. _fragment_formal_charges:

fragment_formal_charges
"""""""""""""""""""""""""""
An array of charges for each fragment, for a single molecule, this is a one element array. This field is not required by default. 
If not specified, the calculation will default to a charge of 0. 

.. code-block:: JSON 
  
      {
        "topologies": [
          {
            "geometry": [
              -4.3997, 1.0764, 7.7009,
              -3.9597, 0.2664, 7.3109,
              -4.4297, 0.9964, 8.7009
            ],
            "symbols": ["O", "H", "H"],
            "fragment_formal_charges": [0]
          }
        ]
      }

.. _fragment_multiplicities:

fragment_multiplicities
"""""""""""""""""""""""""""
Similar to :ref:`fragment_formal_charges`, an array of multiplicities, or a one element array for non-fragmented calculation similar to the 
fragment_formal_charges. This field is not required by default. If not specified, the calculation will assume a singlet. 


.. code-block:: JSON 
  
      {
        "topologies": [
          {
            "geometry": [
              -4.3997, 1.0764, 7.7009,
              -3.9597, 0.2664, 7.3109,
              -4.4297, 0.9964, 8.7009
            ],
            "symbols": ["O", "H", "H"],
            "fragment_formal_charges": [0],
            "fragment_multiplicities": [1]
          }
        ]
      }

.. _fragments:

fragments
"""""""""
An array of arrays, each containing the indices of atoms belonging to a fragment. These indices are ZERO-INDEXED. For example, 
if we had five water molecules, with one water molecule per fragment:

.. code-block:: JSON 

            "fragments": [
              [ 0, 1, 2 ], [ 3,4,5 ],[ 6,7,8 ], [9,10,11 ], [12,13,14]
            ],

.. _connectivity:

connectivity
""""""""""""
An array of three element arrays that specify the connectivity of the molecule. The array represents:

[atom_index_1, atom_index_2, bond_order]

The bond orders can be:

 - Single bond (1)
 - Double bond (2)
 - Triple bond (3)

The connectivity is not needed unless the 
calculation contains fragments that are connected via a covalent bond. For example:

.. code-block:: JSON 

                {
                "topologies": [
                  {
                          "geometry": [
                      1.1851, -0.0039, 0.9875,
                      0.7516, -0.0225, -0.0209,
                      1.1669, 0.833, -0.5693,
                      1.1155, -0.9329, -0.5145,
                      -0.7516, 0.0225, 0.0209,
                      -1.1669, -0.8334, 0.5687,
                      -1.1157, 0.9326, 0.5151,
                      -1.185, 0.0044, -0.9875,
                      1.1851, 1.9961, 1.9875,
                      0.7516, 1.9775, 0.9791,
                      1.1669, 2.833, 0.4307,
                      1.1155, 1.0671, 0.4855,
                      -0.7516, 2.0225, 1.0209,
                      -1.1669, 1.1666, 1.5687,
                      -1.1157, 2.9326, 1.5151,
                      -1.185, 2.0044, 0.0125
                    ],
                    "symbols": [
                      "H",
                      "C",
                      "H",
                      "H",
                      "C",
                      "H",
                      "H",
                      "H",
                      "H",
                      "C",
                      "H",
                      "H",
                      "C",
                      "H",
                      "H",
                      "H"
                    ]
                    "fragments": [
                      [0, 1, 2, 3],
                      [4, 5, 6, 7],
                      [8, 9, 10, 11],
                      [12, 13, 14, 15]
                    ],
                    "connectivity": [
                      [1, 4, 1],
                      [9, 12, 1]
                    ],
                    "fragment_formal_charges": [0, 0, 0, 0]
                  }
                ]
                }

This system has two ethanes which are fragmented across the C-C bond. The "connectivity" signals 
that there's a single bond between atom indices 1 and 4, hence [1,4,1].

The fragmentation algorithm will iterate across the fragment list and check with the connectivity, if there's a bond being
broken between two fragments, it will cap each empty valence with a hydrogen. At the end of the fragmentation calculation 
this Hydrogen caps are automatically subtracted out. 

.. _xyz:

xyz
"""
A string that points to a standard format xyz file to use in place of the :ref:`geometry` and :ref:`symbols` structures. It is compatible with the fragmentation keywords.