musica 0.12.0__cp39-cp39-win32.whl → 0.12.2__cp39-cp39-win32.whl

musica/tuvx.cpp

@@ -0,0 +1,93 @@
+#include "binding_common.hpp"
+
+#include <musica/tuvx/tuvx.hpp>
+
+#include <pybind11/numpy.h>
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+
+namespace py = pybind11;
+
+void bind_tuvx(py::module_& tuvx)
+{
+  tuvx.def("_get_tuvx_version", []() { return musica::TUVX::GetVersion(); }, "Get the version of the TUV-x instance");
+
+  tuvx.def(
+      "_create_tuvx",
+      [](const char* config_path)
+      {
+        try
+        {
+          auto tuvx_instance = new musica::TUVX();
+          tuvx_instance->CreateFromConfigOnly(config_path);
+          return reinterpret_cast<std::uintptr_t>(tuvx_instance);
+        }
+        catch (const std::exception& e)
+        {
+          throw py::value_error(
+              "Error creating TUV-x instance from config file: " + std::string(config_path) + " - " + e.what());
+        }
+      },
+      "Create a TUV-x instance from a JSON configuration file");
+
+  tuvx.def(
+      "_delete_tuvx",
+      [](std::uintptr_t tuvx_ptr)
+      {
+        musica::TUVX* tuvx_instance = reinterpret_cast<musica::TUVX*>(tuvx_ptr);
+        delete tuvx_instance;
+      },
+      "Delete a TUV-x instance");
+
+  tuvx.def(
+      "_run_tuvx",
+      [](std::uintptr_t tuvx_ptr)
+      {
+        musica::TUVX* tuvx_instance = reinterpret_cast<musica::TUVX*>(tuvx_ptr);
+
+        // Get dimensions
+        int n_photolysis = tuvx_instance->GetPhotolysisRateCount();
+
+        int n_heating = tuvx_instance->GetHeatingRateCount();
+
+        int n_layers = tuvx_instance->GetNumberOfLayers();
+
+        int n_sza_steps = tuvx_instance->GetNumberOfSzaSteps();
+
+        // Allocate output arrays (3D: sza_step, layer, reaction/heating_type)
+        std::vector<double> photolysis_rates(n_sza_steps * n_layers * n_photolysis);
+        std::vector<double> heating_rates(n_sza_steps * n_layers * n_heating);
+
+        // Run TUV-x (everything comes from the JSON config)
+        tuvx_instance->RunFromConfig(photolysis_rates.data(), heating_rates.data());
+
+        // Return as numpy arrays with shape (n_sza_steps, n_layers, n_reactions/n_heating)
+        py::array_t<double> py_photolysis =
+            py::array_t<double>({ n_sza_steps, n_layers, n_photolysis }, photolysis_rates.data());
+        py::array_t<double> py_heating = py::array_t<double>({ n_sza_steps, n_layers, n_heating }, heating_rates.data());
+
+        return py::make_tuple(py_photolysis, py_heating);
+      },
+      "Run TUV-x (all parameters come from JSON config)",
+      py::arg("tuvx_instance"));
+
+  tuvx.def(
+      "_get_photolysis_rate_names",
+      [](std::uintptr_t tuvx_ptr)
+      {
+        musica::TUVX* tuvx_instance = reinterpret_cast<musica::TUVX*>(tuvx_ptr);
+
+        return tuvx_instance->GetPhotolysisRateNames();
+      },
+      "Get photolysis rate names");
+
+  tuvx.def(
+      "_get_heating_rate_names",
+      [](std::uintptr_t tuvx_ptr)
+      {
+        musica::TUVX* tuvx_instance = reinterpret_cast<musica::TUVX*>(tuvx_ptr);
+
+        return tuvx_instance->GetHeatingRateNames();
+      },
+      "Get heating rate names");
+}

musica/tuvx.py

