axsdb 0.0.2__py3-none-any.whl

axsdb/error.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+import enum
+import warnings
+from collections.abc import Mapping
+
+import attrs
+
+# ------------------------------------------------------------------------------
+#                                   Exceptions
+# ------------------------------------------------------------------------------
+
+
+class DataError(Exception):
+    """Raised when encountering issues with data."""
+
+    pass
+
+
+class InterpolationError(Exception):
+    """Raised when encountering errors during interpolation."""
+
+    pass
+
+
+# ------------------------------------------------------------------------------
+#                           Error handling components
+# ------------------------------------------------------------------------------
+
+
+class ErrorHandlingAction(enum.Enum):
+    """
+    Error handling action descriptors.
+    """
+
+    IGNORE = "ignore"  #: Ignore the error.
+    RAISE = "raise"  #: Raise the error.
+    WARN = "warn"  #: Emit a warning.
+
+
+@attrs.define
+class ErrorHandlingPolicy:
+    """
+    Error handling policy.
+
+    Parameters
+    ----------
+    missing : ErrorHandlingAction
+        Action to perform when a variable is missing.
+
+    scalar : ErrorHandlingAction
+        Action to perform when a dimension is scalar.
+
+    bounds : ErrorHandlingAction
+        Action to perform when an off-bounds query is made.
+    """
+
+    missing: ErrorHandlingAction
+    scalar: ErrorHandlingAction
+    bounds: ErrorHandlingAction
+
+    @classmethod
+    def convert(cls, value):
+        """
+        Convert a value to an :class:`.ErrorHandlingPolicy`.
+
+        Parameters
+        ----------
+        value
+            Value to convert. Dictionaries values are tentatively converted to
+            :class:`.ErrorHandlingAction`, then passed as keyword arguments to
+            the constructor.
+
+        Returns
+        -------
+        ErrorHandlingPolicy
+        """
+        if isinstance(value, Mapping):
+            kwargs = {k: ErrorHandlingAction(v) for k, v in value.items()}
+            return cls(**kwargs)
+        else:
+            return value
+
+
+@attrs.define
+class ErrorHandlingConfiguration:
+    """
+    Error handling configuration.
+
+    Parameters
+    ----------
+    x : ErrorHandlingPolicy
+        Error handling policy for species concentrations.
+
+    p : ErrorHandlingPolicy
+        Error handling policy for pressure.
+
+    t : ErrorHandlingPolicy
+        Error handling policy for temperature.
+    """
+
+    x: ErrorHandlingPolicy = attrs.field(converter=ErrorHandlingPolicy.convert)
+    p: ErrorHandlingPolicy = attrs.field(converter=ErrorHandlingPolicy.convert)
+    t: ErrorHandlingPolicy = attrs.field(converter=ErrorHandlingPolicy.convert)
+
+    @classmethod
+    def convert(cls, value):
+        """
+        Convert a value to an :class:`.ErrorHandlingConfiguration`.
+
+        Parameters
+        ----------
+        value
+            Value to convert. Dictionaries values are passed as keyword arguments
+            to the constructor.
+
+        Returns
+        -------
+        ErrorHandlingConfiguration
+        """
+        if isinstance(value, Mapping):
+            return cls(**value)
+        else:
+            return value
+
+
+def handle_error(error: InterpolationError, action: ErrorHandlingAction):
+    """
+    Apply an error handling policy.
+
+    Parameters
+    ----------
+    error : .InterpolationError
+        The error that is handled.
+
+    action : ErrorHandlingAction
+        If ``IGNORE``, do nothing; if ``WARN``, emit a warning; if ``RAISE``,
+        raise the error.
+    """
+    if action is ErrorHandlingAction.IGNORE:
+        return
+
+    if action is ErrorHandlingAction.WARN:
+        warnings.warn(str(error), UserWarning)
+        return
+
+    if action is ErrorHandlingAction.RAISE:
+        raise error
+
+    raise NotImplementedError
+
+
+#: Global default error handling configuration
+_DEFAULT_ERROR_HANDLING_CONFIG: ErrorHandlingConfiguration | None = None
+
+
+def set_error_handling_config(value: Mapping | ErrorHandlingConfiguration) -> None:
+    """
+    Set the global default error handling configuration.
+
+    Parameters
+    ----------
+    value : Mapping | ErrorHandlingConfiguration
+        Error handling configuration.
+
+    Raises
+    ------
+    ValueError
+        If ``value`` cannot be converted to an :class:`.ErrorHandlingConfiguration`.
+    """
+    global _DEFAULT_ERROR_HANDLING_CONFIG
+    value = ErrorHandlingConfiguration.convert(value)
+    if not isinstance(value, ErrorHandlingConfiguration):
+        raise ValueError("could not convert value to ErrorHandlingConfiguration")
+    _DEFAULT_ERROR_HANDLING_CONFIG = value
+
+
+def get_error_handling_config() -> ErrorHandlingConfiguration:
+    """
+    Retrieve the current global default error handling configuration.
+
+    Returns
+    -------
+    ErrorHandlingConfiguration
+    """
+    global _DEFAULT_ERROR_HANDLING_CONFIG
+    if _DEFAULT_ERROR_HANDLING_CONFIG is None:  # No config yet: assign a default
+        set_error_handling_config(
+            {
+                # This default configuration ignores bound errors on pressure and temperature
+                # variables because this usually occurs at high altitude, where the absorption
+                # coefficient is very low and can be safely forced to 0.
+                "p": {"missing": "raise", "scalar": "raise", "bounds": "ignore"},
+                "t": {"missing": "raise", "scalar": "raise", "bounds": "ignore"},
+                # Ignore missing molecule coordinates, raise on bound error.
+                "x": {"missing": "ignore", "scalar": "ignore", "bounds": "raise"},
+            }
+        )
+
+    return _DEFAULT_ERROR_HANDLING_CONFIG

