Skip to content

corrections

Dynamical corrections.

BSD 3-Clause License Copyright © 2022, Daniel Nagel All rights reserved.

Authors: Daniel Nagel

LagtimeError

Bases: Exception

An exception for the given lagtime was raised.

dynamical_coring(trajs, lagtime, iterative=True)

Fix spurious transitions with dynamical coring.

Projecting high dimensional data onto low dimensional collective variables can result in spurious state transitions which can be correct for applying dynamical coring, for more details see Nagel et al. 1.

Note

Applying dynamical coring on a msmhelper.LumpedStateTraj is not supported. The reason is that while applying dynamical coring on the microstate level leads to different coarse-graining, applying it on the macrostate level the HS-Projection is not well defined anymore.

  1. Nagel et al., Dynamical coring of Markov state models, J. Chem. Phys., 150, 094111 (2019), doi:10.1063/1.5081767 ↩

Parameters:

  • trajs (StateTraj or list or ndarray or list of ndarray) –

    State trajectory/trajectories. The states should start from zero and need to be integers.

  • lagtime (int) –

    Lagtime [frames] is the minimum time a trajectory is required to spend in a new state to be accepted.

  • iterative (bool, default: True ) –

    If True dynamical coring is applied iteratively with increasing lagtimes, so lagtime=1, 2, ..., lagtimes.

Returns:

  • trajs ( StateTraj ) –

    Dynamically corrected state trajectory.

Source code in src/msmhelper/md/corrections.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
def dynamical_coring(trajs, lagtime, iterative=True):
    """Fix spurious transitions with dynamical coring.

    Projecting high dimensional data onto low dimensional collective variables
    can result in spurious state transitions which can be correct for applying
    dynamical coring, for more details see Nagel et al. [^1].

    !!! note
        Applying dynamical coring on a [msmhelper.LumpedStateTraj][] is not
        supported. The reason is that while applying dynamical coring on the
        microstate level leads to different coarse-graining, applying it on the
        macrostate level the HS-Projection is not well defined anymore.

    [^1]: Nagel et al., **Dynamical coring of Markov state models**,
        *J. Chem. Phys.*, 150, 094111 (2019),
        doi:[10.1063/1.5081767](https://doi.org/10.1063/1.5081767)

    Parameters
    ----------
    trajs : StateTraj or list or ndarray or list of ndarray
        State trajectory/trajectories. The states should start from zero and
        need to be integers.
    lagtime : int
        Lagtime [frames] is the minimum time a trajectory is required to spend
        in a new state to be accepted.
    iterative : bool, optional
        If `True` dynamical coring is applied iteratively with increasing
        lagtimes, so lagtime=1, 2, ..., lagtimes.

    Returns
    -------
    trajs : StateTraj
        Dynamically corrected state trajectory.

    """
    trajs = StateTraj(trajs)

    if isinstance(trajs, LumpedStateTraj):
        raise NotImplementedError(
            'Applying dynamical coring on a LumpedStateTraj is not supported. '
            'The reason is that while applying dynamical coring on the '
            'microstate level leads to different coarse-graining, applying it '
            'on the macrostate level the HS-Projection is not well defined '
            'anymore.'
        )

    # convert trajs to numba list # noqa: SC100
    if numba.config.DISABLE_JIT:
        cored_trajs = trajs.trajs
    else:  # pragma: no cover
        cored_trajs = numba.typed.List(trajs.trajs)

    if lagtime <= 0:
        raise ValueError('The lagtime should be greater 0.')

    # if lagtime == 1 nothing changes
    if lagtime == 1:
        return trajs

    # catch if lagtime <=1
    return StateTraj(
        _dynamical_coring(cored_trajs, lagtime, iterative),
    )