@@ -0,0 +1,199 @@
+"""
+TUV-x photolysis calculator Python interface.
+
+This module provides a simplified Python interface to the TUV-x photolysis calculator.
+It allows users to create a TUV-x instance from a JSON configuration file and
+calculate photolysis rates and heating rates.
+
+Note: TUV-x is only available on macOS and Linux platforms.
+"""
+
+import os
+import json
+import tempfile
+from typing import Dict, Tuple, List
+import numpy as np
+from . import backend
+
+_backend = backend.get_backend()
+
+version = _backend._tuvx._get_tuvx_version() if backend.tuvx_available() else None
+
+
+class TUVX:
+    """
+    A Python interface to the TUV-x photolysis calculator.
+
+    This class provides a simplified interface that only requires a JSON configuration
+    file to set up and run TUV-x calculations. All parameters (solar zenith angle,
+    earth-sun distance, atmospheric profiles, etc.) are specified in the JSON config.
+    """
+
+    def __init__(self, config_path: str):
+        """
+        Initialize a TUV-x instance from a configuration file.
+
+        Args:
+            config_path: Path to the JSON configuration file
+
+        Raises:
+            FileNotFoundError: If the configuration file doesn't exist
+            ValueError: If TUV-x initialization fails or TUVX is not available
+        """
+        if not backend.tuvx_available():
+            raise ValueError("TUV-x backend is not available on windows.")
+
+        if not os.path.exists(config_path):
+            raise FileNotFoundError(
+                f"Configuration file not found: {config_path}")
+
+        self._tuvx_instance = _backend._tuvx._create_tuvx(config_path)
+        self._config_path = config_path
+
+        # Cache the names for efficiency
+        self._photolysis_names = None
+        self._heating_names = None
+
+    def __del__(self):
+        """Clean up the TUV-x instance."""
+        if hasattr(self, '_tuvx_instance') and self._tuvx_instance is not None:
+            _backend._tuvx._delete_tuvx(self._tuvx_instance)
+
+    @property
+    def photolysis_rate_names(self) -> List[str]:
+        """
+        Get the names of photolysis rates.
+
+        Returns:
+            List of photolysis rate names
+        """
+        if self._photolysis_names is None:
+            self._photolysis_names = _backend._tuvx._get_photolysis_rate_names(
+                self._tuvx_instance)
+        return self._photolysis_names
+
+    @property
+    def heating_rate_names(self) -> List[str]:
+        """
+        Get the names of heating rates.
+
+        Returns:
+            List of heating rate names
+        """
+        if self._heating_names is None:
+            self._heating_names = _backend._tuvx._get_heating_rate_names(
+                self._tuvx_instance)
+        return self._heating_names
+
+    def run(self) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        Run the TUV-x photolysis calculator.
+
+        All parameters (solar zenith angle, Earth-Sun distance, atmospheric profiles,
+        etc.) are read from the JSON configuration file.
+
+        Returns:
+            Tuple of (photolysis_rate_constants, heating_rates) as numpy arrays
+            - photolysis_rate_constants: Shape (n_layers, n_reactions) [s^-1]
+            - heating_rates: Shape (n_layers, n_heating_rates) [K s^-1]
+        """
+        photolysis_rates, heating_rates = _backend._tuvx._run_tuvx(
+            self._tuvx_instance)
+
+        return photolysis_rates, heating_rates
+
+    def get_photolysis_rate_constant(
+        self,
+        reaction_name: str,
+        photolysis_rates: np.ndarray
+    ) -> np.ndarray:
+        """
+        Extract photolysis rate constants for a specific reaction.
+
+        Args:
+            reaction_name: Name of the photolysis reaction
+            photolysis_rates: Output from run() method
+
+        Returns:
+            1D array of photolysis rate constants for all layers [s^-1]
+
+        Raises:
+            KeyError: If reaction_name is not found
+        """
+        names = self.photolysis_rate_names
+        if reaction_name not in names:
+            raise KeyError(
+                f"Reaction '{reaction_name}' not found. "
+                f"Available reactions: {names}"
+            )
+
+        reaction_index = names.index(reaction_name)
+        return photolysis_rates[:, reaction_index]
+
+    def get_heating_rate(
+        self,
+        rate_name: str,
+        heating_rates: np.ndarray
+    ) -> np.ndarray:
+        """
+        Extract heating rates for a specific rate type.
+
+        Args:
+            rate_name: Name of the heating rate
+            heating_rates: Output from run() method
+
+        Returns:
+            1D array of heating rates for all layers [K s^-1]
+
+        Raises:
+            KeyError: If rate_name is not found
+        """
+        names = self.heating_rate_names
+        if rate_name not in names:
+            raise KeyError(
+                f"Heating rate '{rate_name}' not found. "
+                f"Available rates: {names}"
+            )
+
+        rate_index = names.index(rate_name)
+        return heating_rates[:, rate_index]
+
+    @staticmethod
+    def create_config_from_dict(config_dict: Dict) -> 'TUVX':
+        """
+        Create a TUVX instance from a configuration dictionary.
+
+        Args:
+            config_dict: Configuration dictionary
+
+        Returns:
+            TUVX instance initialized with the configuration
+
+        Raises:
+            ValueError: If TUV-x backend is not available
+            FileNotFoundError: If required data files are not found
+        """
+        with tempfile.NamedTemporaryFile(
+                mode='w', suffix='.json', delete=True) as temp_file:
+            json.dump(config_dict, temp_file, indent=2)
+            temp_file.flush()  # Ensure all data is written to disk
+            return TUVX(temp_file.name)
+
+    @staticmethod
+    def create_config_from_json_string(json_string: str) -> 'TUVX':
+        """
+        Create a TUVX instance from a JSON configuration string.
+
+        Args:
+            json_string: JSON configuration as string
+
+        Returns:
+            TUVX instance initialized with the configuration
+
+        Raises:
+            json.JSONDecodeError: If json_string is not valid JSON
+            ValueError: If TUV-x backend is not available
+            FileNotFoundError: If required data files are not found
+        """
+        config_dict = json.loads(json_string)
+        return TUVX.create_config_from_dict(config_dict)

musica/types.py

@@ -3,47 +3,36 @@
 #
 # This file is part of the musica Python package.
 # For more information, see the LICENSE file in the top-level directory of this distribution.
-from typing import Optional, Dict, List, Union, Tuple
+from __future__ import annotations
+from .constants import GAS_CONSTANT
+from typing import Optional, Dict, List, Union, Tuple, TYPE_CHECKING, Any
 from os import PathLike
 import math
-from musica import (
-    _Conditions,
-    _SolverType,
-    _Solver,
-    _State,
-    _create_solver,
-    _create_solver_from_mechanism,
-    _create_state,
-    _micm_solve,
-    _vector_size,
-    _species_ordering,
-    _user_defined_rate_parameters_ordering,
-)
-import musica.mechanism_configuration as mc
-from musica.constants import GAS_CONSTANT
 
-FilePath = Union[str, "PathLike[str]"]
-
-
-def _get_vector_matrix_indices(row_index: int, column_index: int, vector_size: int) -> Tuple[int, int]:
-    """
-    Get the row and column indices for a matrix given the row and column indices for a vector.
+# Import backend symbols from the backend module
+from . import backend
+
+# Get all the backend symbols we need
+_backend = backend.get_backend()
+_Conditions = _backend._core._Conditions
+_SolverType = _backend._core._SolverType
+_create_solver = _backend._core._create_solver
+_create_solver_from_mechanism = _backend._core._create_solver_from_mechanism
+_create_state = _backend._core._create_state
+_micm_solve = _backend._core._micm_solve
+_vector_size = _backend._core._vector_size
+_species_ordering = _backend._core._species_ordering
+_user_defined_rate_parameters_ordering = _backend._core._user_defined_rate_parameters_ordering
+mc = _backend._mechanism_configuration
+
+
+# For type hints
+if TYPE_CHECKING:
+    from .mechanism_configuration import Mechanism
+else:
+    Mechanism = mc._Mechanism
 
