Source code for mchammer.observers.cluster_expansion_observer

from ase import Atoms
from icet import ClusterExpansion
from mchammer.observers.base_observer import BaseObserver




class ClusterExpansionObserver(BaseObserver):
    """
    This class represents a cluster expansion (CE) observer.

    A CE observer computes a property described by a CE along the trajectory
    sampled by a Monte Carlo (MC) simulation.
    In general this CE differs from the CE that generates the trajectory.
    In a canonical MC simulation, for example, the latter usually represents
    an energy, while the observed CE could describe the lattice parameter or
    the band gap.

    The observed value is stored in the data container under the tag of the
    observer, which is ``ClusterExpansionObserver`` unless another tag is given
    to :func:`BaseEnsemble.attach_observer
    <mchammer.ensembles.base_ensemble.BaseEnsemble.attach_observer>`.

    Parameters
    ----------
    cluster_expansion
        Cluster expansion to be used for observation.
    interval
        Observation interval in trial steps.
        By default the ensemble the observer is attached to sets the interval
        to the number of sites in the structure.

    Example
    -------
    The following snippet samples an Ising-like cluster expansion in the
    canonical ensemble and observes a second cluster expansion along the
    trajectory.
    Both sets of parameters are made up to keep the example self-contained::

        >>> from ase.build import bulk
        >>> from icet import ClusterExpansion, ClusterSpace
        >>> from mchammer.calculators import ClusterExpansionCalculator
        >>> from mchammer.ensembles import CanonicalEnsemble
        >>> from mchammer.observers import ClusterExpansionObserver

        >>> # prepare the cluster expansions
        >>> prim = bulk('Au')
        >>> cs = ClusterSpace(prim, cutoffs=[4.3], chemical_symbols=['Ag', 'Au'])
        >>> ce_energy = ClusterExpansion(cs, [0, 0, 0.1, -0.02])
        >>> ce_volume = ClusterExpansion(cs, [17.0, 0.5, 0.05, 0.01])

        >>> # prepare initial configuration
        >>> structure = prim.repeat(3)
        >>> for k in range(5):
        ...     structure[k].symbol = 'Ag'

        >>> # set up the simulation and attach the observer
        >>> calculator = ClusterExpansionCalculator(structure, ce_energy)
        >>> mc = CanonicalEnsemble(structure=structure, calculator=calculator,
        ...                        temperature=600)
        >>> observer = ClusterExpansionObserver(ce_volume, interval=len(structure))
        >>> mc.attach_observer(observer, tag='volume')
        >>> mc.run(1000)

        >>> # the observed values are available from the data container
        >>> volumes = mc.data_container.get('volume')
    """

    def __init__(self, cluster_expansion: ClusterExpansion,
                 interval: int | None = None) -> None:
        super().__init__(interval=interval, return_type=float, tag='ClusterExpansionObserver')
        self._cluster_expansion = cluster_expansion



    def get_observable(self, structure: Atoms) -> float:
        """
        Returns the value the cluster expansion predicts for a configuration.

        Parameters
        ----------
        structure
            Atomic configuration to observe.
        """
        return self._cluster_expansion.predict(structure)