agox 3.7.0rc1__tar.gz → 3.9.0__tar.gz

agox-3.9.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.1
+Name: agox
+Version: 3.9.0
+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
+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
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: numpy<2
+Requires-Dist: scipy
+Requires-Dist: ase
+Requires-Dist: matplotlib
+Requires-Dist: cymem
+Requires-Dist: scikit-learn
+Requires-Dist: h5py
+Requires-Dist: matscipy
+Requires-Dist: importlib-resources>1.3; python_version < "3.9"
+Requires-Dist: dscribe>=2.0.0
+Requires-Dist: nbformat
+Requires-Dist: typing_extensions
+Requires-Dist: jax
+Requires-Dist: jaxlib
+Requires-Dist: ray
+Requires-Dist: rich-click>=1.8.3
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-mock; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: furo; extra == "docs"
+Requires-Dist: sphinx-autoapi; extra == "docs"
+Requires-Dist: sphinx-copybutton; extra == "docs"
+Requires-Dist: sphinx-tabs; extra == "docs"
+Provides-Extra: all
+Requires-Dist: agox[docs,test]; extra == "all"
+
+# Atomistic Global Optimization X (AGOX)
+
+![logo](docs/source/logos/logo-carbon.gif)
+
+
+AGOX is a package for global optimization of atomic system using e.g. the energy 
+calculated from density functional theory as the objective function. AGOX interfaces 
+with the Atomistic Simulation Environment (ASE) and as such supports any of 
+calculators in ASE as objectives for optimization. 
+
+AGOX is built to be flexible, consisting of modules that can be put together to 
+create an optimization algorithm, from simple random searches to Bayesian searches 
+guided by a surrogate model and many more. 
+
+Check out the documentation at 
+
+https://agox.gitlab.io/agox/
+
+# Contributions & Issues 
+
+Feel free to make a fork and submit a merge request! 
+
+If you have an issue or a question please post it on the issue board! 
+
+# Authors 
+
+The main AGOX framework has been written by 
+* Mads-Peter Verner Christiansen
+* Nikolaj Rønne
+* Bjørk Hammer
+
+with inspiration and help from current and previous members of the Hammer group at Aarhus University, Denmark.
+Parts of the code have been contributed by
+
+* Andreas Slavensky (Complementary Energy Generator)
+
+# License
+
+AGOX is released under the GPLv3 license. 
+
+

agox-3.9.0/README.md

@@ -0,0 +1,41 @@
+# Atomistic Global Optimization X (AGOX)
+
+![logo](docs/source/logos/logo-carbon.gif)
+
+
+AGOX is a package for global optimization of atomic system using e.g. the energy 
+calculated from density functional theory as the objective function. AGOX interfaces 
+with the Atomistic Simulation Environment (ASE) and as such supports any of 
+calculators in ASE as objectives for optimization. 
+
+AGOX is built to be flexible, consisting of modules that can be put together to 
+create an optimization algorithm, from simple random searches to Bayesian searches 
+guided by a surrogate model and many more. 
+
+Check out the documentation at 
+
+https://agox.gitlab.io/agox/
+
+# Contributions & Issues 
+
+Feel free to make a fork and submit a merge request! 
+
+If you have an issue or a question please post it on the issue board! 
+
+# Authors 
+
+The main AGOX framework has been written by 
+* Mads-Peter Verner Christiansen
+* Nikolaj Rønne
+* Bjørk Hammer
+
+with inspiration and help from current and previous members of the Hammer group at Aarhus University, Denmark.
+Parts of the code have been contributed by
+
+* Andreas Slavensky (Complementary Energy Generator)
+
+# License
+
+AGOX is released under the GPLv3 license. 
+
+

agox-3.9.0/agox/__init__.py

@@ -0,0 +1,24 @@
+import os
+
+# Versioning
+__version_info__ = (3, 9, 0)
+__version__ = "{}.{}.{}".format(*__version_info__)
+
+# Extra versioning - Mainly for managing Pypi releases.
+version_extra = os.environ.get("AGOX_VERSION_EXTRA", None)
+if version_extra:
+    __version__ = "{}{}".format(__version__, version_extra)
+
+try:  # When installing the package we don't need to actually import.
+    from agox.module import Module  # noqa
+    from agox.observer import Observer
+    from agox.writer import Writer
+    from agox.cli.main import main
+    from agox.main.state import State
+    from agox.main.agox import AGOX
+
+    __all__ = ["Module", "Observer", "Writer", "State", "AGOX", "__version__", "main"]
+
+except ImportError as e:
+    print(e)
+    pass

agox-3.9.0/agox/acquisitors/ABC_acquisitor.py

@@ -0,0 +1,207 @@
+from abc import ABC, abstractmethod
+
+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=4,
+        gets={"get_key": "candidates"},
+        sets={"set_key": "prioritized_candidates"},
+        surname="",
+        skip_function=None,
+    ):
+        Observer.__init__(self, gets=gets, sets=sets, order=order, surname=surname)
+        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.9.0/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.9.0/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.9.0/agox/acquisitors/LCB_penalty.py

@@ -0,0 +1,129 @@
+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.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, _) -> 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) :]
+
+        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.9.0/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