-    Parameters
-    ----------
-    row_index : int
-        Row index of the vector.
-    column_index : int
-        Column index of the vector.
-    vector_size : int
-        Size of the vector.
-
-    Returns
-    -------
-    tuple[int, int]
-        Index for which state matrix to use and the index in that matrix'x underlying data vector.
-    """
-    return (row_index // vector_size, column_index * (vector_size - 1) + row_index % vector_size)
+FilePath = Union[str, "PathLike[str]"]
 
 
 class Conditions(_Conditions):
@@ -89,20 +78,22 @@ class State():
     State class for the MICM solver. It contains the initial conditions and species concentrations.
     """
 
-    def __init__(self, solver: _Solver, number_of_grid_cells: int, vector_size: int = 0):
+    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.__states = [
-            _create_state(solver, min(vector_size, number_of_grid_cells - i * vector_size))
+            _create_state(solver, min(
+                vector_size, number_of_grid_cells - i * vector_size))
             for i in range(math.ceil(number_of_grid_cells / vector_size))
         ] if vector_size > 0 else [_create_state(solver, number_of_grid_cells)]
         self.__species_ordering = _species_ordering(self.__states[0])
-        self.__user_defined_rate_parameters_ordering = _user_defined_rate_parameters_ordering(self.__states[0])
+        self.__user_defined_rate_parameters_ordering = _user_defined_rate_parameters_ordering(
+            self.__states[0])
         self.__number_of_grid_cells = number_of_grid_cells
         self.__vector_size = vector_size
 
