Fix Trajectory Unwrapping

[andthum]

Fix Trajectory Unwrapping

Type of change

• Change of core package.
• Change of scripts.

• Bug fix.
• New feature.
• Code refactoring.
• Dependency update.
• Documentation update.
• Maintenance.
• Other: Description.

• Non-breaking (backward-compatible) change.
• Breaking (non-backward-compatible) change.

Proposed changes

Breaking Changes:

• Script unwrap_trj.py: Completely rewrite the script to use the new function mdtools.box.unwrap_frame.
  Add the following command-line arguments:
  • -b: First frame to read.
  • --every: Read every n-th frame.
  • --method: The unwrapping method to use.
    Rename the following command-line arguments:
  • --otrj to --trj-out: Output trajectory.
  • --otop to --top-out: Output topology.
  • --compound to --cmp: The compounds to make whole.
    Remove the following command-line arguments:
  • --make-whole.
  • --keep-whole.
• Remove the function mdtools.box.unwrap because it is replaced by the new function mdtools.box.unwrap_frame.
• Remove the function mdtools.box.unwrap_trj because it uses the displacement unwrapping method that only works for constant simulation boxes and was only implemented for orthorhombic boxes. Use the script unwrap_trj or the function mdtools.box.unwrap_frame instead.
• Function mdtools.box.vdist: If box has shape (k, 6) a two-dimensional position array is not any longer interpreted to have the shape (k, 3). Instead it is now interpreted to have shape (n, 3). Here k is the number of frames and n is the number of particles.
• Function mdtools.box.wrap_pos: Remove the mda_backend argument, because mdtools.box.wrap_pos no longer uses MDAnalysis.lib.distances.apply_PBC internally.
• Function mdtools.box.wrap_pos: If box has shape (k, 6) a two-dimensional position array is not any longer interpreted to have the shape (k, 3). Instead it is now interpreted to have shape (n, 3). Here k is the number of frames and n is the number of particles.
• Function mdtools.structure.wcenter_pos: Remove the mda_backend argument.
• Function mdtools.structure.wcenter_pos: If box has shape (k, 6) a two-dimensional position array is not any longer interpreted to have the shape (k, 3). Instead it is now interpreted to have shape (n, 3). Here k is the number of frames and n is the number of particles.
• Function mdtools.structure.wcenter_pos: If centers are calculated for multiple frames, always return an array of shape (k, 1, 3) instead of (k, 3).

New Features:

• Create a new script rmsd_trj_trj.py that calculates the Root Mean Square Deviation (RMSD) between two trajectories for each frame.
• Add a new function mdtools.box.unwrap_frame that unwraps a single trajectory frame. The new functions implements five different unwrapping algorithms: "scaling", "heuristic", "displacement", "hybrid", "in-house". See
  • Sören von Bülow, Jakob Tómas Bullerjahn, and Gerhard Hummer,
    Systematic errors in diffusion coefficients from long-time moleculardynamics simulations at constant pressure,
    The Journal of Chemical Physics, 2020, 153, 021101,
  • Martin Kulke and Josh V. Vermaas,
    Reversible Unwrapping Algorithm for Constant-Pressure Molecular Dynamics Simulations,
    Journal of Chemical Theory and Computation, 2022, 18, 10, 6161-6171.
• Function mdtools.box.vdist: Add support for triclinic simulation boxes.
• Function mdtools.box.wrap_pos: Add support for triclinic simulation boxes.
• Function mdtools.structure.rmsd: Add support for triclinic simulation boxes.
• Function mdtools.structure.wcenter_pos: Add support for triclinic simulation boxes.
• Add a new function mdtools.box.cart2box that transforms Cartesian coordinates to box coordinates.
• Add a new function mdtools.box.box2cart that transforms box coordinates to Cartesian coordinates.
• Add a new function mdtools.box.triclinic_vectors that converts the length-angle representation of a simulation box to the matrix representation.
• Add a new function mdtools.box.triclinic_box that converts the matrix representation of a simulation box to the length-angle representation.
• Add a new function mdtools.check.box_mat that checks if the input array satisfies the conditions for a (triclinic) simulation box matrix.

Bug fixes:

• Function mdtools.box.make_whole: Remove the debug argument that was parsed to MDAnalysis.core.groups.AtomGroup.unwrap although MDAnalysis.core.groups.AtomGroup.unwrap has no debug argument.
• Various minor bug fixes in the mdtools.check module.

Documentation changes

• Fix broken links in the documentation.
• Fix various typos.
• Include the new install_mdt build option to the developer's guide.

Maintenance

• Sphinx Makefile for doc pages: Add a new make build option install_mdt that (re-)installs MDTools. Re-installing MDTools is necessary when changing the docstring of a script. Otherwise the changes won't be recognized by Sphinx.
• Run Sphinx linkcheck during the CI workflow.

Requested reviewers

@andthum

PR checklist

• I followed the guidelines in the Developer's guide.
• New/changed code is properly tested.
• New/changed code is properly documented.
• The CI workflow is passing.