axsdb/factory.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+from pathlib import Path
+
+import attrs
+from typing import Callable, Type, TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from axsdb import AbsorptionDatabase
+
+    AbsorptionDatabaseT = Type[AbsorptionDatabase]
+
+
+@attrs.define
+class RegistryEntry:
+    name: str = attrs.field()
+    cls: AbsorptionDatabaseT = attrs.field(repr=False)
+    _path: Path | Callable = attrs.field(repr=False)
+    kwargs: dict[str, Any] = attrs.field(repr=False, factory=dict)
+
+    def path(self):
+        return self._path() if callable(self._path) else self._path
+
+
+@attrs.define
+class AbsorptionDatabaseFactory:
+    """
+    This factory instantiates :class:`.AbsorptionDatabase` subclasses given a
+    name. Internally, a registry maps registered names to a matching database
+    type, a path where its data is located, and default loading options.
+
+    Examples
+    --------
+    Initialize a factory instance:
+
+    >>> factory = AbsorptionDatabaseFactory()
+
+    Register a new database:
+
+    >>> factory.register(
+    ...     name="nanockd", cls=CKDAbsorptionDatabase, path="~/Downloads/nanockd"
+    ... )
+
+    Instantiate a database:
+
+    >>> factory.create("nanockd")
+    """
+
+    _registry: dict[str, RegistryEntry] = attrs.field(factory=dict, init=False)
+
+    def register(
+        self,
+        name: str,
+        cls: AbsorptionDatabaseT,
+        path: Path | Callable,
+        kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        """
+        Register a new database to the factory.
+
+        Parameters
+        ----------
+        name : str
+            A unique identifier for this entry.
+
+        cls : type
+            The matching database type.
+
+        path : path-like or callable
+            The path to the directory where database data are located. If the
+            name is dynamic (*e.g.* resolved by Eradiate's file resolver), a
+            callable with signature ``f() -> Path | str`` can be passed.
+
+        kwargs : dict, optional
+            Default loading options passed to the constructor when instantiating
+            this database.
+
+        Examples
+        --------
+        Simplest registration pattern:
+
+        >>> factory.register(
+        ...     name="nanomono", cls=MonoAbsorptionDatabase, path="~/Data/nanomono"
+        ... )
+
+        Get path dynamically from a callable:
+
+        >>> def path():
+        ...     return "~/Data/nanomono"
+        >>> factory.register(
+        ...     name="nanomono",
+        ...     cls=MonoAbsorptionDatabase,
+        ...     path=path,
+        ... )
+
+        Add default keyword arguments:
+
+        >>> factory.register(
+        ...     name="nanomono",
+        ...     cls=MonoAbsorptionDatabase,
+        ...     path="~/Data/nanomono",
+        ...     kwargs={"lazy": True},
+        ... )
+
+        """
+        if kwargs is None:
+            kwargs = {}
+        self._registry[name] = RegistryEntry(
+            name=name, cls=cls, path=path, kwargs=kwargs
+        )
+
+    def create(self, name: str, **kwargs) -> AbsorptionDatabase:
+        """
+        Instantiate a database given its name using the
+        :meth:`~.AbsorptionDatabase.from_directory` constructor.
+
+        Parameters
+        ----------
+        name : str
+            Name of a registered databased.
+
+        kwargs
+            Optional keyword arguments passed to the database constructor. These
+            settings will override registered defaults.
+
+        Returns
+        -------
+        AbsorptionDatabase
+            Created database instance.
+        """
+        entry = self._registry[name]
+        cls = entry.cls
+        path = entry.path()
+        kwargs = {**entry.kwargs, **kwargs}
+
+        return cls.from_directory(path, **kwargs)

axsdb/typing.py

@@ -0,0 +1,4 @@
+import os
+from typing import TypeVar
+
+PathLike = TypeVar("PathLike", str, bytes, os.PathLike)

axsdb/units.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from typing import Any
+import xarray as xr
+import pint
+
+#: An alias to Pint's application registry.
+ureg = pint.get_application_registry()
+
+
+def ensure_units(
+    value: Any, default_units: pint.Unit, convert: bool = False
+) -> pint.Quantity:
+    """
+    Ensure that a value is wrapped in a Pint quantity container.
+
+    Parameters
+    ----------
+    value
+        Checked value.
+
+    default_units : pint.Unit
+        Units to use to initialize the :class:`pint.Quantity` if ``value`` is
+        not a :class:`pint.Quantity`.
+
+    convert : bool, default: False
+        If ``True``, ``value`` will also be converted to ``default_units`` if it is a
+        :class:`pint.Quantity`.
+
+    Returns
+    -------
+    Converted ``value``.
+    """
+    if isinstance(value, pint.Quantity):
+        if convert:
+            return value.to(default_units)
+        else:
+            return value
+    else:
+        return value * default_units
+
+
+def xarray_to_quantity(da: xr.DataArray) -> pint.Quantity:
+    """
+    Converts a :class:`~xarray.DataArray` to a :class:`~pint.Quantity`.
+    The array's ``attrs`` metadata mapping must contain a ``units`` field.
+
+    Parameters
+    ----------
+    da : DataArray
+        :class:`~xarray.DataArray` instance which will be converted.
+
+    Returns
+    -------
+    quantity
+        The corresponding Pint quantity.
+
+    Raises
+    ------
+    ValueError
+        If array attributes do not contain a ``units`` field.
+
+    Notes
+    -----
+    This function can also be used on coordinate variables.
+    """
+    try:
+        units = da.attrs["units"]
+    except KeyError as e:
+        raise ValueError("this DataArray has no 'units' attribute field") from e
+
+    return ureg.Quantity(da.values, units)

axsdb-0.0.2.dist-info/METADATA

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: axsdb
+Version: 0.0.2
+Summary: An absorption database reader for the Eradiate radiative transfer model.
+Author-email: Vincent Leroy <vincent.leroy@rayference.eu>
+Requires-Python: >=3.9
+Requires-Dist: attrs
+Requires-Dist: cachetools
+Requires-Dist: netcdf4
+Requires-Dist: pint
+Requires-Dist: scipy
+Requires-Dist: typer
+Requires-Dist: xarray
+Description-Content-Type: text/markdown
+
+# AxsDB — The Eradiate Absorption Cross-section Database Interface
+
+[![PyPI version](https://img.shields.io/pypi/v/axsdb?color=blue)](https://pypi.org/project/axsdb)
+[![GitHub Workflow Status (branch)](https://img.shields.io/github/actions/workflow/status/eradiate/axsdb/ci.yml?branch=main)](https://github.com/eradiate/axsdb/actions/workflows/ci.yml)
+[![Documentation Status](https://img.shields.io/readthedocs/axsdb)](https://axsdb.readthedocs.io)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+This library provides an interface to read and
+query [Eradiate](https://eradiate.eu)'s absorption databases.
+
+## License
+
+The Eradiate Absorption Database Reader is distributed under the terms of the
+[GNU Lesser General Public License v3.0](https://choosealicense.com/licenses/lgpl-3.0/).

axsdb-0.0.2.dist-info/RECORD

@@ -0,0 +1,13 @@
+axsdb/__init__.py,sha256=9-EMYK0zJ6dTDZxRvqxpoAwZYER6xHjhNRROhCDPqEs,666
+axsdb/_version.py,sha256=zpfzURzIlh9ajjpvYv4uvkfd404RwJGzy_drTalmMm0,163
+axsdb/cli.py,sha256=UUtmlrS1Y0y6TrXDZtjDY2xBeqPlH_RRSDdRQjv9_b4,1689
+axsdb/core.py,sha256=_FXP-gio8yTGvYEuiOjWCizi6OV8r9WdI0UNo9Kqk3U,31343
+axsdb/error.py,sha256=dmdurgFPkZxyutyWnYb85ddt7TV3jFw1etLln14boPQ,5621
+axsdb/factory.py,sha256=Pr8kxQ51hgQY8wBCuMy7sarHT5ORmaRYhFWiu5styhk,3710
+axsdb/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+axsdb/typing.py,sha256=Aol4ouIrfrUs-HBBgblW6Iv-xJDSpFe1RxWCQj8QDFs,94
+axsdb/units.py,sha256=XxbcC-dXiXd8ZkB3cBtd3NTT8zSEd1g8FGQUr5-nrhQ,1762
+axsdb-0.0.2.dist-info/METADATA,sha256=CN4Ek0lbULDF88DFdZnXDni-oquWTsGdAkU6L_TQ-JQ,1457
+axsdb-0.0.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+axsdb-0.0.2.dist-info/entry_points.txt,sha256=4OnXeexRQs2Bl3T4F_jwijW6hPb6vOsIcQAECTsnHUE,41
+axsdb-0.0.2.dist-info/RECORD,,

axsdb-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

axsdb-0.0.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+axsdb = axsdb.cli:main