musica 0.14.4__cp310-cp310-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl

musica/micm/__init__.py

@@ -0,0 +1,10 @@
+from .utils import species_ordering, user_defined_rate_parameters_ordering
+from .state import State
+from .solver_result import SolverState, SolverStats, SolverResult
+from .solver import SolverType
+from .micm import MICM
+from .conditions import Conditions
+from .. import backend
+_backend = backend.get_backend()
+
+__version__ = _backend._micm._get_micm_version()

musica/micm/conditions.py

@@ -0,0 +1,49 @@
+# Copyright (C) 2023-2026 University Corporation for Atmospheric Research
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Optional, Union
+from ..constants import GAS_CONSTANT
+
+from .. import backend
+
+_backend = backend.get_backend()
+Conditions = _backend._micm._Conditions
+original_init = Conditions.__init__
+
+
+def __init__(
+    self,
+    temperature: Optional[Union[float, int]] = None,
+    pressure: Optional[Union[float, int]] = None,
+    air_density: Optional[Union[float, int]] = None,
+):
+    """
+    Initializes the Conditions object with the given parameters.
+
+    Args:
+        temperature (float): Temperature in Kelvin.
+        pressure (float): Pressure in Pascals.
+        air_density (float): Air density in mol m-3
+    """
+    original_init(self)
+    if temperature is not None:
+        self.temperature = temperature
+    if pressure is not None:
+        self.pressure = pressure
+    if air_density is not None:
+        self.air_density = air_density
+    elif temperature is not None and pressure is not None:
+        self.air_density = 1.0 / (GAS_CONSTANT * temperature / pressure)
+
+
+Conditions.__doc__ = """
+    Conditions class for the MICM solver. If air density is not provided,
+    it will be calculated from the Ideal Gas Law using the provided temperature and pressure.
+
+    Attributes:
+        temperature (float): Temperature in Kelvin.
+        pressure (float): Pressure in Pascals.
+        air_density (float): Air density in mol m-3
+    """
+
+Conditions.__init__ = __init__

musica/micm/micm.py

@@ -0,0 +1,135 @@
+# Copyright (C) 2023-2026 University Corporation for Atmospheric Research
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+from typing import Union, Any, TYPE_CHECKING, List
+from os import PathLike
+
+from .state import State
+from .solver import SolverType
+from .solver_result import SolverResult
+from .. import backend
+
+_backend = backend.get_backend()
+
+create_solver = _backend._micm._create_solver
+create_solver_from_mechanism = _backend._micm._create_solver_from_mechanism
+micm_solve = _backend._micm._micm_solve
+vector_size = _backend._micm._vector_size
+
+# For type hints
+if TYPE_CHECKING:
+    from ..mechanism_configuration import Mechanism
+    from .solver_result import SolverResult as SolverResultType
+else:
+    Mechanism = _backend._mechanism_configuration._Mechanism
+    SolverResultType = SolverResult
+
+FilePath = Union[str, "PathLike[str]"]
+
+
+class MICM():
+    """
+    The MICM class is a wrapper around the C++ MICM solver. It provides methods to create a solver,
+    create a state, and solve the system of equations.
+
+    Parameters
+    ----------
+    config_path : FilePath
+        Path to the configuration file.
+    mechanism : mechanism_configuration.Mechanism
+        Mechanism object which specifies the chemical mechanism to use.
+    solver_type : SolverType
+        Type of solver to use.
+    number_of_grid_cells : int
+        Number of grid cells to use. The default is 1.
+    """
+
+    def __init__(
+        self,
+        config_path: FilePath = None,
+        mechanism: Mechanism = None,
+        solver_type: Any = None,
+        ignore_non_gas_phases: bool = True,
+    ):
+        """    Initialize the MICM solver.
+
+        Parameters
+        ----------
+            config_path : FilePath, optional
+                Path to the configuration file. If provided, this will be used to create the solver.
+            mechanism : Mechanism, optional
+                Mechanism object which specifies the chemical mechanism to use. If provided, this will be used
+                to create the solver.
+            solver_type : SolverType, optional
+                Type of solver to use. If not provided, the default Rosenbrock (with standard-ordered matrices) solver type will be used.
+            ignore_non_gas_phases : bool, optional
+                If True, non-gas phases will be ignored when configuring micm with the mechanism. This is only needed
+                until micm properly supports non-gas phases. This option is only supported when passing in a mechanism.
+        """
+        if solver_type is None:
+            solver_type = SolverType.rosenbrock_standard_order
+        self.__solver_type = solver_type
+        self.__vector_size = vector_size(solver_type)
+        if self.__vector_size <= 0:
+            raise ValueError(f"Invalid vector size: {self.__vector_size}")
+        if config_path is None and mechanism is None:
+            raise ValueError(
+                "Either config_path or mechanism must be provided.")
+        if config_path is not None and mechanism is not None:
+            raise ValueError(
+                "Only one of config_path or mechanism must be provided.")
+        if config_path is not None:
+            self.__solver = create_solver(config_path, solver_type)
+        elif mechanism is not None:
+            self.__solver = create_solver_from_mechanism(
+                mechanism, solver_type, ignore_non_gas_phases)
+
+    def solver_type(self) -> SolverType:
+        """
+        Get the type of solver used.
+
+        Returns
+        -------
+        SolverType
+            The type of solver used.
+        """
+        return self.__solver_type
+
+    def create_state(self, number_of_grid_cells: int = 1) -> State:
+        """
+        Create a new state object.
+
+        Returns
+        -------
+        State
+            A new state object.
+        """
+        return State(self.__solver, number_of_grid_cells, self.__vector_size)
+
+    def solve(
+            self,
+            state: State,
+            time_step: float,
+    ) -> SolverResult:
+        """
+        Solve the system of equations for the given state and time step.
+
+        Parameters
+        ----------
+        state : State
+            State object containing the initial conditions.
+        time_step : float
+            Time step in seconds.
+
+        Returns
+        -------
+        SolverResult
+            A SolverResult object containing the solver state and statistics.
+        """
+        if not isinstance(state, State):
+            raise TypeError("state must be an instance of State.")
+        if not isinstance(time_step, (int, float)):
+            raise TypeError("time_step must be an int or float.")
+
+        return micm_solve(self.__solver, state.get_internal_state(), time_step)

