agox 3.10.0__tar.gz → 3.10.1__tar.gz

{agox-3.10.0/agox.egg-info → agox-3.10.1}/PKG-INFO

@@ -1,14 +1,13 @@
 Metadata-Version: 2.4
 Name: agox
-Version: 3.10.0
+Version: 3.10.1
 Summary: Atomistic Global Optimziation X is a framework for structure optimization in materials science.
 Author: AGOX Developers
 Author-email: "Mads-Peter V. Christiansen" <machri@phys.au.dk>, Nikolaj Rønne <nronne@phys.au.dk>, Bjørk Hammer <hammer@phys.au.dk>
-License: GNU General Public License v3.0 or later
+License-Expression: GPL-3.0-only
 Project-URL: homepage, https://agox.gitlab.io/agox/
 Project-URL: Repository, https://gitlab.com/agox/agox
 Classifier: Development Status :: 5 - Production/Stable
-Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3.10

{agox-3.10.0 → agox-3.10.1}/agox/__init__.py

@@ -1,7 +1,7 @@
 import os
 
 # Versioning
-__version_info__ = (3, 10, 0)
+__version_info__ = (3, 10, 1)
 __version__ = "{}.{}.{}".format(*__version_info__)
 
 # Extra versioning - Mainly for managing Pypi releases.

agox-3.10.1/agox/acquisitors/ABC_acquisitor.py

