emantis 1.2.2__tar.gz → 1.3.0__tar.gz

{emantis-1.2.2 → emantis-1.3.0}/PKG-INFO

@@ -1,27 +1,28 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: emantis
-Version: 1.2.2
+Version: 1.3.0
 Summary: A cosmological emulator for nonlinear large-scale structure formation studies in alternative dark energy and gravity theories.
 Keywords: cosmology,emulator,large-scale structure,dark energy,modified gravity
-Author-Email: =?utf-8?q?I=C3=B1igo_S=C3=A1ez_Casares?= <inigo.saez-casares@obspm.fr>
-License: GPL-3.0-or-later
+Author-Email: Iñigo Sáez-Casares <inigo.saez-casares@obspm.fr>
+License-Expression: GPL-3.0-or-later
 Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Classifier: Operating System :: OS Independent
 Classifier: Intended Audience :: Science/Research
 Classifier: Topic :: Scientific/Engineering :: Physics
 Project-URL: repository, https://gitlab.obspm.fr/e-mantis/e-mantis.git
 Project-URL: documentation, https://e-mantis.pages.obspm.fr/e-mantis/index.html
-Requires-Python: <3.15,>=3.10
+Requires-Python: >=3.10
 Requires-Dist: h5py<4.0,>=3.8
-Requires-Dist: scikit-learn<2,>=1
+Requires-Dist: scikit-learn<2,>=1.5
 Requires-Dist: numpy<3.0,>=1.24
 Requires-Dist: pydantic<3.0,>=2.6
 Requires-Dist: tomli<3,>=2; python_version < "3.11"
 Requires-Dist: joblib<2.0.0,>=1.3.2
+Requires-Dist: scipy<2,>=1.15
+Requires-Dist: threadpoolctl<4,>=3
 Description-Content-Type: text/x-rst
 
-|DOI|_ |PyPI|_ |release|_ |pipeline|_
+|DOI|_ |PyPI|_ |release|_ |pipeline|_ |coverage|_
 
 .. |DOI| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.7738362.svg
 .. _DOI: https://doi.org/10.5281/zenodo.7738362
@@ -35,6 +36,9 @@ Description-Content-Type: text/x-rst
 .. |pipeline| image:: https://gitlab.obspm.fr/e-mantis/e-mantis/badges/main/pipeline.svg
 .. _pipeline: https://gitlab.obspm.fr/e-mantis/e-mantis/-/commits/main
 
+.. |coverage| image:: https://gitlab.obspm.fr/e-mantis/e-mantis/badges/main/coverage.svg
+.. _coverage: https://gitlab.obspm.fr/e-mantis/e-mantis/-/commits/main
+
 e-MANTIS: Emulator for Multiple observable ANalysis in extended cosmological TheorIeS
 =====================================================================================
 
@@ -74,44 +78,12 @@ Or you can directly clone our public `repository <https://gitlab.obspm.fr/e-mant
 
 It requires a python version >= 3.10.
 
-Post-installation
------------------
-
-The emulators shipped with e-MANTIS need to be trained before they can provide predictions.
-This will be done automatically and on-the-fly the first time you use each emulator.
-
-Alternatively, we provide a CLI utility to train all emulators at once::
-
-  emantis-train
-
-This should not take more than a couple of minutes.
-
-The trained emulators are saved to disk, using the pickle protocol, ready for future usage.
-Major changes in the versions of python, e-MANTIS, or some of its main dependencies, such as numpy, scipy, or scikit-learn, might break the compatibility with previously trained emulators.
-In such case, the emulators will be retrained automatically on-the-fly.
-You can also retrain them manually using the CLI utility.
-
 Documentation and usage
 -----------------------
 
 The up-to-date documentation for this project (with code examples and a detailed API) is available `here <https://e-mantis.pages.obspm.fr/e-mantis>`_.
 
-Licence
+License
 -------
 
-Copyright (C) 2023 Iñigo Sáez-Casares
-
-inigo.saez-casares@obspm.fr
-
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License
-along with this program.  If not, see https://www.gnu.org/licenses/.
+e-MANTIS is distributed under the GNU General Public License v3.0 or later (GPL-3.0-or-later).

{emantis-1.2.2 → emantis-1.3.0}/README.rst

@@ -1,4 +1,4 @@
-|DOI|_ |PyPI|_ |release|_ |pipeline|_
+|DOI|_ |PyPI|_ |release|_ |pipeline|_ |coverage|_
 
 .. |DOI| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.7738362.svg
 .. _DOI: https://doi.org/10.5281/zenodo.7738362
