imas-python 0.1.dev1618__py3-none-any.whl

imas/ids_coordinates.py

@@ -0,0 +1,400 @@
+# This file is part of imas-python.
+# You should have received the imas-python LICENSE file with this project.
+"""Logic for interpreting coordinates in an IDS.
+"""
+
+import logging
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union
+
+import numpy as np
+
+from imas.exception import CoordinateError, CoordinateLookupError, ValidationError
+from imas.ids_data_type import IDSDataType
+from imas.ids_defs import EMPTY_FLOAT
+from imas.ids_defs import IDS_TIME_MODE_HETEROGENEOUS as HETEROGENEOUS_TIME
+from imas.ids_defs import IDS_TIME_MODE_HOMOGENEOUS as HOMOGENEOUS_TIME
+from imas.ids_path import IDSPath
+
+if TYPE_CHECKING:  # Prevent circular imports
+    from imas.ids_base import IDSBase
+    from imas.ids_primitive import IDSPrimitive
+
+logger = logging.getLogger(__name__)
+
+
+class IDSCoordinate:
+    """Class representing a coordinate reference from the DD.
+
+    Example:
+        - Coordinates are an index:
+
+          - ``1...N``: any number of items allowed
+          - ``1...3``: max 3 items allowed
+
+        - Coordinates refer to other quantities:
+
+          - ``time``: refers to the ``time`` quantity in the IDS toplevel
+          - ``profiles_1d(itime)/time``: refers to the ``time`` quantity in the
+            ``profiles_1d`` IDSStructArray with (dummy) index itime
+
+        - Coordinates specify alternatives:
+
+          - ``distribution(i1)/profiles_2d(itime)/grid/r OR
+            distribution(i1)/profiles_2d(itime)/grid/rho_tor_norm``: coordinate can
+            be ``r`` or ``rho_tor_norm`` (only one may be filled)
+          - ``coherent_wave(i1)/beam_tracing(itime)/beam(i2)/length OR 1...1``: either
+            use ``length`` as coordinate, or this dimension must have size one.
+    """
+
+    _cache: Dict[str, "IDSCoordinate"] = {}
+
+    def __new__(cls, coordinate_spec: str) -> "IDSCoordinate":
+        if coordinate_spec not in cls._cache:
+            cls._cache[coordinate_spec] = super().__new__(cls)
+        return cls._cache[coordinate_spec]
+
+    def __init__(self, coordinate_spec: str) -> None:
+        if hasattr(self, "_init_done"):
+            return  # Already initialized, __new__ returned from cache
+        self._coordinate_spec = coordinate_spec
+        self.size: Optional[int] = None
+        """Exact size of this dimension. For example, 2 when coordinate = 1...2."""
+
+        refs: List[IDSPath] = []
+        specs = coordinate_spec.split(" OR ")
+        for spec in specs:
+            if spec.startswith("1..."):
+                if spec != "1...N":
+                    try:
+                        self.size = int(spec[4:])
+                    except ValueError:
+                        logger.debug(
+                            f"Ignoring invalid coordinate specifier {spec}",
+                            exc_info=True,
+                        )
+            elif spec.startswith("IDS:"):
+                pass  # Coordinate is in another IDS, we don't handle that
+            elif spec:
+                try:
+                    refs.append(IDSPath(spec))
+                except ValueError:
+                    logger.debug(
+                        f"Ignoring invalid coordinate specifier {spec}", exc_info=True
+                    )
+        self.references: "tuple[IDSPath]" = tuple(refs)
+        """A tuple paths that this coordinate refers to.
+        """
+
+        num_rules = len(self.references) + (self.size is not None)
+        self.has_validation: bool = num_rules > 0
+        """True iff this coordinate specifies a validation rule."""
+        self.has_alternatives: bool = num_rules > 1
+        """True iff exclusive alternative coordinates are specified."""
+        self.is_time_coordinate: bool = any(ref.is_time_path for ref in self.references)
+        """True iff this coordinate refers to ``time``."""
+
+        # Prevent accidentally modifying attributes
+        self._init_done = True
+
+    def __setattr__(self, name: str, value: Any):
+        if hasattr(self, "_init_done"):
+            raise RuntimeError("Cannot set attribute: IDSCoordinate is read-only.")
+        super().__setattr__(name, value)
+
+    def __str__(self) -> str:
+        return self._coordinate_spec
+
+    def __repr__(self) -> str:
+        return f"IDSCoordinate({self._coordinate_spec!r})"
+
+    def __hash__(self) -> int:
+        """IDSCoordinate objects are immutable, we can be used e.g. as dict key."""
+        return hash(self._coordinate_spec)
+
+    def format_refs(self, element: "IDSBase") -> str:
+        """Return a comma-separated list of paths representing self.references.
+
+        Useful when constructing error messages to users.
+        """
+        ref_paths = []
+        for ref in self.references:
+            try:
+                ref_paths.append(ref.goto(element)._path)
+            except (ValueError, AttributeError, LookupError):
+                ref_paths.append(str(ref))
+        return ", ".join(f"`{ref}`" for ref in ref_paths)
+
+
+def _goto(path: IDSPath, element: "IDSBase") -> "IDSPrimitive":
+    """Wrapper around IDSPath.goto to raise more meaningful errors."""
+    try:
+        return path.goto(element)
+    except (ValueError, AttributeError) as exc:
+        raise RuntimeError(
+            f"The data dictionary coordinate definition '{path}' cannot be found: {exc}"
+        ) from None
+
+
+class IDSCoordinates:
+    """Class representing coordinates of an IDSStructArray or IDSPrimitive.
+
+    Can be used to automatically retrieve coordinate values via the indexing operator.
+
+    Example:
+        >>> import imas
+        >>> core_profiles = imas.IDSFactory().core_profiles()
+        >>> core_profiles.ids_properties.homogeneous_time = \\
+        ...     imas.ids_defs.IDS_TIME_MODE_HOMOGENEOUS
+        >>> core_profiles.profiles_1d.coordinates[0]
+        IDSNumericArray("/core_profiles/time", array([], dtype=float64))
+    """
+
+    __slots__ = ["_node"]
+
+    def __init__(self, node: "IDSBase") -> None:
+        self._node = node
+
+    def __repr__(self) -> str:
+        coordinates = []
+        for i in range(len(self)):
+            coor_str = f"\n  {i}: '{self._node.metadata.coordinates[i]}'"
+            same_as = self._node.metadata.coordinates_same_as[i]
+            if same_as.references:
+                coor_str += f" (same as '{same_as}')"
+            coordinates.append(coor_str)
+        return f"<IDSCoordinates of '{self._node._path}'>{''.join(coordinates)}"
+
+    def __len__(self) -> int:
+        """Number of coordinates is equal to the dimension of the bound IDS node."""
+        return self._node.metadata.ndim
+
+    def __getitem__(self, key: int) -> Union["IDSPrimitive", np.ndarray]:
+        """Get the coordinate of the given dimension.
+
+        When the coordinate is an index (e.g. 1...N) this will return a numpy arange
+        with the same size as the data currently has in that dimension.
+
+        When one coordinate path is defined in the DD, the corresponding IDSPrimitive
+        object is returned.
+
+        When multiple coordinate paths are defined, the one that is set is returned. A
+        ValueError is raised when multiple or none are defined.
+        """
+        coordinate = self._node.metadata.coordinates[key]
+        if not coordinate.references:
+            return np.arange(self._node.shape[key])
+        coordinate_path: Optional[IDSPath] = None
+        # Time is a special coordinate:
+        if coordinate.is_time_coordinate:
+            time_mode = self._node._time_mode
+            if time_mode == HOMOGENEOUS_TIME:
+                coordinate_path = IDSPath("time")
+            elif time_mode == HETEROGENEOUS_TIME:
+                # Time coordinates are guaranteed to be unique (no alternatives)
+                coordinate_path = coordinate.references[0]
+            else:
+                raise ValueError(
+                    "Invalid IDS time mode: ids_properties/homogeneous_time is "
+                    f"{time_mode}, was expecting {HETEROGENEOUS_TIME} or "
+                    f"{HOMOGENEOUS_TIME}."
+                )
+        elif not coordinate.has_alternatives:
+            coordinate_path = coordinate.references[0]
+
+        # Check if the coordinate is inside the AoS
+        if coordinate_path is not None:
+            if self._node.metadata.data_type is IDSDataType.STRUCT_ARRAY:
+                if self._node.metadata.path.is_ancestor_of(coordinate_path):
+                    # Create a numpy array with the contents of all elements in the AoS
+                    # TODO: move this to IDSPath?
+                    data = [_goto(coordinate_path, ele).value for ele in self._node]
+                    return np.array(data)
+            coordinate_node = _goto(coordinate_path, self._node)
+            if not coordinate_node.metadata.alternative_coordinates:
+                return coordinate_node
+
+            # This coordinate has alternatives, check which are set
+            nonzero_alternatives = [coordinate_node] if len(coordinate_node) > 0 else []
+            for alternative_path in coordinate_node.metadata.alternative_coordinates:
+                alternative_node = alternative_path.goto(coordinate_node)
+                if len(alternative_node) > 0:
+                    nonzero_alternatives.append(alternative_node)
+            if not nonzero_alternatives:
+                # None of the coordinates are set, return the primary coordinate
+                return coordinate_node
+            # Check if the lengths of all nonzero alternatives agree
+            if len(set(map(len, nonzero_alternatives))) != 1:
+                sizes = "\n".join(
+                    f"    `{alt._path}` has size {len(alt)}"
+                    for alt in nonzero_alternatives
+                )
+                raise CoordinateLookupError(
+                    f"Element `{self._node._path}` has "
+                    "multiple alternative coordinates set, but they don't have "
+                    f"matching sizes:\n{sizes}"
+                )
+            if len(nonzero_alternatives) > 1:
+                logger.info("Multiple alternative coordinates are set, using the first")
+            return nonzero_alternatives[0]
+
+        # Handle alternative coordinates, currently (DD 3.38.1) the `coordinate in
+        # structure` logic is not applicable for these cases:
+        refs = [_goto(ref, self._node) for ref in coordinate.references]
+        ref_is_defined = [len(ref.value) > 0 for ref in refs]
+        if sum(ref_is_defined) == 0:
+            if coordinate.size is not None:
+                # alternatively we can be an index
+                return np.arange(self._node.shape[key])
+            coordinate_refs = coordinate.format_refs(self._node)
+            if ", " in coordinate_refs:
+                coordinate_refs = "any of " + coordinate_refs
+            raise CoordinateLookupError(
+                f"Element `{self._node._path}` must have its coordinate in dimension "
+                f"{key + 1} ({coordinate_refs}) filled."
+            )
+
+        if sum(ref_is_defined) == 1:
+            for i in range(len(refs)):
+                if ref_is_defined[i]:
+                    return refs[i]
+
+        raise CoordinateLookupError(
+            f"Element `{self._node._path}` must have "
+            f"exactly one of its coordinates ({coordinate.format_refs(self._node)}) "
+            "set, but multiple are set."
+        )
+
+    @property
+    def time_index(self) -> Optional[int]:
+        """Get the index of the time coordinate
+
+        Returns:
+            The index of the time coordinate, or None if there is no time coordinate.
+        """
+        for i, coor in enumerate(self._node.metadata.coordinates):
+            if coor.is_time_coordinate:
+                return i
+        return None
+
+    def _validate(self):
+        """Coordinate validation checks.
+
+        See also:
+            :py:meth:`imas.ids_toplevel.IDSToplevel.validate`.
+        """
+        node = self._node
+        shape = node.shape
+        metadata = node.metadata
+
+        # Validate coordinate
+        for dim in range(metadata.ndim):
+            coordinate = metadata.coordinates[dim]
+            if not coordinate.has_validation:
+                continue  # Nothing to validate
+
+            # Validate size
+            if coordinate.size:
+                if shape[dim] == coordinate.size:
+                    continue  # Correct size
+                elif not coordinate.has_alternatives:
+                    # If the coordinate has alternatives (see test case
+                    # test_validate_reference_or_fixed_size) we continue checking the
+                    # references below.
+                    # If only size is specified, the dimension is not the correct size:
+                    raise CoordinateError(node, dim, coordinate.size, None)
+
+            # Validate references
+            assert coordinate.references
+            with self._capture_goto_errors(dim, coordinate) as captured:
+                other_element = self[dim]
+            if captured:
+                continue  # Ignored error, continue to next dimension
+
+            if isinstance(other_element, np.ndarray):
+                if coordinate.size:
+                    # other_element may be a numpy array when coordinate = "path OR
+                    # 1...1" and path is unset
+                    raise CoordinateError(node, dim, coordinate.size, None)
+                # Otherwise, this is a dynamic AoS with heterogeneous_time, verify that
+                # none of the values are EMPTY_FLOAT
+                if EMPTY_FLOAT in other_element:
+                    (n,) = np.where(other_element == EMPTY_FLOAT)
+                    raise ValidationError(
+                        f"Coordinate `{node._path}[{n[0]}]/time` is empty."
+                    )
+
+            with self._capture_goto_errors(dim, coordinate) as captured:
+                # other_element may (incorrectly) be a struct in older DD versions
+                expected_size = other_element.shape[0]
+            if captured:
+                continue  # Ignored error, continue to next dimension
+            if shape[dim] != expected_size:
+                other_path = other_element._path
+                raise CoordinateError(node, dim, expected_size, other_path)
+
+        # Validate coordinate_same_as
+        for dim in range(metadata.ndim):
+            same_as = metadata.coordinates_same_as[dim]
+            if not same_as.has_validation:
+                continue  # Nothing to validate
+
+            assert len(same_as.references) == 1
+            with self._capture_goto_errors(dim, coordinate) as captured:
+                other_element = same_as.references[0].goto(self._node)
+            if captured:
+                continue  # Ignored error, continue to next dimension
+
+            expected_size = other_element.shape[dim]
+            if shape[dim] != expected_size:
+                other_path = other_element._path
+                raise CoordinateError(node, dim, expected_size, other_path)
+
+    @contextmanager
+    def _capture_goto_errors(self, dim, coordinate):
+        """Helper method for _validate to capture errors encountered during
+        IDSPath.goto().
+        """
+        did_capture = []
+        path = self._node._path
+        try:
+            yield did_capture
+        except CoordinateLookupError as exc:
+            raise ValidationError(exc.args[0])
+        except IndexError as exc:
+            # Can happen in IDSPath.goto when an invalid index is encountered.
+            coordinate_refs = coordinate.format_refs(self._node)
+            raise ValidationError(
+                f"Error while validating element `{path}`: dimension {dim + 1} has an "
+                f"invalid index for coordinate(s) {coordinate_refs}."
+            ) from exc
+        except Exception as exc:
+            # Ignore all other exceptions and log them
+            if "Unexpected index" in str(exc):
+                logger.debug(
+                    "Ignored AoS coordinate outside our tree (see IMAS-4675) of "
+                    "element `%s`, dimension %s, coordinate `%s`",
+                    path,
+                    dim,
+                    coordinate.references,
+                )
+            else:
+                if self._node._version <= "3.38.1":
+                    version_error = (
+                        "This is expected to happen in DD versions <= 3.38.1, where "
+                        "some coordinate metadata is incorrect."
+                    )
+                else:
+                    version_error = (
+                        "Please report this issue to the imas-python developers."
+                    )
+                logger.warning(
+                    "An error occurred while finding coordinate `%s` of dimension %s, "
+                    "which is ignored. %s",
+                    coordinate.references,
+                    dim,
+                    version_error,
+                    exc_info=1,
+                )
+            # Flag to the caller that an error was suppressed
+            did_capture.append(1)