@@ -0,0 +1,214 @@
+from abc import ABC, abstractmethod
+from typing import Callable
+
+import numpy as np
+
+from agox.observer import Observer
+
+
+class AcquisitorBaseClass(ABC, Observer):
+    """
+    Base-class for acquisitors.
+
+    Parameters
+    -----------
+    order : int
+        Order of the observer.
+    gets : dict
+        Dictionary of gets, passed to the agox.observer.Observer.
+    sets : dict
+        Dictionary of sets, passed to the agox.observer.Observer.
+    """
+
+    def __init__(
+        self,
+        order: int | float = 4,
+        gets: dict[str, str] | None = None,
+        sets: dict[str, str] | None = None,
+        surname: str | None = None,
+        skip_function: Callable = None,
+        **kwargs,
+    ) -> None:
+        if gets is None:
+            gets = {"get_key": "candidates"}        
+        if sets is None:
+            sets = {"set_key": "prioritized_candidates"}
+
+        Observer.__init__(self, gets=gets, sets=sets, order=order, surname=surname, **kwargs)
+        self.skip_function = skip_function
+
+        self.add_observer_method(
+            self.prioritize_candidates,
+            sets=self.sets[0],
+            gets=self.gets[0],
+            order=self.order[0],
+            handler_identifier="AGOX",
+        )
+
+    def _skip_function(self, candidate_list):
+        """
+        Default function defining probablility acquisitor returns nothing.
+
+        """
+        if self.skip_function is not None:
+            return self.skip_function(self, candidate_list)
+        else:
+            return False
+
+    @abstractmethod
+    def calculate_acquisition_function(self, candidates):  # pragma: no cover
+        """
+        Implements the acquisition function.
+
+        Parameters
+        -----------
+        candidates : list
+            List of candidates that the acquisition function will be evaluated for.
+
+        Returns
+        --------
+        np.array
+            Numpy array of acquisition function values.
+
+        """
+        return acquisition_values
+
+    @Observer.observer_method
+    def prioritize_candidates(self, state):
+        """
+        Method that is attached to the AGOX iteration loop as an observer - not intended for use outside of that loop.
+
+        The method does the following:
+        1. Gets candidates from the cache using 'get_key'.
+        2. Removes 'None' from the candidate list.
+        3. Calculates and sorts according to acquisition function.
+        4. Adds the sorted candidates to cache with 'set_key'
+        5. Prints information.
+
+        Parameters
+        -----------
+        state: agox.main.State
+            State object that contains the iteration data.
+        """
+
+        # Get data from the iteration data dict.
+        candidate_list = state.get_from_cache(self, self.get_key)
+        candidate_list = list(filter(None, candidate_list))
+
+        if len(candidate_list) > 0:
+            if self._skip_function(candidate_list):
+                state.add_to_cache(self, self.set_key, [], mode="a")
+                return
+
+        # Calculate acquisition function values and sort:
+        if self.do_check():
+            candidate_list, acquisition_values = self.sort_according_to_acquisition_function(candidate_list)
+        else:
+            acquisition_values = np.zeros(len(candidate_list))
+        # Add the prioritized candidates to the iteration data in append mode!
+        state.add_to_cache(self, self.set_key, candidate_list, mode="a")
+
+        self.print_information(candidate_list, acquisition_values)
+
+    ########################################################################################
+    # Default methods
+    ########################################################################################
+
+    def sort_according_to_acquisition_function(self, candidates):
+        """
+        Calculates acquisiton-function based on the implemeneted version calculate_acquisition_function.
+
+        Note: Sorted so that the candidate with the LOWEST acquisition function value is first.
+
+        Parameters
+        ------------
+        candidates: list
+            List of candidate objects.
+
+        Returns:
+        -----------
+        list
+            List of candidates sorted according to increasing acquisition value (lowest first).
+        np.array
+            Array of acquisition function values in the same order as the sorted list, i.e. increasing.
+
+        """
+        acquisition_values = self.calculate_acquisition_function(candidates)
+        sort_idx = np.argsort(acquisition_values)
+        sorted_candidates = [candidates[i] for i in sort_idx]
+        acquisition_values = acquisition_values[sort_idx]
+        [
+            candidate.add_meta_information("acquisition_value", acquisition_value)
+            for candidate, acquisition_value in zip(sorted_candidates, acquisition_values)
+        ]
+        return sorted_candidates, acquisition_values
+
+    def get_random_candidate(self):
+        DeprecationWarning("Will be removed in the future. Please use collector.get_random_candidate")
+        return self.collector.get_random_candidate()
+
+    def print_information(self, candidates, acquisition_values):
+        """
+        Printing function for analysis/debugging/sanity checking.
+
+        Parameters
+        -----------
+        candidates: list
+            List of candidate objects.
+        acquisition_values: np.array
+            Acquisition function value for each candidate in 'candidates'.
+        """
+
+    def get_acquisition_calculator(self):
+        """
+        Creates a calculator for the acquisiton function that can be used for e.g. relaxation.
+
+        Returns
+        --------
+        ASE Calculator
+            ASE calculator where the energy is the acquisition function and forces are the forces of the acquisition forces.
+        """
+        raise NotImplementedError("'get_acqusition_calculator' is not implemented for this acquisitor")
+
+
+from ase.calculators.calculator import Calculator
+
+from agox.module import Module
+
+
+class AcquisitonCalculatorBaseClass(Calculator, Module):
+    name = "AcqusitionCalculator"
+
+    """
+    Base-class for calculators that are used for acquisition functions.
+
+    Parameters
+    -----------
+    model: agox.models.ABC_model.ModelBaseClass 
+        A model that is used for the acquisition function.
+    kwargs: dict
+        Dictionary of keyword arguments passed to the Calculator-class.
+
+    """
+
+    def __init__(self, model, **kwargs):
+        Calculator.__init__(self, **kwargs)
+        Module.__init__(self)
+        self.model = model
+
+    def get_model_parameters(self):
+        parameters = self.model.get_model_parameters()
+        return parameters
+
+    def set_model_parameters(self, parameters):
+        self.model.set_model_parameters(parameters)
+
+    def get_iteration_number(self):
+        if hasattr(self, "get_iteration_counter"):
+            return self.get_iteration_counter()
+        else:
+            return self.iteration
+
+    @property
+    def ready_state(self):
+        return self.model.ready_state

agox-3.10.1/agox/acquisitors/EI.py

@@ -0,0 +1,51 @@
+import numpy as np
+from scipy.stats import norm
+
+from agox.acquisitors import AcquisitorBaseClass
+from agox.observer import Observer
+
+
+class ExpectedImprovementAcquisitor(AcquisitorBaseClass):
+    name = "EIAcquisitor"
+
+    def __init__(self, model, database, xi=0.01, **kwargs):
+        super().__init__(maximize=True, **kwargs)
+        self.model = model
+        self.xi = xi
+        self.lowest_energy = 10e10
+        self.add_observer_method(self.update, sets={}, gets={}, order=0, handler_identifier="database")
+        self.attach(database)
+
+    def calculate_acquisition_function(self, candidates):
+        fitness = np.zeros(len(candidates))
+        for i, candidate in enumerate(candidates):
+            E, sigma = self.model.predict_energy_and_uncertainty(candidate)
+            fitness[i] = self.acquisition_function(E, sigma)
+            candidate.add_meta_information("model_energy", E)
+            candidate.add_meta_information("uncertainty", sigma)
+        return fitness
+
+    def acquisition_function(self, E, sigma):
+        mu = E
+        mu_opt = self.lowest_energy
+        with np.errstate(divide="warn"):
+            imp = mu_opt - mu - self.xi
+            Z = imp / sigma
+            ei = imp * norm.cdf(Z) + sigma * norm.pdf(Z)
+        return ei
+
+    def print_information(self, candidates, acquisition_values):
+        if self.do_check():
+            for i, candidate in enumerate(candidates):
+                fitness = acquisition_values[i]
+                E = candidate.get_meta_information("model_energy")
+                sigma = candidate.get_meta_information("uncertainty")
+                self.writer(f"Candidate {i}: E = {E:8.3f}, s = {sigma:8.3f}, EI = {fitness:8.6f}")
+
+    @Observer.observer_method
+    def update(self, database, state):
+        self.lowest_energy = database.get_best_energy()
+        self.writer("Lowest energy: {}".format(self.lowest_energy))
+
+    def do_check(self, **kwargs):
+        return self.model.ready_state

