Bouchaud trap model

The Bouchaud trap model, walkers that escape from traps of exponentially distributed depths.

• Name: trap_model
• Field: physics/statistical_mechanics
• Formalism: renewal process
• References: Bouchaud 1992; Monthus and Bouchaud 1996; Bertin 2021

Factory

@register_model(
    field='physics/statistical_mechanics',
    tags=('trap model', 'renewal process', 'aging', 'glass'),
    references=('Bouchaud 1992', 'Monthus and Bouchaud 1996', 'Bertin 2021'),
    defaults={'until': 10000.0, 'dt': 50.0},
)
def trap_model(
    n_walkers: int = 500,
    *,
    T: float = 0.5,
    tau0: float = 1.0,
    random_state: int | np.random.Generator | None = 0,
) -> System:
    """Return the Bouchaud trap model, walkers that escape from traps of exponentially distributed depths.

    The escape times `tau0 exp(E / T)` of depths with the density `exp(-E)` have the tail `tau^(-1 - T)`. Below the
    glass temperature `T = 1` their mean diverges, so the walkers fall into ever deeper traps, the number of escapes
    grows as `t^T` instead of linearly, and the system ages without reaching equilibrium.

    Args:
        n_walkers:
            The number of independent walkers.

        T:
            The temperature, in units of the mean depth.

        tau0:
            The escape time from a trap of zero depth.

        random_state:
            The seed or generator of the first traps.

    Returns:
        system:
            The model, with the places `walkers.x`, the depths `walkers.E`, and the escape count `escapes.renewals`.

    Examples:
        >>> from skcomplex.models.physics.statistical_mechanics import trap_model
        >>> trap_model(10, T=0.8).elements[0].values['T']
        0.8
    """
    rng = np.random.default_rng(random_state)
    walkers = GroupElement(
        'walkers',
        element=TrapWalkerElement,
        size=n_walkers,
        values={'x': rng.random((n_walkers, 2)), 'E': rng.exponential(1.0, n_walkers), 'T': T, 'tau0': tau0},
    )
    return System(elements=[walkers], space=ContinuousSpace(n_dim=2))

Components

class TrapWalkerElement(Element):
    """Walker in a trap of depth `E`, which escapes after an exponential time of mean `tau0 exp(E / T)`.

    On escape the walker falls into a new trap of the fully connected landscape, at a uniformly random place in the
    unit square, whose depth is drawn from the density `exp(-E)`.

    Args:
        label:
            The label of the walker or the group.

        visual:
            How the element is drawn, or `None` for `default_visual_`.

        x:
            The place of the trap.

        E:
            The depth of the trap.

        T:
            The temperature, in units of the mean depth.

        tau0:
            The escape time from a trap of zero depth.

    Examples:
        >>> from skcomplex.models.physics.statistical_mechanics import TrapWalkerElement
        >>> TrapWalkerElement('walker', T=0.5).T
        0.5
    """

    def __init__(
        self,
        label: str,
        visual: VisualSpec | None = VisualSpec('points', {'position': 'x', 'color_by': 'E', 'color_range': (0.0, 5.0)}),
        *,
        x: Annotated[npt.ArrayLike, StateSpec(vector=True, role='position')] = 0.5,
        E: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 1.0,
        T: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 0.5,
        tau0: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    ) -> None:
        super().__init__(label, visual=visual)
        self.x = x
        self.E = E
        self.T = T
        self.tau0 = tau0

    def _get_laws(self, s: SimpleNamespace) -> list[BaseLaw]:
        """Return the escapes after activated waiting times.

        Args:
            s:
                The namespace of the symbols the laws can use.

        Returns:
            laws:
                The laws of the component.
        """
        reset = {item: uniform(f'place{index}') for index, item in enumerate(s.x)}
        waiting = draw('escape', 'expon', scale=s.tau0 * exp(s.E / s.T))
        return [JumpLaw(waiting=waiting, reset={**reset, s.E: draw('depth', 'expon')}, label='escapes')]