musica/micm/solver.py

@@ -0,0 +1,8 @@
+# Copyright (C) 2023-2026 University Corporation for Atmospheric Research
+# SPDX-License-Identifier: Apache-2.0
+
+from .. import backend
+
+_backend = backend.get_backend()
+
+SolverType = _backend._micm._SolverType

musica/micm/solver_result.py

@@ -0,0 +1,24 @@
+# Copyright (C) 2023-2026 University Corporation for Atmospheric Research
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Module for exposing solver result types from MICM.
+
+This module provides access to:
+- SolverState: Enum representing the final state of the solver
+- SolverStats: Statistics from a solver run
+- SolverResult: Combined result containing both state and statistics
+"""
+
+from .. import backend
+
+_backend = backend.get_backend()
+
+# Expose the SolverState enum
+SolverState = _backend._micm._SolverState
+
+# Expose the SolverStats class
+SolverStats = _backend._micm._SolverResultsStats
+
+# Expose the SolverResult class
+SolverResult = _backend._micm._SolverResult

musica/micm/state.py

@@ -0,0 +1,220 @@
+# Copyright (C) 2023-2026 University Corporation for Atmospheric Research
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Optional, Dict, List, Union, Any
+import math
+
+from ..constants import GAS_CONSTANT
+from .. import backend
+from .utils import is_scalar_number, species_ordering, user_defined_rate_parameters_ordering
+
+_backend = backend.get_backend()
+
+create_state = _backend._micm._create_state
+
+
+class State():
+    """
+    State class for the MICM solver. It contains the initial conditions and species concentrations.
+    """
+
+    def __init__(self, solver: Any, number_of_grid_cells: int, vector_size: int = 0):
+        if number_of_grid_cells < 1:
+            raise ValueError("number_of_grid_cells must be greater than 0.")
+        super().__init__()
+        self.__state = create_state(solver, number_of_grid_cells)
+        self.__species_ordering = species_ordering(self.__state)
+        self.__user_defined_rate_parameters_ordering = user_defined_rate_parameters_ordering(self.__state)
+        self.__number_of_grid_cells = number_of_grid_cells
+        self.__vector_size = vector_size
+
+    def get_internal_state(self) -> Any:
+        """
+        Get the internal state object. This is used for passing the state to the solver.
+
+        Returns
+        -------
+        _State
+            Internal state object.
+        """
+        return self.__state
+
+    def set_concentrations(self, concentrations: Dict[str, Union[Union[float, int], List[Union[float, int]]]]):
+        """
+        Set the concentrations of the species in the state. Any species not in the
+        dictionary will be set to zero. The concentrations can be a single value when solving
+        for a single grid cell, or a list of values when solving for multiple grid cells.
+
+        Parameters
+        ----------
+        concentrations : Dict[str, Union[Union[float, int], List[Union[float, int]]]]
+            Dictionary of species names and their concentrations.
+        """
+        n_species = len(self.__species_ordering)
+        for name, value in concentrations.items():
+            if name not in self.__species_ordering:
+                raise ValueError(f"Species {name} not found in the mechanism.")
+            i_species = self.__species_ordering[name]
+            if is_scalar_number(value):
+                value = [value]
+            if len(value) != self.__number_of_grid_cells:
+                raise ValueError(f"Concentration list for {name} must have length {self.__number_of_grid_cells}.")
+            for i_cell in range(self.__number_of_grid_cells):
+                group_index = i_cell // self.__vector_size
+                row_in_group = i_cell % self.__vector_size
+                idx = (group_index * n_species + i_species) * self.__vector_size + row_in_group
+                self.__state.concentrations[idx] = value[i_cell]
+
+    def set_user_defined_rate_parameters(
+            self, user_defined_rate_parameters: Dict[str, Union[Union[float, int], List[Union[float, int]]]]):
+        """
+        Set the user-defined rate parameters in the state. Any parameter not in the
+        dictionary will be set to zero. The parameters can be a single value when solving
+        for a single grid cell, or a list of values when solving for multiple grid cells.
+
+        Parameters
+        ----------
+        user_defined_rate_parameters : Dict[str, Union[Union[float, int], List[Union[float, int]]]]
+            Dictionary of user-defined rate parameter names and their values.
+        """
+        n_params = len(self.__user_defined_rate_parameters_ordering)
+        for name, value in user_defined_rate_parameters.items():
+            if name not in self.__user_defined_rate_parameters_ordering:
+                raise ValueError(f"User-defined rate parameter {name} not found in the mechanism.")
+            i_param = self.__user_defined_rate_parameters_ordering[name]
+            if is_scalar_number(value):
+                value = [value]
+            if len(value) != self.__number_of_grid_cells:
+                raise ValueError(
+                    f"User-defined rate parameter list for {name} must have length {self.__number_of_grid_cells}.")
+            for i_cell in range(self.__number_of_grid_cells):
+                group_index = i_cell // self.__vector_size
+                row_in_group = i_cell % self.__vector_size
+                idx = (group_index * n_params + i_param) * self.__vector_size + row_in_group
+                self.__state.user_defined_rate_parameters[idx] = value[i_cell]
+
+    def set_conditions(self,
+                       temperatures: Optional[Union[Union[float, int], List[Union[float, int]]]] = None,
+                       pressures: Optional[Union[Union[float, int], List[Union[float, int]]]] = None,
+                       air_densities: Optional[Union[Union[float, int], List[Union[float, int]]]] = None):
+        """
+        Set the conditions for the state. The individual conditions can be a single value
+        when solving for a single grid cell, or a list of values when solving for multiple grid cells.
+        If air density is not provided, it will be calculated from the Ideal Gas Law using the provided
+        temperature and pressure. If temperature or pressure are not provided, their values will remain
+        unchanged.
+
+        Parameters
+        ----------
+        temperatures : Optional[Union[float, List[float]]]
+            Temperature in Kelvin.
+        pressures : Optional[Union[float, List[float]]]
+            Pressure in Pascals.
+        air_densities : Optional[Union[float, List[float]]]
+            Air density in mol m-3. If not provided, it will be calculated from the Ideal Gas Law.
+        """
+
+        empty = [None] * self.__number_of_grid_cells
+
+        def check_and_expand(param, name):
+            if param is not None:
+                if is_scalar_number(param):
+                    if self.__number_of_grid_cells > 1:
+                        raise ValueError(f"{name} must be a list of length {self.__number_of_grid_cells}.")
+                    param = [param]
+                elif len(param) != self.__number_of_grid_cells:
+                    raise ValueError(f"{name} must be a list of length {self.__number_of_grid_cells}.")
+            else:
+                param = empty
+            return param
+        temperatures = check_and_expand(temperatures, "temperatures")
+        pressures = check_and_expand(pressures, "pressures")
+        air_densities = check_and_expand(air_densities, "air_densities")
+
+        for condition, temp, pres, dens in zip(self.__state.conditions, temperatures, pressures, air_densities):
+            condition.temperature = temp if temp is not None else condition.temperature
+            condition.pressure = pres if pres is not None else condition.pressure
+            condition.air_density = dens if dens is not None else condition.pressure / \
+                (GAS_CONSTANT * condition.temperature)
+
+    def get_concentrations(self) -> Dict[str, List[float]]:
+        """
+        Get the concentrations of the species in the state.
+
+        Returns
+        -------
+        Dict[str, List[float]]
+            Dictionary of species names and their concentrations.
+        """
+        concentrations = {}
+        n_species = len(self.__species_ordering)
+
+        for species, i_species in self.__species_ordering.items():
+            concentrations[species] = []
+            for i_cell in range(self.__number_of_grid_cells):
+                group_index = i_cell // self.__vector_size
+                row_in_group = i_cell % self.__vector_size
+                idx = (group_index * n_species + i_species) * self.__vector_size + row_in_group
+                concentrations[species].append(self.__state.concentrations[idx])
+        return concentrations
+
+    def get_user_defined_rate_parameters(self) -> Dict[str, List[float]]:
+        """
+        Get the user-defined rate parameters in the state.
+
+        Returns
+        -------
+        Dict[str, List[float]]
+            Dictionary of user-defined rate parameter names and their values.
+        """
+        user_defined_rate_parameters = {}
+        n_params = len(self.__user_defined_rate_parameters_ordering)
+        for param, i_param in self.__user_defined_rate_parameters_ordering.items():
+            user_defined_rate_parameters[param] = []
+            for i_cell in range(self.__number_of_grid_cells):
+                group_index = i_cell // self.__vector_size
+                row_in_group = i_cell % self.__vector_size
+                idx = (group_index * n_params + i_param) * self.__vector_size + row_in_group
+                user_defined_rate_parameters[param].append(self.__state.user_defined_rate_parameters[idx])
+        return user_defined_rate_parameters
+
+    def get_conditions(self) -> Dict[str, List[float]]:
+        """
+        Get the conditions for the state.
+
+        Returns
+        -------
+        Dict[str, List[float]]
+            Dictionary of conditions names and their values.
+        """
+        conditions = {}
+        conditions["temperature"] = []
+        conditions["pressure"] = []
+        conditions["air_density"] = []
+        for i_cell in range(self.__number_of_grid_cells):
+            conditions["temperature"].append(self.__state.conditions[i_cell].temperature)
+            conditions["pressure"].append(self.__state.conditions[i_cell].pressure)
+            conditions["air_density"].append(self.__state.conditions[i_cell].air_density)
+        return conditions
+
+    def get_species_ordering(self) -> Dict[str, int]:
+        """
+        Get the species ordering for the state.
+
+        Returns
+        -------
+        Dict[str, int]
+            Dictionary of species names and their indices.
+        """
+        return self.__species_ordering
+
+    def get_user_defined_rate_parameters_ordering(self) -> Dict[str, int]:
+        """
+        Get the user-defined rate parameters ordering for the state.
+
+        Returns
+        -------
+        Dict[str, int]
+            Dictionary of user-defined rate parameter names and their indices.
+        """
+        return self.__user_defined_rate_parameters_ordering

musica/micm/utils.py

@@ -0,0 +1,18 @@
+# Copyright (C) 2023-2026 University Corporation for Atmospheric Research
+# SPDX-License-Identifier: Apache-2.0
+
+import numpy as np
+
+from .. import backend
+
+_backend = backend.get_backend()
+
+species_ordering = _backend._micm._species_ordering
+user_defined_rate_parameters_ordering = _backend._micm._user_defined_rate_parameters_ordering
+
+
+def is_scalar_number(x):
+    return (
+        isinstance(x, (int, float, np.number))
+        and not isinstance(x, bool)
+    )

musica/tuvx/__init__.py

@@ -0,0 +1,11 @@
+from .radiator import Radiator
+from .radiator_map import RadiatorMap
+from .profile import Profile
+from .profile_map import ProfileMap
+from .grid import Grid
+from .grid_map import GridMap
+from .tuvx import TUVX
+from .. import backend
+_backend = backend.get_backend()
+
+__version__ = _backend._tuvx._get_tuvx_version() if backend.tuvx_available() else None

musica/tuvx/grid.py

@@ -0,0 +1,98 @@
+# Copyright (C) 2023-2026 University Corporation for Atmospheric Research
+# SPDX-License-Identifier: Apache-2.0
+"""
+TUV-x Grid class.
+
+This module provides a class for defining grids on which TUV-x profiles exist.
+Typically, this would be used to define vertical and wavelength grids.
+
+Note: TUV-x is only available on macOS and Linux platforms.
+"""
+
+from typing import Optional
+import numpy as np
+from .. import backend
+
+_backend = backend.get_backend()
+
+Grid = _backend._tuvx._Grid if backend.tuvx_available() else None
+
+if backend.tuvx_available():
+    original_init = Grid.__init__
+
+    def __init__(self, *, name: str, units: str,
+                 num_sections: Optional[int] = None,
+                 edges: Optional[np.ndarray] = None,
+                 midpoints: Optional[np.ndarray] = None,
+                 **kwargs):
+        """Initialize a Grid instance. Note that at least one of num_sections, edges, or midpoints
+        must be provided.
+
+        Args:
+            name: Name of the grid
+            units: Units of the grid values
+            num_sections: Optional number of grid sections
+            edges: Optional array of edge values (length num_sections + 1)
+            midpoints: Optional array of midpoint values (length num_sections)
+            **kwargs: Additional arguments passed to the C++ constructor
+        """
+        if (num_sections is None and edges is None and midpoints is None):
+            raise ValueError("At least one of num_sections, edges, or midpoints must be provided.")
+        if (num_sections is None):
+            if (edges is not None):
+                num_sections = len(edges) - 1
+            elif (midpoints is not None):
+                num_sections = len(midpoints)
+        # Call the original C++ constructor correctly
+        original_init(self, name=name, units=units, num_sections=num_sections, **kwargs)
+
+        # Set edges or midpoints if provided
+        if edges is not None:
+            self.edges = edges
+        if midpoints is not None:
+            self.midpoints = midpoints
+
+    Grid.__init__ = __init__
+
+    def __str__(self):
+        """User-friendly string representation."""
+        return f"Grid(name={self.name}, units={self.units}, num_sections={self.num_sections})"
+
+    Grid.__str__ = __str__
+
+    def __repr__(self):
+        """Detailed string representation for debugging."""
+        return (f"Grid(name={self.name}, units={self.units}, num_sections={self.num_sections}, "
+                f"edges={self.edges}, midpoints={self.midpoints})")
+
+    Grid.__repr__ = __repr__
+
+    def __len__(self):
+        """Return the number of sections in the grid."""
+        return self.num_sections
+
+    Grid.__len__ = __len__
+
+    def __eq__(self, other):
+        """Check equality with another Grid instance."""
+        if not isinstance(other, Grid):
+            return NotImplemented
+        return (self.name == other.name and
+                self.units == other.units and
+                self.num_sections == other.num_sections and
+                np.array_equal(self.edges, other.edges) and
+                np.array_equal(self.midpoints, other.midpoints))
+
+    Grid.__eq__ = __eq__
+
+    def __bool__(self):
+        """Return True if the grid has sections."""
+        return self.num_sections > 0
+
+    Grid.__bool__ = __bool__
+
+    def __contains__(self, value):
+        """Check if a value is within the grid bounds."""
+        return self.edges[0] <= value <= self.edges[-1]
+
+    Grid.__contains__ = __contains__