agox-3.10.1/agox/acquisitors/LCB.py

@@ -0,0 +1,101 @@
+import numpy as np
+from ase.calculators.calculator import all_changes
+
+from agox.acquisitors.ABC_acquisitor import AcquisitonCalculatorBaseClass, AcquisitorBaseClass
+
+
+class LowerConfidenceBoundAcquisitor(AcquisitorBaseClass):
+    """
+    Lower Confidence Bound Acquisitor, using predictions and uncertainties from a model.
+
+    The acquisition function is given by
+
+    .. math::
+
+        F(x) = E(x) - \kappa \sigma(x)
+
+
+    Parameters
+    -----------
+
+    model: agox.models.ABC_model.ModelBaseClass
+        Model that is used for the acquisition function.
+    kappa: float
+        Constant that is multiplied with the uncertainty.
+    kwargs: dict
+        Dictionary of keyword arguments passed to the AcquisitorBaseClass.
+    """
+
+    name = "LCBAcquisitor"
+
+    def __init__(self, model, kappa=1, **kwargs):
+        super().__init__(**kwargs)
+        self.kappa = kappa
+        self.model = model
+
+    def calculate_acquisition_function(self, candidates):
+        fitness = np.zeros(len(candidates))
+
+        # Attach calculator and get model_energy
+        for i, candidate in enumerate(candidates):
+            E, sigma = self.model.predict_energy_and_uncertainty(candidate)
+            fitness[i] = self.acquisition_function(E, sigma)
+
+            # For printing:
+            candidate.add_meta_information("model_energy", E)
+            candidate.add_meta_information("uncertainty", sigma)
+
+        return fitness
+
+    def print_information(self, candidates, acquisition_values):
+
+        format_float = lambda f: f"{f:.3f}"
+
+        columns = ['Candidate', 'Energy', 'Uncertainty', 'Fitness', 'Generator']
+        rows = []
+        if self.model.ready_state:
+            for i, candidate in enumerate(candidates):
+                fitness = format_float(acquisition_values[i])
+                Emodel = format_float(candidate.get_meta_information("model_energy"))
+                sigma = format_float(candidate.get_meta_information("uncertainty"))
+                generator = candidate.get_meta_information("generator")
+                rows.append([str(i), Emodel, sigma, fitness, generator])
+        
+        self.writer.write_table(columns, rows, show_lines=False, show_edge=False)
+
+    def get_acquisition_calculator(self):
+        return LowerConfidenceBoundCalculator(self.model, self.acquisition_function, self.acquisition_force)
+
+    def acquisition_function(self, E, sigma):
+        return E - self.kappa * sigma
+
+    def acquisition_force(self, E, F, sigma, sigma_force):
+        return F - self.kappa * sigma_force
+
+    def do_check(self, **kwargs):
+        return self.model.ready_state
+
+
+class LowerConfidenceBoundCalculator(AcquisitonCalculatorBaseClass):
+    implemented_properties = ["energy", "forces"]
+
+    def __init__(self, model, acquisition_function, acquisition_force, **kwargs):
+        super().__init__(model, **kwargs)
+        self.acquisition_function = acquisition_function
+        self.acquisition_force = acquisition_force
+
+    def calculate(self, atoms=None, properties=["energy"], system_changes=all_changes):
+        super().calculate(atoms, properties, system_changes)
+
+        derivatives = "forces" in properties
+        model_data = self.model.converter(atoms, derivatives=derivatives)
+
+        E = self.model.predict_energy(atoms, **model_data)
+        sigma = self.model.predict_uncertainty(atoms, **model_data)
+        self.results["energy"] = self.acquisition_function(E, sigma)
+
+        if derivatives:
+            F = self.model.predict_forces(atoms, **model_data)
+            sigma_force = self.model.predict_uncertainty_forces(atoms, **model_data)
+
+            self.results["forces"] = self.acquisition_force(E, F, sigma, sigma_force)

