normal_modes
============

.. py:module:: normal_modes

.. autoapi-nested-parse::

   Generating normal modes, reading and writing mode data from/to files.









Module Contents
---------------

.. py:function:: generate_nmd_from_pdb(pdb_path: pathlib.Path | str, nmd_path: pathlib.Path | str, mode_count=10)

   Parses a PDB file with a structure and a trajectory and calculates the normal
   modes of the trajectory. Writes them to an NMD file.

   This can be an expensive process, which is why it's encapsulated in a
   function that goes from file to file and doesn't produce an in-memory
   structure. To work with the resulting normal modes, use
   :func:`NormalModes.from_nmd`, which is a cheap operation.


.. py:exception:: ValidationError

   Bases: :py:obj:`Exception`


   Represents a mismatch in normal mode information

   Example: the number of coordinates given versus the number of vectors in
   the mode.


.. py:class:: NormalModes

   An object that represents a collection of normal modes

   Primarily parsed from an NMD file generated by the
   :func:`generate_nmd_from_pdb` function, but can be constructed manually.


   .. py:method:: from_nmd(nmd_path: pathlib.Path | str) -> NormalModes
      :staticmethod:


      Create a :class:`NormalModes` instance by parsing the given input file.
      A fast operation.



   .. py:attribute:: coordinates
      :value: None



   .. py:attribute:: atomnames
      :value: None



   .. py:attribute:: resnames
      :value: None



   .. py:attribute:: resids
      :value: None



   .. py:attribute:: modes
      :value: []



   .. py:method:: parse_nmd_file(nmd_path)

      Parse the given NMD file and extract atomnames, resnames, resids,
      coordinates, and modes into a :class:`NormalModes` object. Expected
      structure::

          atomnames CA CA CA ...
          resnames SER ARG LEU ...
          resids 0 1 2 3 4 5 6 7 8 11 12 ...
          coordinates 54.260 50.940 73.060 ...
          mode 1 29.61 -0.008 -0.005 0.012 ...
          mode 2 18.28 -0.009 0.004 -0.008 ...
          mode 3 17.50 -0.027 -0.025 0.023 ...
          mode <N> <magnitude> <x1> <y1> <z1> <x2> <y2> <z2> ...

      There may be additional lines that we currently ignore.



   .. py:method:: generate_trajectory(frame_count=100, vector_scale=2.5, mode_indices=0)

      Generate a trajectory that visualises these modes.

      The frame count is expected to be an even number. The first frame is
      the initial coordinates, then the animation applies the vectors
      forward, then back. The last frame should also be the initial
      coordinates, provided there are no numerical errors.

      By default, the first mode is used, but you can provide the index in
      `self.modes` to use by changing `mode_indices`. If that input is given
      as a range, the whole range of modes will be used to generate the
      trajectory.

      The `vector_scale` parameter simply controls how much to scale the
      vectors to produce a clearly visible trajectory. Setting it too high
      might result in very large changes to the visualization.



   .. py:method:: _validate_modes()

      Ensure that the modes' shapes match the coordinates.



   .. py:method:: _group_in_threes(flat_coordinates)

      A utility function that groups sequences of values into triplets.