-    def get_internal_states(self) -> List[_State]:
+    def get_internal_states(self) -> List[Any]:
         """
         Get the internal states of the MICM solver.
 
@@ -131,13 +122,15 @@ class State():
             if isinstance(value, float) or isinstance(value, int):
                 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}.")
+                raise ValueError(
+                    f"Concentration list for {name} must have length {self.__number_of_grid_cells}.")
             # Counter 'k' is used to map grid cell indices across multiple state segments.
             k = 0
             for state in self.__states:
                 cell_stride, species_stride = state.concentration_strides()
                 for i_cell in range(state.number_of_grid_cells()):
-                    state.concentrations[i_species * species_stride + i_cell * cell_stride] = value[k]
+                    state.concentrations[i_species *
+                                         species_stride + i_cell * cell_stride] = value[k]
                     k += 1
 
     def set_user_defined_rate_parameters(
@@ -154,7 +147,8 @@ class State():
         """
         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.")
+                raise ValueError(
+                    f"User-defined rate parameter {name} not found in the mechanism.")
             i_param = self.__user_defined_rate_parameters_ordering[name]
             if isinstance(value, float) or isinstance(value, int):
                 value = [value]
@@ -166,54 +160,61 @@ class State():
             for state in self.__states:
                 cell_stride, param_stride = state.user_defined_rate_parameter_strides()
                 for i_cell in range(state.number_of_grid_cells()):
-                    state.user_defined_rate_parameters[i_param * param_stride + i_cell * cell_stride] = value[k]
+                    state.user_defined_rate_parameters[i_param *
+                                                       param_stride + i_cell * cell_stride] = value[k]
                     k += 1
 