agox-3.10.1/agox/acquisitors/LCB_penalty.py

@@ -0,0 +1,130 @@
+from collections import Counter
+from collections.abc import Hashable
+from typing import List
+
+import numpy as np
+from numpy.typing import NDArray
+
+from agox.acquisitors.LCB import LowerConfidenceBoundAcquisitor
+from agox.candidates.standard import StandardCandidate
+from agox.databases.ABC_database import DatabaseBaseClass
+from agox.main import State
+from agox.models.ABC_model import ModelBaseClass
+from agox.models.descriptors import SpectralGraphDescriptor, Voronoi
+from agox.models.descriptors.ABC_descriptor import DescriptorBaseClass
+from agox.observer import Observer
+
+
+class LCBPenaltyAcquisitor(LowerConfidenceBoundAcquisitor):
+    """Lower confidence bound acquisitor with a penalty term for repeated
+    descriptor values.
+
+    The acquisition function for selecting candidates is given by
+
+    .. math::
+
+        F(x) = E(x) - \kappa \sigma(x) + \alpha n_D(x),
+
+    where :math:`n_D` is the number of times the descriptor value already
+    exists for the candidates in the database, and :math:`\alpha` is the
+    penalty scale value.
+
+    The acquisition function for relaxing candidates is equivalent to that of
+    regular LCB, as the :math:`\alpha n_D(x)` term is discontinuous.
+
+    Parameters
+    ----------
+    model : ModelBaseClass
+        Model to obtain energy and uncertainty predictions from.
+    descriptor : DescriptorBaseClass
+        Descriptor to evaluate descriptor values from.
+    penalty_scale : float, optional
+        Scale value for penalty (in eV), by default 1.0
+    """
+
+    def __init__(self, model: ModelBaseClass, descriptor: DescriptorBaseClass, penalty_scale: float = 1.0, **kwargs):
+        super().__init__(model, **kwargs)
+
+        if not isinstance(descriptor, (SpectralGraphDescriptor, Voronoi)):
+            raise ValueError("Descriptor can currently only be graph-type descriptor")
+
+        self.descriptor = descriptor
+        self.penalty_scale = penalty_scale
+
+        self.descriptor_value_counts = Counter()
+
+        self.add_observer_method(
+            self.update_descriptor_values, gets={}, sets={}, order=self.order[0], handler_identifier="database"
+        )
+
+    def calculate_acquisition_function(self, candidates: List[StandardCandidate]) -> NDArray:
+        fitness = np.zeros(len(candidates))
+
+        for i, candidate in enumerate(candidates):
+            E, sigma = self.model.predict_energy_and_uncertainty(candidate)
+
+            descriptor_value = self._get_descriptor_value(candidate)
+            count = self.descriptor_value_counts[descriptor_value]
+            penalty = count * self.penalty_scale
+
+            fitness[i] = self.acquisition_function(E, sigma) + penalty
+
+            candidate.add_meta_information("model_energy", E)
+            candidate.add_meta_information("uncertainty", sigma)
+            candidate.add_meta_information("penalty", penalty)
+
+        return fitness
+
+    def print_information(self, candidates: List[StandardCandidate], acquisition_values: List[float]) -> None:
+        if self.model.ready_state:
+            for i, candidate in enumerate(candidates):
+                fitness = acquisition_values[i]
+                Emodel = candidate.get_meta_information("model_energy")
+                sigma = candidate.get_meta_information("uncertainty")
+                penalty = candidate.get_meta_information("penalty")
+                self.writer(
+                    "Candidate: E={:8.3f}, s={:8.3f}, p={:7.2f}, F={:8.3f}".format(Emodel, sigma, penalty, fitness)
+                )
+
+    def attach_to_database(self, database: DatabaseBaseClass) -> None:
+        if not isinstance(database, DatabaseBaseClass):
+            raise TypeError(f"{database} is not a DatabaseBaseClass object")
+
+        print(f"{self.name}: Attaching to database: {database}")
+        self.attach(database)
+
+    @Observer.observer_method
+    def update_descriptor_values(self, database: DatabaseBaseClass, state: State) -> None:
+        """Update the internal counter of descriptor values present in the
+        database.
+        """
+        candidates = database.get_all_candidates()
+        new_candidates = candidates[sum(self.descriptor_value_counts.values()):]
+
+        for candidate in new_candidates:
+            descriptor_value = self._get_descriptor_value(candidate)
+            self.descriptor_value_counts[descriptor_value] += 1
+
+        s = "s" if len(new_candidates) != 1 else ""
+        self.writer(f"Added {len(new_candidates)} structure{s} to the descriptor list")
+
+    def _get_descriptor_value(self, candidate: StandardCandidate) -> Hashable:
+        """Obtain a hashable descriptor value to store in the internal counter.
+
+        Parameters
+        ----------
+        candidate : StandardCandidate
+            Candidate to evaluate the descriptor for.
+
+        Returns
+        -------
+        Hashable
+            Hashable descriptor value.
+        """
+        descriptor_value = self.descriptor.get_features(candidate)
+
+        # convert to hashable object
+        if isinstance(descriptor_value, np.ndarray):
+            descriptor_value = descriptor_value.data.tobytes()
+
+        return descriptor_value

