# 4.7.1. Polymer analysis — `MDAnalysis.analysis.polymer`

Author:

  Richard J. Gowers

Year:

  2015, 2018

Copyright:

  Lesser GNU Public License v2.1+

This module contains various commonly used tools in analysing polymers.

class MDAnalysis.analysis.polymer.PersistenceLength(atomgroups, **kwargs)

  Calculate the persistence length for polymer chains

  The persistence length is the length at which two points on the polymer chain become decorrelated. This is determined by first measuring the autocorrelation (\(C(n)\)) of two bond vectors (\(\mathbf{a}_i, \mathbf{a}_{i + n}\)) separated by \(n\) bonds

  \[C(n) = \langle \cos\theta_{i, i+n} \rangle = \langle \mathbf{a_i} \cdot \mathbf{a_{i+n}} \rangle\]

  where \(a_i\) and \(a_{i+n}\) are unit vectors along the bonds.

  An exponential decay is then fitted to this, which yields the persistence length

  \[C(n) \approx \exp\left( - \frac{n \bar{l_B}}{l_P} \right)\]

  where \(\bar{l_B}\) is the average bond length, and \(l_P\) is the persistence length which is fitted

  Parameters:

    - atomgroups (iterable) – List of AtomGroups. Each should represent a single polymer chain, ordered in the correct order.

    - verbose (bool, optional) – Show detailed progress of the calculation if set to `True`.

  results.bond_autocorrelation

    the measured bond autocorrelation

    Type:

      numpy.ndarray

  results.lb

    the average bond length

    Added in version 2.0.0.

    Type:

      float

  lb

    Alias to the `results.lb`.

    Deprecated since version 2.0.0: Will be removed in MDAnalysis 3.0.0. Please use `results.lb` instead.

    Type:

      float

  results.x

    length of the decorrelation predicted by lp

    Added in version 2.0.0.

    Type:

      numpy.ndarray

  results.lp

    calculated persistence length

    Added in version 2.0.0.

    Type:

      float

  lp

    Alias to the `results.lp`.

    Deprecated since version 2.0.0: Will be removed in MDAnalysis 3.0.0. Please use `results.lp` instead.

    Type:

      float

  results.fit

    the modelled backbone decorrelation predicted by lp

    Added in version 2.0.0.

    Type:

      numpy.ndarray

  fit

    Alias to the `results.fit`.

    Deprecated since version 2.0.0: Will be removed in MDAnalysis 3.0.0. Please use `results.fit` instead.

    Type:

      float

  See also

  `sort_backbone()`

    for producing the sorted AtomGroup required for input.

  Example

      from MDAnalysis.tests.datafiles import TRZ_psf, TRZ
      import MDAnalysis as mda
      from MDAnalysis.analysis import polymer
      u = mda.Universe(TRZ_psf, TRZ)

      # this system is a pure polymer melt of polyamide,
      # so we can select the chains by using the .fragments attribute
      chains = u.atoms.fragments

      # select only the backbone atoms for each chain
      backbones = [chain.select_atoms('not name O* H*') for chain in chains]

      # sort the chains, removing any non-backbone atoms
      sorted_backbones = [polymer.sort_backbone(bb) for bb in backbones]
      persistence_length = polymer.PersistenceLength(sorted_backbones)

      # Run the analysis, this will average over all polymer chains
      # and all timesteps in trajectory
      persistence_length = persistence_length.run()
      print(f'The persistence length is: {persistence_length.results.lp}')

      # always check the visualisation of this:
      persistence_length.plot()

  Added in version 0.13.0.

  Changed in version 0.20.0: The run method now automatically performs the exponential fit

  Changed in version 1.0.0: Deprecated `PersistenceLength.perform_fit()` has now been removed.

  Changed in version 2.0.0: Former `results` are now stored as `results.bond_autocorrelation`. `lb`, `lp`, `fit` are now stored in a `MDAnalysis.analysis.base.Results` instance.

  Changed in version 2.10.0: introduced `get_supported_backends()` allowing for parallel execution on `multiprocessing` and `dask` backends.

  classmethod get_supported_backends()

    Tuple with backends supported by the core library for a given class. User can pass either one of these values as `backend=...` to `run()` method, or a custom object that has `apply` method (see documentation for `run()`):

    > - ‘serial’: no parallelization

    > - ‘multiprocessing’: parallelization using multiprocessing.Pool

    > - ‘dask’: parallelization using dask.delayed.compute(). Requires installation of mdanalysis[dask]

    If you want to add your own backend to an existing class, pass a `backends.BackendBase` subclass (see its documentation to learn how to implement it properly), and specify `unsupported_backend=True`.

    Returns:

      names of built-in backends that can be used in `run(backend=...)()`

    Return type:

      tuple

    Added in version 2.8.0.

  property parallelizable

    Boolean mark showing that a given class can be parallelizable with split-apply-combine procedure. Namely, if we can safely distribute `_single_frame()` to multiple workers and then combine them with a proper `_conclude()` call. If set to `False`, no backends except for `serial` are supported.

    Note

    If you want to check parallelizability of the whole class, without explicitly creating an instance of the class, see `_analysis_algorithm_is_parallelizable`. Note that you setting it to other value will break things if the algorithm behind the analysis is not trivially parallelizable.

    Returns:

      if a given `AnalysisBase` subclass instance is parallelizable with split-apply-combine, or not

    Return type:

      bool

    Added in version 2.8.0.

  plot(ax=None)

    Visualize the results and fit

    Parameters:

      ax (matplotlib.Axes, optional) – if provided, the graph is plotted on this axis

    Returns:

      ax

    Return type:

      the axis that the graph was plotted on

  run(start: int = None, stop: int = None, step: int = None, frames: Iterable = None, verbose: bool = None, n_workers: int = None, n_parts: int = None, backend: str | BackendBase = None, *, unsupported_backend: bool = False, progressbar_kwargs=None)

    Perform the calculation

    Parameters:

      - start (int, optional) – start frame of analysis

      - stop (int, optional) – stop frame of analysis

      - step (int, optional) – number of frames to skip between each analysed frame

      - frames (array_like, optional) –

        array of integers or booleans to slice trajectory; `frames` can only be used instead of `start`, `stop`, and `step`. Setting both `frames` and at least one of `start`, `stop`, `step` to a non-default value will raise a `ValueError`.

        Added in version 2.2.0.

      - verbose (bool, optional) – Turn on verbosity

      - progressbar_kwargs (dict, optional) – ProgressBar keywords with custom parameters regarding progress bar position, etc; see `MDAnalysis.lib.log.ProgressBar` for full list. Available only for `backend='serial'`

      - backend (Union[str, BackendBase], optional) –

        By default, performs calculations in a serial fashion. Otherwise, user can choose a backend: `str` is matched to a builtin backend (one of `serial`, `multiprocessing` and `dask`), or a `MDAnalysis.analysis.results.BackendBase` subclass.

        Added in version 2.8.0.

      - n_workers (int) –

        positive integer with number of workers (processes, in case of built-in backends) to split the work between

        Added in version 2.8.0.

      - n_parts (int, optional) –

        number of parts to split computations across. Can be more than number of workers.

        Added in version 2.8.0.

      - unsupported_backend (bool, optional) –

        if you want to run your custom backend on a parallelizable class that has not been tested by developers, by default False

        Added in version 2.8.0.

    Changed in version 2.2.0: Added ability to analyze arbitrary frames by passing a list of frame indices in the frames keyword argument.

    Changed in version 2.5.0: Add progressbar_kwargs parameter, allowing to modify description, position etc of tqdm progressbars

    Changed in version 2.8.0: Introduced `backend`, `n_workers`, `n_parts` and `unsupported_backend` keywords, and refactored the method logic to support parallelizable execution.

MDAnalysis.analysis.polymer.fit_exponential_decay(x, y)

  Fit a function to an exponential decay

  \[y = \exp\left(- \frac{x}{a}\right)\]
  Parameters:

    - x (array_like) – The two arrays of data

    - y (array_like) – The two arrays of data

  Returns:

    a – The coefficient a for this decay

  Return type:

    float

  Notes

  This function assumes that data starts at 1.0 and decays to 0.0

MDAnalysis.analysis.polymer.sort_backbone(backbone)

  Rearrange a linear AtomGroup into backbone order

  Requires that the backbone has bond information, and that only backbone atoms are provided (ie no side chains or hydrogens).

  Parameters:

    backbone (AtomGroup) – the backbone atoms, not necessarily in order

  Returns:

    sorted_backbone – backbone in order, so sorted_backbone[i] is bonded to sorted_backbone[i - 1] and sorted_backbone[i + 1]

  Return type:

    AtomGroup

  Added in version 0.20.0.