# Springcraft - Investigate molecular dynamics by elastic network models¶

*Springcraft* is a *Biotite* extension package, that allows the analysis
of AtomArray objects via *Elastic Network Models* (ENMs).
An ENM can be thought of as a system that connects residues via springs:
Interaction of nearby residues is governed by a harmonic potential, with the
native (input) conformation representing the energy minimum.
Normal mode analysis allows the researcher to investigate global
functional movements of a protein in a fast coarse-grained manner.
For a deeper dive into the theory of ENMs please refer to literature,
such as a method review from 2010.

## Installation¶

*Springcraft* can be installed via

```
$ pip install springcraft
```

or

```
$ conda install -c conda-forge springcraft
```

You can also install *Springcraft* from source on
GitHub.
The package uses Poetry for building
distributions.
Via **PEP 517** it is possible to install the package from local source code
via *pip*:

```
$ git clone https://github.com/biotite-dev/springcraft.git
$ pip install ./springcraft
```

## Usage¶

To compute an ENM a `ForceField`

is required, that defines the spring
force constant for each pair of atoms via `force_constant()`

.
A variety of `ForceField`

subclasses is available, each bringing
its own concept for parameterization.

```
import biotite.structure.io as strucio
import springcraft
# All pairs of atoms within a cutoff distance obtain the same force constant
ff = springcraft.InvariantForceField(cutoff_distance=13.0)
# The force constant is inversely proportional to the squared distance
ff = springcraft.ParameterFreeForceField()
# The force constant is read from tabulated values
# based on residue types and distance
# For the residue type the underlying CA-trace is required
atoms = strucio.load_structure("path/to/structure.pdb")
atoms = atoms[(atoms.atom_name == "CA") & (atoms.element == "C")]
ff = springcraft.TabulatedForceField.sd_enm(atoms)
```

The functions `compute_kirchhoff()`

and `compute_hessian()`

use
atom coordinates at the presumed minimum energy conformation, which is usually
simply the experimentally determined conformation, and the `ForceField`

to compute the *Kirchhoff* and *Hessian* matrix of the molecular system,
respectively.
As byproduct it also returns the pairs of atoms that were found within
cutoff distance given by the `ForceField`

.

```
ff = springcraft.InvariantForceField(cutoff_distance=13.0)
hessian, pairs = springcraft.compute_hessian(atoms.coord, ff)
```

One type of ENMs are *Gaussian Network models* (GNM).
They do not include directional information, but can be used to
investigate whether atoms move collectively and which atoms are involved
in global movements.
A `GNM`

is created using an `AtomArray`

representing the
structure model and a `ForceField`

.
Internally, both are given to `compute_kirchhoff()`

to obtain the
*Kirchhoff* matrix, which can be accessed with the kirchhoff attribute.
Actually, `GNM`

is only a thin wrapper around
`compute_kirchhoff()`

, that conveniently provides common operations
performed on the *Kirchhoff* matrix.
This includes the calculation of eigenvectors and eigenvalues among other
things.
A useful quantity is the correlation between the displacements of two atoms.
This value is contained in the covariance matrix (the covariance attribute),
which is the pseudo-inverse of the *Kirchhoff* matrix.

Note

Note that *Springcraft* uses arbitrary units, i.e. factors like the
*Boltzmann* constant or the temperature are generally not applied,
if not stated otherwise.

The kirchhoff and covariance matrix can also be modified to alter the network model. Changing one attribute also updates the other attribute.

```
gnm = springcraft.GNM(atoms, ff)
eigen_values, eigen_vectors = gnm.eigen()
```

Analogous to `GNM`

, the class for *Anisotropic Network models*
`ANM`

is a wrapper around the *Hessian* matrix, which in contrast to the
*Kirchhoff* matrix also includes the directionality of oscillation modes.
Hence, its shape is \(3n \times 3n\) since it comprises the three
spatial dimensions for each atom \((x_1, y_1, z_1, x_2, ...)\).
Similar to `GNM`

, the *Hessian* as well as its pseudo-inverse, the
covariance matrix, are accessible via the hessian and covariance
attributes.
The added spatial information allows an `ANM`

the depiction of
atom oscillations in normal modes or the application of
*Linear Response Theory* to investigate conformational changes upon ligand
binding.

```
import numpy as np
anm = springcraft.ANM(atoms, ff)
force_vector = np.zeros((atoms.array_length(), 3))
force_vector[42, 0] = 10
displacements = anm.linear_response(force_vector)
```