imas/ids_data_type.py

@@ -0,0 +1,115 @@
+# This file is part of imas-python.
+# You should have received the imas-python LICENSE file with this project.
+"""Data Dictionary type handling functionality.
+"""
+
+from enum import Enum
+from functools import lru_cache
+from typing import Optional, Tuple
+
+import numpy as np
+
+from imas.ids_defs import (
+    CHAR_DATA,
+    COMPLEX_DATA,
+    DOUBLE_DATA,
+    EMPTY_COMPLEX,
+    EMPTY_FLOAT,
+    EMPTY_INT,
+    INTEGER_DATA,
+)
+
+
+class IDSDataType(Enum):
+    """Enum representing the possible data types in an IDS"""
+
+    STRUCTURE = "structure"
+    """IDS structure. Maps to an IDSStructure object."""
+
+    STRUCT_ARRAY = "struct_array"
+    """IDS array of structures. Maps to an IDSStructArray object with IDSStructure
+    children."""
+
+    STR = "STR"
+    """String data."""
+
+    INT = "INT"
+    """Integer data."""
+
+    FLT = "FLT"
+    """Floating point data."""
+
+    CPX = "CPX"
+    """Complex data."""
+
+    def __init__(self, value) -> None:
+        self.default = {
+            "STR": "",
+            "INT": EMPTY_INT,
+            "FLT": EMPTY_FLOAT,
+            "CPX": EMPTY_COMPLEX,
+        }.get(value, None)
+        """Default value for a field with this type."""
+
+        self.al_type = {
+            "STR": CHAR_DATA,
+            "INT": INTEGER_DATA,
+            "FLT": DOUBLE_DATA,
+            "CPX": COMPLEX_DATA,
+        }.get(value, None)
+        """Lowlevel identifier for this type."""
+
+        self.python_type = {
+            "STR": str,
+            "INT": int,
+            "FLT": float,
+            "CPX": complex,
+        }.get(value, None)
+        """Python type for 0D instances of this type."""
+
+        self.numpy_dtype = {
+            "INT": np.int32,
+            "FLT": np.float64,
+            "CPX": np.complex128,
+        }.get(value, None)
+        """Numpy dtype for array instances of this type."""
+
+    @staticmethod
+    @lru_cache(maxsize=None)
+    def parse(data_type: Optional[str]) -> Tuple[Optional["IDSDataType"], int]:
+        """Parse data type string from the Data Dictionary.
+
+        Args:
+            data_type: Data type string from the DD.
+
+        Returns:
+            IDSDataType instance representing the parsed data type and number of
+            dimensions.
+
+        Examples:
+            >>> IDSDataType.parse("STR_1D")
+            (<IDSDataType.STR: 'STR'>, 1)
+            >>> IDSDataType.parse("struct_array")
+            (<IDSDataType.STRUCT_ARRAY: 'struct_array'>, 1)
+            >>> IDSDataType.parse("structure")
+            (<IDSDataType.STRUCTURE: 'structure'>, 0)
+            >>> IDSDataType.parse("CPX_5D")
+            (<IDSDataType.CPX: 'CPX'>, 5)
+        """
+        if data_type is None:
+            return None, 0
+        if data_type == "structure":
+            ndim = 0
+        elif data_type == "struct_array":
+            ndim = 1
+        else:
+            dtype, *rest = data_type.upper().split("_")
+            if rest == ["TYPE"]:  # legacy str_type, int_type, flt_type, cpx_type:
+                ndim = 0
+            elif rest and "0" <= rest[0][0] <= "9":
+                # works for both legacy flt_1d_type and regular TYP_ND
+                ndim = int(rest[0][0])
+            else:
+                raise ValueError(f"Unknown IDS data type: {data_type}")
+            data_type = dtype
+        return IDSDataType(data_type), ndim

