==========
Restraints
==========

Restraints are geometry-dependent potentials that are employed to bias simulated systems towards selected structural features.
These are used whenever it is desirable to encourage rather than enforce a particular geometry; rigid constraints, by contrast, eliminate the corresponding degrees of freedom entirely.
By introducing supplementary energy terms that penalise deviations from specified reference values, such as inter-atomic distances or bond angles, experimental observations or prior theoretical insights may be honoured, enhanced convergence can be promoted, and rare events may be explored within practicable timescales; all whilst permitting natural fluctuations.
Typically, restraints are applied only to a limited selection of atoms, leaving the remainder of the model to evolve according to the underlying force-field.
In this way, a balance is struck between preserving the natural dynamical character of the system and focusing computational effort on the configurational regions of greatest significance to the study at hand.

Restraints are defined and applied at the :mod:`~chemsh.tasks` layer.
Upon execution, each task—such as :class:`~chemsh.tasks.sp.SP` or :class:`~chemsh.tasks.opt.Opt`—automatically iterates over the supplied restraints, evaluating them in sequence.
All concrete restraint classes inherit from the abstract base :class:`chemsh.base.restraint.Restraint`.
Accordingly, an instance of the appropriate concrete class is required for every restraint to be used, and a list of these instances should be supplied to the task via the restraints keyword argument.

The `chemsh` package offers harmonic restraint potentials for the six following geometric properties:

 * :class:`~chemsh.base.restraint.Bond`: bond distance restraint between two atoms.
 * :class:`~chemsh.base.restraint.Angle`: bond angle restraint involving three atoms.
 * :class:`~chemsh.base.restraint.Torsion`: torsion angle restraint defined by four atoms.
 * :class:`~chemsh.base.restraint.BondDifference2`: difference of two bond distances.
 * :class:`~chemsh.base.restraint.BondDifference3`: difference of three bond distances.
 * :class:`~chemsh.base.restraint.BondDifference4`: difference of four bond distances.

A minimum working example is provided below demonstrating the application of three harmonic restraints to a single-point task:

.. code-block:: python

    import chemsh
    from chemsh import Fragment, NWChem, SP
    from chemsh.base.restraint import Bond, Angle, Torsion

    fragment = Fragment("some_molecule_file.xyz")

    theory = NWChem(frag=fragment, method="hf", basis="3-21g")

    restraints = [
        Bond((0, 8), 2.4, 2.0),
        Angle((8, 0, 2), 115.0, 2.0),
        Torsion((0, 2, 3, 1), -50.0, 2.0)]

    task = SP(frag=fragment, theory=theory,
              restraints=restraints, gradients=True)

    task.run()


.. currentmodule:: chemsh.base.restraint


Abstract base
=============

.. autoclass:: Restraint
   :members:
   :special-members: __init__
   :undoc-members:
   :show-inheritance:
   :inherited-members:
   :exclude-members: __weakref__


Harmonic restraints
===================

Bond
----

.. autoclass:: Bond
   :members:
   :special-members: __init__
   :show-inheritance:

Angle
-----

.. autoclass:: Angle
   :members:
   :special-members: __init__
   :show-inheritance:

Torsion
-------

.. autoclass:: Torsion
   :members:
   :special-members: __init__
   :show-inheritance:

Distance-difference restraints
------------------------------

.. autoclass:: BondDifference2
   :members:
   :special-members: __init__
   :show-inheritance:

.. autoclass:: BondDifference3
   :members:
   :special-members: __init__
   :show-inheritance:

.. autoclass:: BondDifference4
   :members:
   :special-members: __init__
   :show-inheritance:

Type aliases
------------

.. py:type:: Indices2
   :canonical: tuple[int, int]

.. py:type:: Indices3
   :canonical: tuple[int, int, int]

.. py:type:: Indices4
   :canonical: tuple[int, int, int, int]

.. py:type:: Indices6
   :canonical: tuple[int, int, int, int, int, int]

.. py:type:: Indices8
   :canonical: tuple[int, int, int, int, int, int, int, int]