@@ -12,6 +12,9 @@
 .. |pipeline| image:: https://gitlab.obspm.fr/e-mantis/e-mantis/badges/main/pipeline.svg
 .. _pipeline: https://gitlab.obspm.fr/e-mantis/e-mantis/-/commits/main
 
+.. |coverage| image:: https://gitlab.obspm.fr/e-mantis/e-mantis/badges/main/coverage.svg
+.. _coverage: https://gitlab.obspm.fr/e-mantis/e-mantis/-/commits/main
+
 e-MANTIS: Emulator for Multiple observable ANalysis in extended cosmological TheorIeS
 =====================================================================================
 
@@ -51,44 +54,12 @@ Or you can directly clone our public `repository <https://gitlab.obspm.fr/e-mant
 
 It requires a python version >= 3.10.
 
-Post-installation
------------------
-
-The emulators shipped with e-MANTIS need to be trained before they can provide predictions.
-This will be done automatically and on-the-fly the first time you use each emulator.
-
-Alternatively, we provide a CLI utility to train all emulators at once::
-
-  emantis-train
-
-This should not take more than a couple of minutes.
-
-The trained emulators are saved to disk, using the pickle protocol, ready for future usage.
-Major changes in the versions of python, e-MANTIS, or some of its main dependencies, such as numpy, scipy, or scikit-learn, might break the compatibility with previously trained emulators.
-In such case, the emulators will be retrained automatically on-the-fly.
-You can also retrain them manually using the CLI utility.
-
 Documentation and usage
 -----------------------
 
 The up-to-date documentation for this project (with code examples and a detailed API) is available `here <https://e-mantis.pages.obspm.fr/e-mantis>`_.
 
-Licence
+License
 -------
 
-Copyright (C) 2023 Iñigo Sáez-Casares
-
-inigo.saez-casares@obspm.fr
-
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License
-along with this program.  If not, see https://www.gnu.org/licenses/.
+e-MANTIS is distributed under the GNU General Public License v3.0 or later (GPL-3.0-or-later).

{emantis-1.2.2 → emantis-1.3.0}/pyproject.toml

@@ -1,23 +1,25 @@
 [project]
 authors = [
-    { name = "Iñigo Sáez Casares", email = "inigo.saez-casares@obspm.fr" },
+    { name = "Iñigo Sáez-Casares", email = "inigo.saez-casares@obspm.fr" },
 ]
-requires-python = "<3.15,>=3.10"
+license = "GPL-3.0-or-later"
+requires-python = ">=3.10"
 dependencies = [
     "h5py <4.0,>=3.8",
-    "scikit-learn <2,>=1",
+    "scikit-learn >=1.5,<2",
     "numpy <3.0,>=1.24",
     "pydantic <3.0,>=2.6",
     "tomli <3,>=2; python_version < '3.11'",
     "joblib <2.0.0,>=1.3.2",
+    "scipy>=1.15,<2",
+    "threadpoolctl <4,>=3",
 ]
 name = "emantis"