agox-3.10.1/agox/acquisitors/LCB_power.py

@@ -0,0 +1,16 @@
+
+from agox.acquisitors.LCB import LowerConfidenceBoundAcquisitor
+
+
+class PowerLowerConfidenceBoundAcquisitor(LowerConfidenceBoundAcquisitor):
+    name = "PowerLowerConfindenceBoundAcquisitor"
+
+    def __init__(self, power=0, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.power = power
+
+    def acquisition_function(self, E, sigma):
+        return E - self.kappa * sigma**self.power
+
+    def acquisition_force(self, E, F, sigma, sigma_force):
+        return F - self.kappa * self.power * sigma ** (self.power - 1) * sigma_force

agox-3.10.1/agox/acquisitors/__init__.py

@@ -0,0 +1,38 @@
+r"""
+Acquisitors are used to select the next candidate to evaluate among a number of
+candidates, usually by sorting according to some metric.
+The concept of acquisitors comes from Bayesian search algorithms.
+
+A common acquisitor is the Lower Confidence Bound (LCB) acquisitor, which
+selects according to the expression
+
+.. math::
+    LCB(x) = E(x) - \kappa \sigma(x).
+
+Where E(x) is a prediction of the objective function at x, and :math:`\sigma(x)`
+is the uncertainty of the prediction. :math:`\kappa` is a parameter that
+controls the trade-off between exploration and exploitation.
+This lets an algorithm choose which candidates to evaluate, but
+does require the generation of multiple candidates to choose from.
+"""
+# ruff: noqa: I001, E402
+from typing import TypeAlias
+from .ABC_acquisitor import AcquisitonCalculatorBaseClass, AcquisitorBaseClass
+Acquisitor: TypeAlias = AcquisitorBaseClass
+
+from .LCB import LowerConfidenceBoundAcquisitor
+from .LCB_penalty import LCBPenaltyAcquisitor
+from .LCB_power import PowerLowerConfidenceBoundAcquisitor
+from .meta_acquisitor import MetaInformationAcquisitor
+from .replica_exchange.default import ReplicaExchangeAcquisitor
+
+__all__ = [
+    "AcquisitorBaseClass",
+    "Acquisitor",
+    "LowerConfidenceBoundAcquisitor",
+    "LCBPenaltyAcquisitor",
+    "PowerLowerConfidenceBoundAcquisitor",
+    "AcquisitonCalculatorBaseClass",
+    "MetaInformationAcquisitor",
+    "ReplicaExchangeAcquisitor",
+]

agox-3.10.1/agox/acquisitors/meta_acquisitor.py

@@ -0,0 +1,23 @@
+import numpy as np
+
+from agox.acquisitors.ABC_acquisitor import AcquisitorBaseClass
+
+
+class MetaInformationAcquisitor(AcquisitorBaseClass):
+    name = "MetaInformationAcquisitor"
+
+    def __init__(self, meta_key, mode="min", **kwargs):
+        super().__init__(**kwargs)
+        self.meta_key = meta_key
+        self.mode = mode
+
+        assert mode in ["max", "min"]  # Either maximize or minimize according to the meta key.
+
+    def calculate_acquisition_function(self, candidates):
+        sign = 1 if self.mode == "min" else -1
+        fitness = np.zeros(len(candidates))
+
+        for i, candidate in enumerate(candidates):
+            fitness[i] = sign * candidate.get_meta_information(self.meta_key)
+
+        return fitness

agox-3.10.1/agox/acquisitors/replica_exchange/__init__.py

@@ -0,0 +1,5 @@
+from .default import ReplicaExchangeAcquisitor
+
+__all__ = [
+    "ReplicaExchangeAcquisitor",
+]