Source code for ccu.workflows.mh

"""DFT-code agnostic standard minima hopping workflow utilities.

Example:
    Run a minima hopping simulation with CO on a Au surface

    .. code-block:: python

        import logging

        from ase.build import bulk
        from ase.calculators.vasp.vasp import Vasp
        from ase.optimize.minimahopping import MinimaHopping
        from ccu.adsorption.adsorbates import get_adsorbate
        from ccu.workflows.mh import run_minima_hopping

        logging.basicConfig(level=logging.DEBUG)

        atoms = bulk("Au") * 6
        atoms.center(vacuum=10, axis=2)
        surface_atom = max(atoms, key=lambda a: a.position[2])
        cooh = get_adsorbate("CO")
        com = cooh.get_center_of_mass()
        site = surface_atom.position + [0, 0, 3]
        direction = site - com

        for atom in cooh:
            atom.position += direction

        atoms += cooh

        atoms.calc = Vasp(...)
        hopper = MinimaHopping(atoms, ...)
        run_minima_hopping(hopper, totalsteps=..., maxtemp=...)
"""

import logging

from ase.optimize.minimahopping import MinimaHopping

from ccu import SETTINGS

logger = logging.getLogger(__name__)




def run_minima_hopping(
    hopper: MinimaHopping,
    totalsteps: int | None = None,
    maxtemp: float | None = None,
    output: str | None = None,
) -> None:
    """Run a minima hopping simulation.

    Args:
        hopper: An initialized :class:`MinimaHopping` object.
        totalsteps: The maximum number of minima hopping steps (the outer
            part of the MH algorithm). Defaults to None.
        maxtemp: The maximum temperature to which the system will be increased
            in order to find new basins. Defaults to None.
        output: The name of the output atoms file. Defaults to
            ``SETTINGS.OUTPUT_ATOMS_FILE``.
    """
    logger.debug("Running minima hopping")
    logger.debug("Printing minima hopping parameters")

    for k in hopper._default_settings:
        v = getattr(hopper, f"_{k}")
        logger.info(f"{k} = {v!r}")

    hopper(totalsteps=totalsteps, maxtemp=maxtemp)
    # Write output atoms (identical to input atoms) just in case we're
    # expecting to read output atoms
    output = output or SETTINGS.OUTPUT_ATOMS_FILE
    hopper._atoms.write(output)

    logger.info(
        "Successfully ran minima hopping. Minima found: %s", hopper._counter
    )
    return hopper