-version = "1.2.2"
+version = "1.3.0"
 description = "A cosmological emulator for nonlinear large-scale structure formation studies in alternative dark energy and gravity theories."
 readme = "README.rst"
 classifiers = [
     "Programming Language :: Python :: 3",
-    "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
     "Operating System :: OS Independent",
     "Intended Audience :: Science/Research",
     "Topic :: Scientific/Engineering :: Physics",
@@ -30,9 +32,6 @@ keywords = [
     "modified gravity",
 ]
 
-[project.license]
-text = "GPL-3.0-or-later"
-
 [project.urls]
 repository = "https://gitlab.obspm.fr/e-mantis/e-mantis.git"
 documentation = "https://e-mantis.pages.obspm.fr/e-mantis/index.html"
@@ -40,24 +39,6 @@ documentation = "https://e-mantis.pages.obspm.fr/e-mantis/index.html"
 [project.scripts]
 emantis-train = "emantis._cli:train_all_emulators"
 
-[tool.pdm.build]
-includes = []
-excludes = [
-    "src/emantis/data/emulator_storage*",
-]
-
-[tool.uv]
-default-groups = [
-    "dev",
-    "docs",
-]
-
-[tool.pytest.ini_options]
-addopts = "-vv --cov"
-
-[tool.pydocstyle]
-convention = "numpy"
-
 [build-system]
 requires = [
     "pdm-backend",
@@ -68,16 +49,39 @@ build-backend = "pdm.backend"
 dev = [
     "ipython",
     "matplotlib",
-    "jupyterlab <4.0,>=3.6",
-    "pytest>=8.4.1",
-    "pytest-cov>=6",
-    "pytest-pydocstyle>=2.4.0",
+    "jupyterlab",
     "pre-commit>=4.5.0",
 ]
 docs = [
-    "sphinx",
+    "sphinx>=7,<9",
     "sphinx-copybutton",
-    "sphinx-rtd-theme",
     "myst-nb",
     "sphinx-multiversion>=0.2.4",
+    "furo>=2025.9.25",
+]
+test = [
+    "pytest>=8.4.1",
+    "pytest-cov>=6",
+    "pytest-sugar>=1.0",
+]
+
+[tool.uv]
+default-groups = [
+    "dev",
+    "docs",
+    "test",
+]
+
+[tool.pytest.ini_options]
+addopts = "-vv --strict-markers"
+
+[tool.coverage.run]
+source = [
+    "emantis",
+]
+
+[tool.coverage.paths]
+source = [
+    "src/emantis",
+    "*/site-packages/emantis",
 ]

emantis-1.3.0/src/emantis/__init__.py

@@ -0,0 +1,37 @@
+"""Emulators of the large-scale structure formation in alternative cosmologies.
+
+e-MANTIS provides theoretical predictions for the nonlinear large-scale structure
+formation in alternative dark energy and gravity theories.
+It uses Gaussian processes to interpolate between the outputs
+of high resolution cosmological N-body simulations.
+It supports multiple cosmological models and observables,
+and is divided into modules, each one focusing on a type of observable.
+
+Available modules
+-----------------
+matter_power_spectrum
+    Emulators for the matter power spectrum.
+halo_mass_function
+    Emulator for the halo mass function.
+custom_emulators
+    Build, save and load your own emulators.
+powerspectrum_matter
+    Emulators for the matter power spectrum.
+    Deprecated, use matter_power_spectrum instead.
+"""
+
+from importlib.metadata import version
+
+from emantis import custom_emulators, halo_mass_function, matter_power_spectrum
+from emantis.custom_emulators import load_emulator
+from emantis.powerspectrum_matter import FofrBoost
+
+__version__ = version("emantis")
+
+__all__ = [
+    "FofrBoost",
+    "custom_emulators",
+    "halo_mass_function",
+    "load_emulator",
+    "matter_power_spectrum",
+]

emantis-1.3.0/src/emantis/_base.py

@@ -0,0 +1,355 @@
+"""Base classes of the e-MANTIS emulators."""
+
+import sys
+from collections.abc import Sequence
+
+import numpy as np
+import numpy.typing as npt
+
+from emantis import _utils_inputs
+
+
+class _BaseEmulator:
+    """A base emulator class meant to be inherited.
+
+    Parameters
+    ----------
+    params_range : dict or None, default=None
+        A dict. with the emulation range of each input parameter.
+        If ``None``, the emulator only accepts input parameters in the form of an array
+        and it will never check if the requested input parameters
+        are within the emulation range.
+        WARNING: the order of the parameters in the dict matters.
+    random_seed: int or None, default=None
+        The random seed passed to the random generators used during training.
+    n_jobs: int, default=1
+        Maximum number of independent processes used to fit the emulator
+        (training and cross-validation). A value of -1 uses all available cores.
+    name : str, default='e-MANTIS'
+        Name of the emulator, used as prefix of the verbose messages.
+    verbose : bool, default=True
+        If ``True``, print messages to the standard output
+        (e.g. when the emulator is trained or loaded).
+
+    Attributes
+    ----------
+    random_seed : int or None
+        The random seed passed to the random generators used during training.
+    n_jobs : int
+        Maximum number of independent processes used to fit the emulator
+        (see the `n_jobs` parameter).
+    verbose : bool
+        If ``True``, print messages to the standard output
+        (e.g. when the emulator is trained or loaded).
+    _name : str
+        Name of the emulator, used as prefix of the verbose messages.
+
+    """
+
+    def __init__(
+        self,
+        params_range: dict[str, dict[str, float]] | None = None,
+        random_seed: int | None = None,
+        n_jobs: int = 1,
+        name: str = "e-MANTIS",
+        verbose: bool = True,
+    ) -> None:
+        # Get params names and range.
+        self._params_range = params_range
+
+        # Set random seed.
+        self.random_seed = random_seed
+
+        # Number of jobs.
+        self.n_jobs = n_jobs
+
+        # Name, used as prefix of the verbose messages.
+        self._name = name
+
+        # Verbosity.
+        self.verbose = verbose
+
+    @property
+    def params_range(self) -> dict | None:
+        """Dict or None: The emulation range of each input parameter, if given."""
+        return self._params_range
+
+    def range(self, parameter: str) -> tuple[float, float]:
+        """Give the emulation range of an input parameter.
+
+        Parameters
+        ----------
+        parameter : str
+            The name of the parameter.
+
+        Returns
+        -------
+        min_value, max_value : float
+            The minimum and maximum of the emulation range.
+
+        Raises
+        ------
+        ValueError
+            If `parameter` is not an input parameter of this emulator.
+
+        """
+        if self.params_range is None:
+            raise ValueError(
+                f"Unknown variable: {parameter}.\n"
+                "Note: the params_range dict was not provided"
+                " at the initialization of this instance,"
+                " therefore the parameter names are not known."
+            )
+        if parameter not in self.params_range:
+            raise ValueError(f"Unknown variable: {parameter}.")
+        return (
+            self.params_range[parameter]["min_value"],
+            self.params_range[parameter]["max_value"],
+        )
+
+    def _print(self, message: str) -> None:
+        """Print a message prefixed by the emulator name, if verbose is ``True``.
+
+        Parameters
+        ----------
+        message : str
+            The message to print.
+
+        """
+        if self.verbose:
+            # Messages pending on stderr (e.g. the progress of joblib) come first,
+            # also where the two streams are shown separately (e.g. Jupyter).
+            sys.stderr.flush()
+            print(f"{self._name}: {message}", flush=True)
+
+    def _format_input_params_to_array(
+        self,
+        input_params: dict[str, float | list[float] | npt.NDArray] | npt.NDArray,
+    ) -> npt.NDArray:
+        """Convert the input parameters to a validated 2-D array.
+
+        An array of shape (n_params,) (one model) or (n_samples, n_params)
+        is reshaped to 2-D. If this instance has a `params_range`, the number
+        of columns and the range of each parameter are checked, the columns
+        being ordered as `params_range`.
+
+        A dict must have one entry per parameter of `params_range`, whose names
+        and ranges are checked. Each entry has either one value, or the same
+        number of values `n_samples` as every other entry with more than one value;
+        single values are repeated for all samples.
+
+        Parameters
+        ----------
+        input_params : dict or ndarray of shape (n_params,) or (n_samples, n_params)
+            The input parameters.
+
+        Returns
+        -------
+        params_array : ndarray of shape (n_samples, n_params)
+            Array containing the input parameters, where `n_params` is the number
+            of parameters and `n_samples` the number of inputs per parameter.
+
+        Raises
+        ------
+        TypeError
+            If `input_params` is a dict, but this instance was not initialized with
+            a `params_range` dict, or if it is neither a dict nor an array.
+        ValueError
+            If an array has more than two dimensions or the wrong number of columns,
+            or if the number of values in `input_params` for different
+            parameters is not compatible.
+
+        """
+        if isinstance(input_params, np.ndarray):
+            params_array = input_params
+
+            # Ensure correct array shape.
+            if params_array.ndim == 1:
+                params_array = params_array.reshape(1, -1)
+            elif params_array.ndim != 2:
+                raise ValueError(
+                    "Array `params` must have shape (n_params,) or"
+                    f" (n_samples, n_params), got shape {params_array.shape}."
+                )
+
+            # Check each parameter range if necessary.
+            if self.params_range is not None:
+                # Check number of parameters (columns).
+                if params_array.shape[1] != len(self.params_range):
+                    raise ValueError(
+                        f"Array `params` has {params_array.shape[1]} columns,"
+                        f" but this emulator expects {len(self.params_range)}"
+                        f" parameters, in this order: {list(self.params_range)}."
+                    )
+
+                # Loop over all parameters.
+                for i, param_name in enumerate(self.params_range):
+                    _utils_inputs.check_emulation_range(
+                        params_array[:, i],
+                        self.params_range[param_name]["min_value"],
+                        self.params_range[param_name]["max_value"],
+                        param_name,
+                    )
+
+        elif isinstance(input_params, dict):
+            if self.params_range is None:
+                raise TypeError(
+                    "This instance only accepts the 'params' argument"
+                    " in the form of an array, since the 'params_range' argument"
+                    " was not provided when instantiated."
+                )
+
+            # First check names (and range) of input parameters.
+            self._check_input_params_dict(input_params)
+
+            # Each parameter must have either 1 value or the same number
+            # of values n_samples as every other parameter with > 1 value.
+            arrays = {
+                param_name: _utils_inputs.format_input_to_1d_array(
+                    input_params[param_name], param_name
+                )
+                for param_name in input_params
+            }
+            n_values = {name: array.shape[0] for name, array in arrays.items()}
+            lengths = set(n_values.values()) - {1}
+            if len(lengths) > 1:
+                raise ValueError(
+                    "Input parameters must have either one value or the same"
+                    f" number of values. Got: {n_values}."
+                )
+            n_samples: int = lengths.pop() if lengths else 1
+
+            # Gather the parameters in an array, in the order of params_range.
+            # A single value is broadcast to all the samples.
+            params_array = np.zeros((n_samples, len(self.params_range)))
+            for i, param_name in enumerate(self.params_range):
+                params_array[:, i] = arrays[param_name]
+        else:
+            raise TypeError("Argument 'params' must be a dict or a ndarray.")
+
+        return params_array
+
+    def _check_input_params_dict(
+        self,
+        input_params_dict: dict[str, float | list[float] | npt.NDArray],
+        check_range: bool = True,
+    ) -> None:
+        """Check input parameter dict.
+
+        Check that the input parameters have valid names,
+        and that all the required parameters have been provided.
+
+        Can also check the range of the input parameters (see `required_params_range`).
+
+        Parameters
+        ----------
+        input_params_dict : dict
+            A dictionary with the input parameters.
+        check_range : bool, default=True
+            If ``True`` check that the input parameters are within
+            the allowed emulation range.
+
+        Raises
+        ------
+        TypeError
+            If this instance was not initialized with a `params_range` dict.
+        KeyError
+            If the keys of `input_params_dict` do not match
+            those of the attribute `params_range`.
+
+        """
+        if self.params_range is None:
+            raise TypeError(
+                "This instance only accepts the 'params' argument"
+                " in the form of an array, since the 'params_range' argument"
+                " was not provided when instantiated."
+            )
+
+        # Check that all the provided parameter names are valid.
+        for param in input_params_dict:
+            if param not in self.params_range:
+                raise KeyError(f"The provided parameter '{param}' is not supported.")
+
+        # Check that all the required parameters
+        # have been provided.
+        for param in self.params_range:
+            if param not in input_params_dict:
+                raise KeyError(f"The parameter '{param}' is missing.")
+
+        # Check emulation range.
+        if check_range:
+            # Loop over input parameters.
+            for param_name in input_params_dict:
+                _utils_inputs.check_emulation_range(
+                    input_params_dict[param_name],
+                    self.params_range[param_name]["min_value"],
+                    self.params_range[param_name]["max_value"],
+                    param_name,
+                )
+
+
+class _CompositeEmulator(_BaseEmulator):
+    """An emulator made of other emulators, its inner emulators.
+
+    The runtime options `random_seed`, `n_jobs` and `verbose` are those of the
+    inner emulators: the getters read the first one, and the setters set all of them.
+    Nothing is stored here. A subclass defines :py:meth:`_inner_emulators`,
+    and creates its inner emulators before calling ``super().__init__``,
+    because the base class sets the runtime options.
+    """
+
+    def _inner_emulators(self) -> Sequence[_BaseEmulator]:
+        """Return the inner emulators.
+
+        Returns
+        -------
+        emulators : sequence of _BaseEmulator
+            The inner emulators. The first one gives the values of the options.
+
+        Raises
+        ------
+        NotImplementedError
+            Always: subclasses define it.
+
+        """
+        raise NotImplementedError
+
+    @property
+    def random_seed(self) -> int | None:
+        """Int or None: The random seed passed to the random generators of training.
+
+        Setting it sets it on every inner emulator.
+        """
+        return self._inner_emulators()[0].random_seed
+
+    @random_seed.setter
+    def random_seed(self, value: int | None) -> None:
+        for emulator in self._inner_emulators():
+            emulator.random_seed = value
+
+    @property
+    def n_jobs(self) -> int:
+        """int: Maximum number of independent processes used to fit the emulator.
+
+        Used for training and cross-validation. A value of -1 uses all available cores.
+        Setting it sets it on every inner emulator.
+        """
+        return self._inner_emulators()[0].n_jobs
+
+    @n_jobs.setter
+    def n_jobs(self, value: int) -> None:
+        for emulator in self._inner_emulators():
+            emulator.n_jobs = value
+
+    @property
+    def verbose(self) -> bool:
+        """bool: If ``True``, print messages to the standard output.
+
+        Setting it sets it on every inner emulator.
+        """
+        return self._inner_emulators()[0].verbose
+
+    @verbose.setter
+    def verbose(self, value: bool) -> None:
+        for emulator in self._inner_emulators():
+            emulator.verbose = value