# Module MMTK.NormalModes

See also the normal mode example applications.

## Class Mode: Single normal mode

A subclass of MMTK.ParticleVector.

Mode objects are created by indexing a NormalModes object. They contain the atomic displacements corresponding to a single mode.

Mode objects are specializations of MMTK.ParticleVector objects and support all their operations. In addition, the frequency corresponding to the mode is stored in the attribute "frequency".

Note: the normal mode vectors are not mass weighted, and therefore not orthogonal to each other.

Methods:

- view(factor=`1.0`, subset=`None`)

  Start an animation of the mode. The displacements can be scaled by a factor to make them better visible, and a subset of the total system can be specified as well. This function requires an external viewer, see module MMTK.Visualization for details.

## Class NormalModes: Normal modes

Constructor: NormalModes(universe, temperature=300)

universe

  the system for which the normal modes are calculated; it must have a force field which provides the second derivatives of the potential energy

temperature

  the temperature for which the amplitudes of the atomic displacement vectors are calculated. A value of `None` can be specified to have no scaling at all. In that case the mass-weighted norm of each normal mode is one.

In order to obtain physically reasonable normal modes, the configuration of the universe must correspond to a local minimum of the potential energy.

A NormalModes object behaves like a sequence of modes. Individual modes (see class MMTK.NormalModes.Mode) can be extracted by indexing with an integer. Looping over the modes is possible as well.

Methods:

- reduceToRange(first, last)

  Discards all modes except for those whose numbers are between first (inclusive) and last (exclusive). This is done to reduce memory requirements, especially before saving the modes to a file.

- fluctuations()

  Returns a MMTK.ParticleScalar containing the thermal fluctuations for each atom in the universe.

## Class SparseMatrixNormalModes: Normal modes using a sparse matrix

A subclass of MMTK.NormalModes.NormalModes.

This class differs from the class NormalModes in that it obtains the Cartesian force constant matrix in a sparse-matrix format and uses a sparse-matrix eigenvalue solver from the ARPACK library. This is advantageous if the Cartesian force constant matrix is sparse (as it is for force fields without long-range terms), but for non-sparse matrices the memory requirements are higher than for NormalModes. Note that the calculation time depends not only on the size of the system, but also on its frequency spectrum, because an iterative algorithm is used.

Constructor: SparseMatrixNormalModes(universe, nmodes, temperature=300)

universe

  the system for which the normal modes are calculated; it must have a force field which provides the second derivatives of the potential energy

nmodes

  the number of modes that is calculated. The calculation time can grow significantly with an increasing number of modes.

temperature

  the temperature for which the amplitudes of the atomic displacement vectors are calculated. A value of `None` can be specified to have no scaling at all. In that case the mass-weighted norm of each normal mode is one.

In order to obtain physically reasonable normal modes, the configuration of the universe must correspond to a local minimum of the potential energy.

A SparseMatrixNormalModes object behaves like a sequence of modes. Individual modes (see class MMTK.NormalModes.Mode) can be extracted by indexing with an integer. Looping over the modes is possible as well.

## Class SubspaceNormalModes: Normal modes in a subspace

A subclass of MMTK.NormalModes.NormalModes.

Constructor: SubspaceNormalModes(universe, basis, temperature=300)

universe

  the system for which the normal modes are calculated; it must have a force field which provides the second derivatives of the potential energy

basis

  the basis for the subspace in which the normal modes are calculated (or, more precisely, a set of vectors spanning the subspace; it does not have to be orthogonal). This can either be a sequence of MMTK.ParticleVector objects or a tuple of two such sequences. In the second case, the subspace is defined by the space spanned by the first set of vectors projected on the complement of the space spanned by the second set of vectors. The second set thus defines directions that are excluded from the subspace.

temperature

  the temperature for which the amplitudes of the atomic displacement vectors are calculated. A value of `None` can be specified to have no scaling at all. In that case the mass-weighted norm of each normal mode is one.

In order to obtain physically reasonable normal modes, the configuration of the universe must correspond to a local minimum of the potential energy.

A SubspaceNormalModes object behaves like a sequence of modes. Individual modes (see class MMTK.NormalModes.Mode) can be extracted by indexing with an integer. Looping over the modes is possible as well.

## Class FiniteDifferenceSubspaceNormalModes: Normal modes in a subspace with numerical differentiation

A subclass of MMTK.NormalModes.SubspaceNormalModes.

This class differs from SubspaceNormalModes in the way it obtains the force constant matrix. Instead of obtaining the full Cartesian force constant matrix from the force field and projecting it on the subspace, it performs a numerical differentiation of the gradients along the basis vectors of the subspace. This is useful in two cases:

- for small subspaces this approach uses less memory, because the full Cartesian force constant matrix is not needed

- it can be used even if the force field does not provide second derivatives

Constructor: FiniteDifferenceSubspaceNormalModes(universe, basis, delta=0.0001, temperature=300)

universe

  the system for which the normal modes are calculated

basis

  the basis for the subspace in which the normal modes are calculated (or, more precisely, a set of vectors spanning the subspace; it does not have to be orthogonal). This can either be a sequence of ParticleVector objects or a tuple of two such sequences. In the second case, the subspace is defined by the space spanned by the first set of vectors projected on the complement of the space spanned by the second set of vectors. The second set thus defines directions that are excluded from the subspace.

delta

  the length of the displacement used for numerical differentiation

temperature

  the temperature for which the amplitudes of the atomic displacement vectors are calculated. A value of `None` can be specified to have no scaling at all. In that case the mass-weighted norm of each normal mode is one.

In order to obtain physically reasonable normal modes, the configuration of the universe must correspond to a local minimum of the potential energy.

A FiniteDifferenceSubspaceNormalModes object behaves like a sequence of modes. Individual modes (see class MMTK.NormalModes.Mode) can be extracted by indexing with an integer. Looping over the modes is possible as well.

## Class SparseMatrixSubspaceNormalModes: Normal modes in a subspace using a sparse matrix

A subclass of MMTK.NormalModes.SubspaceNormalModes.

This class differs from SubspaceNormalModes in that it obtains the Cartesian force constant matrix in a sparse-matrix format. This is advantageous if the Cartesian force constant matrix is sparse (as it is for force fields without long-range terms), but for non-sparse matrices the memory requirements are higher than for SubspaceNormalModes.

Constructor: SparseMatrixSubspaceNormalModes(universe, basis, temperature=300)

universe

  the system for which the normal modes are calculated; it must have a force field which provides the second derivatives of the potential energy

basis

  the basis for the subspace in which the normal modes are calculated (or, more precisely, a set of vectors spanning the subspace; it does not have to be orthogonal). This can either be a sequence of ParticleVector objects or a tuple of two such sequences. In the second case, the subspace is defined by the space spanned by the first set of vectors projected on the complement of the space spanned by the second set of vectors. The second set thus defines directions that are excluded from the subspace.

temperature

  the temperature for which the amplitudes of the atomic displacement vectors are calculated. A value of `None` can be specified to have no scaling at all. In that case the mass-weighted norm of each normal mode is one.

In order to obtain physically reasonable normal modes, the configuration of the universe must correspond to a local minimum of the potential energy.

A SparseMatrixSubspaceNormalModes object behaves like a sequence of modes. Individual modes (see class MMTK.NormalModes.Mode) can be extracted by indexing with an integer. Looping over the modes is possible as well.