imas/ids_defs.py

@@ -0,0 +1,171 @@
+# This file is part of imas-python.
+# You should have received the imas-python LICENSE file with this project.
+""" Load imas-python libs to provide constants
+
+.. _`Backend identifiers`:
+
+Backend identifiers
+-------------------
+
+The following constants are identifiers for the different Access Layer backends. Please
+see the Access Layer documentation for more details on the different backends.
+
+.. data:: ASCII_BACKEND
+
+    Identifier for the ASCII backend.
+
+.. data:: MDSPLUS_BACKEND
+
+    Identifier for the MDS+ backend.
+
+.. data:: HDF5_BACKEND
+
+    Identifier for the HDF5 backend.
+
+.. data:: MEMORY_BACKEND
+
+    Identifier for the memory backend.
+
+.. data:: UDA_BACKEND
+
+    Identifier for the UDA backend.
+
+
+Time modes
+----------
+
+.. data:: IDS_TIME_MODE_HOMOGENEOUS
+
+    Use homogeneous time, all time coordinates refer to the toplevel ``time`` array.
+
+.. data:: IDS_TIME_MODE_HETEROGENEOUS
+
+    Use heterogeneous time, time coordinates refer to their local ``time`` array.
+
+.. data:: IDS_TIME_MODE_INDEPENDENT
+
+    Indicates that this IDS does not store time-dependent data.
+
+
+Interpolation modes
+-------------------
+
+.. data:: CLOSEST_INTERP
+
+    Interpolation method that returns the `closest` time slice in the original IDS (can
+    break causality as it can return data ahead of requested time).
+
+.. data:: PREVIOUS_INTERP
+
+    Interpolation method that returns the `previous` time slice if the requested time
+    does not exactly exist in the original IDS.
+
+.. data:: LINEAR_INTERP
+
+    Interpolation method that returns a linear interpolation between the existing slices
+    before and after the requested time.
+
+
+Serializer protocols
+--------------------
+
+.. data:: ASCII_SERIALIZER_PROTOCOL
+
+    Identifier for the ASCII serialization protocol.
+
+.. data:: FLEXBUFFERS_SERIALIZER_PROTOCOL
+
+    Identifier for the Flexbuffers serialization protocol. This protocol is more
+    performant and results in a smaller buffer size than the
+    :data:`ASCII_SERIALIZER_PROTOCOL`.
+
+    .. versionadded:: 1.1 Requires ``imas_core`` version 5.3 or newer.
+
+.. data:: DEFAULT_SERIALIZER_PROTOCOL
+
+    Identifier for the default serialization protocol.
+"""
+
+import functools
+import logging
+
+from imas.backends.imas_core.imas_interface import has_imas, imasdef
+
+logger = logging.getLogger(__name__)
+
+
+if has_imas:
+    ASCII_BACKEND = imasdef.ASCII_BACKEND
+    CHAR_DATA = imasdef.CHAR_DATA
+    CLOSE_PULSE = imasdef.CLOSE_PULSE
+    CLOSEST_INTERP = imasdef.CLOSEST_INTERP
+    CREATE_PULSE = imasdef.CREATE_PULSE
+    DOUBLE_DATA = imasdef.DOUBLE_DATA
+    COMPLEX_DATA = imasdef.COMPLEX_DATA
+    EMPTY_COMPLEX = imasdef.EMPTY_COMPLEX
+    EMPTY_FLOAT = imasdef.EMPTY_FLOAT
+    EMPTY_INT = imasdef.EMPTY_INT
+    ERASE_PULSE = imasdef.ERASE_PULSE
+    FORCE_CREATE_PULSE = imasdef.FORCE_CREATE_PULSE
+    FORCE_OPEN_PULSE = imasdef.FORCE_OPEN_PULSE
+    HDF5_BACKEND = imasdef.HDF5_BACKEND
+    IDS_TIME_MODE_HETEROGENEOUS = imasdef.IDS_TIME_MODE_HETEROGENEOUS
+    IDS_TIME_MODE_HOMOGENEOUS = imasdef.IDS_TIME_MODE_HOMOGENEOUS
+    IDS_TIME_MODE_INDEPENDENT = imasdef.IDS_TIME_MODE_INDEPENDENT
+    IDS_TIME_MODE_UNKNOWN = imasdef.IDS_TIME_MODE_UNKNOWN
+    IDS_TIME_MODES = imasdef.IDS_TIME_MODES
+    INTEGER_DATA = imasdef.INTEGER_DATA
+    LINEAR_INTERP = imasdef.LINEAR_INTERP
+    MDSPLUS_BACKEND = imasdef.MDSPLUS_BACKEND
+    MEMORY_BACKEND = imasdef.MEMORY_BACKEND
+    NODE_TYPE_STRUCTURE = imasdef.NODE_TYPE_STRUCTURE
+    OPEN_PULSE = imasdef.OPEN_PULSE
+    PREVIOUS_INTERP = imasdef.PREVIOUS_INTERP
+    READ_OP = imasdef.READ_OP
+    UDA_BACKEND = imasdef.UDA_BACKEND
+    UNDEFINED_INTERP = imasdef.UNDEFINED_INTERP
+    UNDEFINED_TIME = imasdef.UNDEFINED_TIME
+    WRITE_OP = imasdef.WRITE_OP
+    ASCII_SERIALIZER_PROTOCOL = getattr(imasdef, "ASCII_SERIALIZER_PROTOCOL", 60)
+    FLEXBUFFERS_SERIALIZER_PROTOCOL = getattr(
+        imasdef, "FLEXBUFFERS_SERIALIZER_PROTOCOL", None
+    )
+    DEFAULT_SERIALIZER_PROTOCOL = getattr(imasdef, "DEFAULT_SERIALIZER_PROTOCOL", 60)
+
+else:
+    # Preset some constants which are used elsewhere
+    # this is a bit ugly, perhaps reuse the list of imports from above?
+    # it seems no problem to use None, since the use of the values should not
+    # be allowed, they are only used in operations which use the backend,
+    # which we (should) gate
+    ASCII_BACKEND = CHAR_DATA = CLOSE_PULSE = CLOSEST_INTERP = DOUBLE_DATA = None
+    FORCE_OPEN_PULSE = CREATE_PULSE = ERASE_PULSE = None
+    COMPLEX_DATA = FORCE_CREATE_PULSE = HDF5_BACKEND = None
+    INTEGER_DATA = LINEAR_INTERP = MDSPLUS_BACKEND = MEMORY_BACKEND = None
+    NODE_TYPE_STRUCTURE = OPEN_PULSE = PREVIOUS_INTERP = READ_OP = None
+    UDA_BACKEND = UNDEFINED_INTERP = UNDEFINED_TIME = WRITE_OP = None
+    # These constants are also useful when not working with the AL
+    EMPTY_FLOAT = -9e40
+    EMPTY_INT = -999_999_999
+    EMPTY_COMPLEX = complex(EMPTY_FLOAT, EMPTY_FLOAT)
+    IDS_TIME_MODE_UNKNOWN = EMPTY_INT
+    IDS_TIME_MODE_HETEROGENEOUS = 0
+    IDS_TIME_MODE_HOMOGENEOUS = 1
+    IDS_TIME_MODE_INDEPENDENT = 2
+    IDS_TIME_MODES = [0, 1, 2]
+    ASCII_SERIALIZER_PROTOCOL = 60
+    FLEXBUFFERS_SERIALIZER_PROTOCOL = None
+    DEFAULT_SERIALIZER_PROTOCOL = 60
+
+
+def needs_imas(func):
+    if has_imas:
+        return func
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        raise RuntimeError(
+            f"Function {func.__name__} requires IMAS, but IMAS is not available."
+        )
+
+    return wrapper