Source code for mchammer.kinetics.transition

"""
This module provides the Transition class, the descriptor that couples a
barrier model with an attempt frequency for kinetic Monte Carlo.
"""

from typing import Any

from icet.input_output.repr_tools import html_representation, text_representation

from .local_cluster_expansion_calculator import LocalClusterExpansionCalculator
from ..configuration_manager import VACANCY_ATOMIC_NUMBER




class Transition:
    """Descriptor of one transition type in a kinetic Monte Carlo simulation.

    A transition bundles the barrier model of a hop type with its attempt
    frequency.
    The event catalog of a simulation derives from the event prototypes of
    its transitions.

    Parameters
    ----------
    calculator
        Calculator for the kinetically resolved activation energy of the
        hop type, in eV.
    attempt_frequency
        Attempt frequency of the hop in Hz, which sets the absolute time
        scale of the simulation.
    """

    def __init__(self,
                 calculator: LocalClusterExpansionCalculator,
                 attempt_frequency: float) -> None:
        if attempt_frequency <= 0:
            raise ValueError('attempt_frequency must be positive'
                             f' ({attempt_frequency})')
        # A hop carries the migrating species onto a vacant site, so a
        # migrating species that is the vacancy describes a hop that
        # changes nothing while the clock advances on it.
        if calculator.migrating_number == VACANCY_ATOMIC_NUMBER:
            raise ValueError(
                'The migrating species of the barrier model is the vacancy'
                ' species, so every hop of this transition would carry a'
                ' vacancy onto a vacancy and leave the configuration'
                ' unchanged')
        self._calculator = calculator
        self._attempt_frequency = float(attempt_frequency)

    @property
    def calculator(self) -> LocalClusterExpansionCalculator:
        """Calculator for the kinetically resolved activation energy."""
        return self._calculator

    @property
    def attempt_frequency(self) -> float:
        """Attempt frequency of the hop in Hz."""
        return self._attempt_frequency

    @property
    def migrating_number(self) -> int:
        """Atomic number of the migrating species."""
        return self._calculator.migrating_number

    def __repr__(self) -> str:
        space = self._calculator.local_cluster_expansion.local_cluster_space
        return (f'{type(self).__name__}('
                f'species={space.event.species!r}, '
                f'attempt_frequency={self._attempt_frequency!r})')

    def _get_rows(self) -> list[tuple[str, Any]]:
        """Returns the label and value pairs that describe this transition."""
        space = self._calculator.local_cluster_expansion.local_cluster_space
        return [('migrating species', space.event.species),
                ('attempt frequency', self._attempt_frequency),
                ('event instances', len(self._calculator.event_instances)),
                ('barrier model parameters',
                 len(self._calculator.local_cluster_expansion))]

    def __str__(self) -> str:
        """ String representation. """
        return text_representation(title='Transition', rows=self._get_rows(),
                                   width=60, label_width=24)

    def _repr_html_(self) -> str:
        """ HTML representation. Used, e.g., in jupyter notebooks. """
        return html_representation(title='Transition', rows=self._get_rows())