-
     def set_conditions(self,
-                       temperatures: Union[Union[float, int], List[Union[float, int]]],
-                       pressures: Union[Union[float, int], List[Union[float, int]]],
+                       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.
+        temperature and pressure. If temperature or pressure are not provided, their values will remain
+        unchanged.
 
         Parameters
         ----------
-        temperatures : Union[float, List[float]]
+        temperatures : Optional[Union[float, List[float]]]
             Temperature in Kelvin.
-        pressures : Union[float, List[float]]
+        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.
         """
-        if isinstance(temperatures, float) or isinstance(temperatures, int):
+        if temperatures is not None and (isinstance(temperatures, float) or isinstance(temperatures, int)):
             if self.__number_of_grid_cells > 1:
-                raise ValueError(f"temperatures must be a list of length {self.__number_of_grid_cells}.")
+                raise ValueError(
+                    f"temperatures must be a list of length {self.__number_of_grid_cells}.")
             temperatures = [temperatures]
-        if isinstance(pressures, float) or isinstance(pressures, int):
+        if pressures is not None and (isinstance(pressures, float) or isinstance(pressures, int)):
             if self.__number_of_grid_cells > 1:
-                raise ValueError(f"pressures must be a list of length {self.__number_of_grid_cells}.")
+                raise ValueError(
+                    f"pressures must be a list of length {self.__number_of_grid_cells}.")
             pressures = [pressures]
         if air_densities is not None and (isinstance(air_densities, float) or isinstance(air_densities, int)):
             if self.__number_of_grid_cells > 1:
-                raise ValueError(f"air_densities must be a list of length {self.__number_of_grid_cells}.")
+                raise ValueError(
+                    f"air_densities must be a list of length {self.__number_of_grid_cells}.")
             air_densities = [air_densities]
-        if len(temperatures) != self.__number_of_grid_cells:
-            raise ValueError(f"temperatures must be a list of length {self.__number_of_grid_cells}.")
-        if len(pressures) != self.__number_of_grid_cells:
-            raise ValueError(f"pressures must be a list of length {self.__number_of_grid_cells}.")
+        if temperatures is not None and len(temperatures) != self.__number_of_grid_cells:
+            raise ValueError(
+                f"temperatures must be a list of length {self.__number_of_grid_cells}.")
+        if pressures is not None and len(pressures) != self.__number_of_grid_cells:
+            raise ValueError(
+                f"pressures must be a list of length {self.__number_of_grid_cells}.")
         if air_densities is not None and len(air_densities) != self.__number_of_grid_cells:
-            raise ValueError(f"air_densities must be a list of length {self.__number_of_grid_cells}.")
+            raise ValueError(
+                f"air_densities must be a list of length {self.__number_of_grid_cells}.")
         k = 0
         for state in self.__states:
             for condition in state.conditions:
-                condition.temperature = temperatures[k]
-                condition.pressure = pressures[k]
-                condition.air_density = air_densities[k] if air_densities is not None else pressures[k] / (
-                    GAS_CONSTANT * temperatures[k])
+                condition.temperature = temperatures[k] if temperatures is not None else condition.temperature
+                condition.pressure = pressures[k] if pressures is not None else condition.pressure
+                condition.air_density = air_densities[k] if air_densities is not None else condition.pressure / (
+                    GAS_CONSTANT * condition.temperature)
                 k += 1
 
     def get_concentrations(self) -> Dict[str, List[float]]:
@@ -269,11 +270,36 @@ class State():
         conditions["air_density"] = []
         for state in self.__states:
             for i_cell in range(state.number_of_grid_cells()):
-                conditions["temperature"].append(state.conditions[i_cell].temperature)
-                conditions["pressure"].append(state.conditions[i_cell].pressure)
-                conditions["air_density"].append(state.conditions[i_cell].air_density)
+                conditions["temperature"].append(
+                    state.conditions[i_cell].temperature)
+                conditions["pressure"].append(
+                    state.conditions[i_cell].pressure)
+                conditions["air_density"].append(
+                    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
+
 
 class MICM():
     """
@@ -295,19 +321,40 @@ class MICM():
     def __init__(
         self,
         config_path: FilePath = None,
-        mechanism: mc.Mechanism = None,
-        solver_type: _SolverType = 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 config_path is None and mechanism is None:
-            raise ValueError("Either config_path or mechanism must be provided.")
+            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.")
+            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)
+            self.__solver = _create_solver_from_mechanism(
+                mechanism, solver_type, ignore_non_gas_phases)
 
     def solver_type(self) -> SolverType:
         """