musica 0.12.0__cp311-cp311-win32.whl → 0.12.1__cp311-cp311-win32.whl

musica/constants.py

@@ -1,3 +1,3 @@
 AVOGADRO = 6.02214076e23  # mol^-1
 BOLTZMANN = 1.380649e-23  # J K^-1
-GAS_CONSTANT = AVOGADRO * BOLTZMANN  # J K^-1 mol^-1
+GAS_CONSTANT = AVOGADRO * BOLTZMANN  # J K^-1 mol^-1

musica/cpu_binding.cpp

@@ -1,9 +1,10 @@
 // Copyright (C) 2023-2025 University Corporation for Atmospheric Research
 // SPDX-License-Identifier: Apache-2.0
 
-#include <pybind11/pybind11.h>
 #include "binding_common.hpp"
 
+#include <pybind11/pybind11.h>
+
 PYBIND11_MODULE(_musica, m)
 {
   bind_all(m);

musica/cuda.py

@@ -1,4 +1,7 @@
-from . import _backend
+from . import backend
+
+_backend = backend.get_backend()
+
 
 def is_cuda_available() -> bool:
     """

musica/examples/__init__.py

@@ -0,0 +1 @@
+from .examples import Examples

musica/examples/carma_aluminum.py

@@ -0,0 +1,123 @@
+"""
+Python example for CARMA aluminum aerosols.
+
+This script creates one grid box with an initial concentration of aluminum particles
+and allows them to coagulate.
+"""
+import xarray as xr
+import numpy as np
+import musica
+import ussa1976
+
+available = musica.backend.carma_available()
+
+def run_carma_aluminum_example():
+    group = musica.carma.CARMAGroupConfig(
+        name="aluminum",
+        shortname="PRALUM",
+        rmrat=2.0,
+        rmin=21.5e-6,
+        rmon=21.5e-6,
+        ishape=musica.carma.ParticleShape.SPHERE,
+        eshape=1.0,
+        mie_calculation_algorithm=musica.carma.MieCalculationAlgorithm.TOON_1981,
+        is_ice=False,
+        is_fractal=True,
+        do_wetdep=False,
+        do_drydep=True,
+        do_vtran=True,
+        solfac=0.0,
+        scavcoef=0.0,
+        df=[1.6] * 5,  # 5 bins with fractal dimension 1.6
+        falpha=1.0
+    )
+
+    # Create aluminum element
+    element = musica.carma.CARMAElementConfig(
+        igroup=1,
+        isolute=0,
+        name="Aluminum",
+        shortname="ALUM",
+        itype=musica.carma.ParticleType.INVOLATILE,
+        icomposition=musica.carma.ParticleComposition.ALUMINUM,
+        rho=0.00395,  # kg/m3
+        arat=[1.0] * 5,  # 5 bins with area ratio 1.0
+        kappa=0.0,
+    )
+
+    # Create coagulation
+    coagulation = musica.carma.CARMACoagulationConfig(
+        igroup1=1,
+        igroup2=1,
+        igroup3=1,
+        algorithm=musica.carma.ParticleCollectionAlgorithm.FUCHS)
+
+    params = musica.carma.CARMAParameters(
+        nbin=5,
+        nz=1,
+        dtime=1800.0,
+        groups=[group],
+        elements=[element],
+        coagulations=[coagulation]
+    )
+
+    FIVE_DAYS_IN_SECONDS = 432000
+    params.nstep = FIVE_DAYS_IN_SECONDS // params.dtime
+    params.initialization.do_vtran = False
+
+    n_levels = params.nz
+    deltaz = 1000.0
+    zmin = 16500.0
+
+    vertical_center = zmin + (np.arange(n_levels) + 0.5) * deltaz
+    vertical_levels = zmin + np.arange(n_levels + 1) * deltaz
+
+    centered_variables = ussa1976.compute(z=vertical_center, variables=["t", "p", "rho"])
+    edge_variables = ussa1976.compute(z=vertical_levels, variables=["p"])
+
+    temperature = centered_variables.t.values
+    pressure = centered_variables.p.values
+    pressure_levels = edge_variables.p.values
+    density = centered_variables.rho.values
+
+    carma = musica.CARMA(params)
+
+    mmr_initial = 5e9 / (deltaz * 2.57474699e14) / density[0]
+
+    state = carma.create_state(
+        time_step=params.dtime,
+        temperature=temperature,
+        pressure=pressure,
+        pressure_levels=pressure_levels,
+        vertical_center=vertical_center,
+        vertical_levels=vertical_levels,
+        longitude=0.0,
+        latitude=-105.0,
+        coordinates=musica.carma.CarmaCoordinates.CARTESIAN,
+    )
+
+    for i in range(params.nbin):
+        for j in range(len(params.elements)):
+            state.set_bin(i + 1, j + 1, mmr_initial)
+
+    bin_data = state.get_bins()
+    bin_data = bin_data.expand_dims({"time": [0]})
+    env = state.get_environmental_values()
+    env = env.expand_dims({"time": [0]})
+
+    # Run the simulation for the specified number of steps
+    for step in range(1, int(params.nstep)):
+        state.step()
+        bin_data = xr.concat([bin_data, state.get_bins().expand_dims({"time": [step * params.dtime]})], dim="time")
+        env = xr.concat([env, state.get_environmental_values().expand_dims(
+            {"time": [step * params.dtime]})], dim="time")
+
+    return xr.merge([bin_data, env])
+
+
+if __name__ == '__main__':
+    if not available:
+        print("CARMA backend is not available.")
+    else:
+        state = run_carma_aluminum_example()
+        print(state)

musica/examples/carma_sulfate.py

@@ -0,0 +1,245 @@
+"""
+Python example for CARMA sulfate that mimics the logic of the CARMA Fortran test.
+
+This script creates one grid box with an initial concentration of sulfate particles
+at the smallest size, then allows that to grow using H2SO4 gas. The total mass
+of particles + gas should be conserved.
+
+Based on carma_sulfatetest.F90
+"""
+
+import xarray as xr
+import numpy as np
+import musica
+
+available = musica.backend.carma_available()
+
+def run_carma_sulfate_example():
+    """Test CARMA sulfate growth from gas condensation in a simple single grid box."""
+
+    GRAVITY = 9.806  # Acceleration due to gravity in m/s^2
+
+    # Simplified constants for debugging
+    NZ = 1
+    NELEM = 1
+    NBIN = 38
+
+    dtime = 1800.0  # Time step in seconds
+    deltaz = 10000.0  # Grid box height in meters
+    nsteps = int(180000 / dtime)
+
+    # Sulfate density
+    rho_sulfate_kg_m3 = 1923.0  # kg/m³
+
+    # Grid setup
+    latitude = -40.0
+    longitude = -105.0
+    vertical_center = [17000.0]
+    vertical_levels = [vertical_center[0] - deltaz, vertical_center[0] + deltaz]
+
+    # Standard atmosphere
+    pressure_centers = np.array([9000.0])
+    temperature_centers = np.array([250.0])
+    # this is directly from the original CARMA test, but it seems like there are some unit conversion issues
+    air_mass_density_centers = pressure_centers * 10.0 / (8.31430e07 / 28.966 * temperature_centers) * (1.0e-3 * 1.0e6)
+    pressure_levels = np.zeros(2)
+    pressure_levels[0] = pressure_centers[0] - \
+        (vertical_levels[0] - vertical_center[0]) * air_mass_density_centers[0] * GRAVITY
+    pressure_levels[1] = pressure_centers[0] - \
+        (vertical_levels[1] - vertical_center[0]) * air_mass_density_centers[0] * GRAVITY
+
+    # Initial mass mixing ratios
+    mass_mixing_ratios = {
+        "H2O": [1.0e-4],
+        "H2SO4": [0.1e-9 * (98.0 / 29.0)],
+        "SULFATE": [[0.0 for _ in range(NBIN)]]
+    }
+    satliq = {
+        "H2O": [-1.0],
+        "H2SO4": [-1.0]
+    }
+    satice = {
+        "H2O": [-1.0],
+        "H2SO4": [-1.0]
+    }
+
+    # Set up CARMA parameters
+    params = musica.CARMAParameters()
+    params.nz = NZ
+    params.nbin = NBIN
+
+    # Create sulfate group - simplified
+    sulfate_group = musica.carma.CARMAGroupConfig(
+        name="sulfate",
+        shortname="SULF",
+        rmin=2.e-10,  # Minimum radius in m
+        rmrat=2.0,   # Mass ratio between bins
+        swelling_approach={
+            "algorithm": musica.carma.ParticleSwellingAlgorithm.WEIGHT_PERCENT_H2SO4,
+            "composition": musica.carma.ParticleSwellingComposition.NONE
+        },
+        do_drydep=True,
+        is_sulfate=True
+    )
+    params.add_group(sulfate_group)
+
+    # Create sulfate element
+    sulfate_element = musica.carma.CARMAElementConfig(
+        igroup=1,
+        name="Sulfate",
+        shortname="SULF",
+        rho=rho_sulfate_kg_m3,
+        itype=musica.carma.ParticleType.VOLATILE,
+        icomposition=musica.carma.ParticleComposition.SULFURIC_ACID
+    )
+    params.add_element(sulfate_element)
+
+    # Create gases - simplified to match successful test_carma.py pattern
+    water_gas = musica.carma.CARMAGasConfig(
+        name="Water Vapor",
+        shortname="H2O",
+        wtmol=0.018015,  # kg/mol
+        ivaprtn=musica.carma.VaporizationAlgorithm.H2O_MURPHY_2005,
+        icomposition=musica.carma.GasComposition.H2O,
+        dgc_threshold=0.1,
+        ds_threshold=0.1
+    )
+    params.add_gas(water_gas)
+
+    # Create H2SO4 gas
+    h2so4_gas = musica.carma.CARMAGasConfig(
+        name="Sulfuric Acid",
+        shortname="H2SO4",
+        wtmol=0.098079,  # kg/mol
+        ivaprtn=musica.carma.VaporizationAlgorithm.H2SO4_AYERS_1980,
+        icomposition=musica.carma.GasComposition.H2SO4,
+        dgc_threshold=0.1,
+        ds_threshold=0.1
+    )
+    params.add_gas(h2so4_gas)
+
+    # Add growth process
+    growth = musica.carma.CARMAGrowthConfig(
+        ielem=1,  # Sulfate element
+        igas=2    # H2SO4 gas
+    )
+    params.add_growth(growth)
+
+    # Add nucleation process
+    nucleation = musica.carma.CARMANucleationConfig(
+        ielemfrom=1,
+        ielemto=1,
+        algorithm=musica.carma.ParticleNucleationAlgorithm.HOMOGENEOUS_NUCLEATION,
+        rlh_nuc=0.0,
+        igas=2  # H2SO4 gas
+    )
+    params.add_nucleation(nucleation)
+
+    # Add coagulation
+    coagulation = musica.carma.CARMACoagulationConfig(
+        igroup1=1,
+        igroup2=1,
+        igroup3=1,
+        algorithm=musica.carma.ParticleCollectionAlgorithm.FUCHS
+    )
+    params.add_coagulation(coagulation)
+
+    # Initialization
+    params.initialization.do_substep = True
+    params.initialization.do_thermo = True
+    params.initialization.maxretries = 16
+    params.initialization.maxsubsteps = 32
+    params.initialization.dt_threshold = 1.0
+    params.initialization.sulfnucl_method = musica.carma.SulfateNucleationMethod.ZHAO_TURCO.value
+
+    # Create CARMA instance
+    carma = musica.CARMA(params)
+
+    # Output group properties
+    group_props, _ = carma.get_group_properties()
+    # Print bin radius and bin mass from group_props xarray Dataset
+    for i_bin in range(NBIN):
+        print(
+            f"Bin {i_bin + 1}: bin radius = {group_props.isel(bin=i_bin)['bin_radius']}; bin mass = {group_props.isel(bin=i_bin)['bin_mass']}"
+        )
+
+    bin_state = None
+    gas_state = None
+    env_state = None
+
+    for i_step in range(nsteps):
+
+        # Create state
+        state = carma.create_state(
+            time_step=dtime,
+            temperature=temperature_centers,
+            original_temperature=temperature_centers,
+            pressure=pressure_centers,
+            pressure_levels=pressure_levels,
+            vertical_center=vertical_center,
+            vertical_levels=vertical_levels,
+            longitude=longitude,
+            latitude=latitude,
+            coordinates=musica.carma.CarmaCoordinates.CARTESIAN,
+            specific_humidity=mass_mixing_ratios["H2O"],
+        )
+
+        # Initialize particle concentrations to zero
+        for ibin in range(1, NBIN + 1):
+            for ielem in range(1, NELEM + 1):
+                state.set_bin(ibin, ielem, mass_mixing_ratios["SULFATE"][0][ibin - 1])
+
+        # Set H2O concentration
+        state.set_gas(
+            gas_index=1,
+            value=mass_mixing_ratios["H2O"],
+            old_mmr=mass_mixing_ratios["H2O"],
+            gas_saturation_wrt_ice=satice["H2O"],
+            gas_saturation_wrt_liquid=satliq["H2O"],
+        )
+
+        # Set H2SO4 concentration
+        state.set_gas(
+            gas_index=2,
+            value=[mmr * 1.05 for mmr in mass_mixing_ratios["H2SO4"]],
+            old_mmr=mass_mixing_ratios["H2SO4"],
+            gas_saturation_wrt_ice=satice["H2SO4"],
+            gas_saturation_wrt_liquid=satliq["H2SO4"],
+        )
+
+        # Perform model step
+        state.step()
+        stats = state.get_step_statistics()
+        print(f"Step {i_step + 1}/{nsteps}: {stats}")
+
+        # Get updated state values
+        if bin_state is None:
+            bin_state = state.get_bins()
+            bin_state = bin_state.expand_dims({"time": [i_step * dtime]})
+        else:
+            bin_state = xr.concat([bin_state, state.get_bins().expand_dims({"time": [i_step * dtime]})], dim="time")
+
+        if gas_state is None:
+            gas_state = state.get_gases()[0]
+            gas_state = gas_state.expand_dims({"time": [i_step * dtime]})
+        else:
+            gas_state = xr.concat([gas_state, state.get_gases()[0].expand_dims({"time": [i_step * dtime]})], dim="time")
+
+        if env_state is None:
+            env_state = state.get_environmental_values()
+            env_state = env_state.expand_dims({"time": [i_step * dtime]})
+        else:
+            env_state = xr.concat([env_state, state.get_environmental_values(
+            ).expand_dims({"time": [i_step * dtime]})], dim="time")
+
+    return env_state, gas_state, bin_state
+
+
+if __name__ == '__main__':
+    if not available:
+        print("CARMA backend is not available.")
+    else:
+        env_state, gas_state, bin_state = run_carma_sulfate_example()
+        print(env_state)
+        print(gas_state)
+        print(bin_state)

musica/examples/examples.py

@@ -0,0 +1,165 @@
+"""MUSICA Examples Module.
+
+This module provides a centralized way to access and manage MUSICA examples.
+It defines the Example class for representing individual examples and the
+Examples singleton for accessing all available examples.
+
+Example:
+    >>> from musica.examples import Examples
+    >>> print(Examples.TS1LatinHyperCube)
+    >>> for example in Examples:
+    ...     print(example.name)
+"""
+
+
+class Example:
+    """A class representing a MUSICA example.
+
+    This class encapsulates information about a specific example, including its name,
+    short name, description, and file path. It provides methods for string representation
+    and class-based construction.
+    """
+
+    def __init__(self, name, short_name, description, path):
+        """Initialize an Example instance.
+
+        Args:
+            name (str): The display name of the example.
+            short_name (str): A short identifier for the example.
+            description (str): A detailed description of what the example demonstrates.
+            path (str): The file path to the example script.
+        """
+        self.name = name
+        self.short_name = short_name
+        self.description = description
+        self.path = path
+
+    def __str__(self):
+        """Return a string representation of the example.
+
+        Returns:
+            str: A formatted string showing the name and description.
+        """
+        return f'{self.name}: {self.description}'
+
+    def __repr__(self):
+        """Return a string representation of the example for debugging.
+
+        Returns:
+            str: A formatted string showing the name and description.
+        """
+        return f'{self.name}: {self.description}'
+
+    @classmethod
+    def from_config(cls, display_name, path, short_name, description):
+        """Create an Example instance from configuration parameters.
+
+        This class method provides an alternative constructor that creates an Example
+        instance with more explicit parameter naming.
+
+        Args:
+            display_name (str): The display name of the example.
+            path (str): The file path to the example script.
+            short_name (str): A short identifier for the example.
+            description (str): A detailed description of what the example demonstrates.
+
+        Returns:
+            Example: A new Example instance with the provided configuration.
+        """
+        return cls(name=display_name, short_name=short_name, description=description, path=path)
+
+
+class _Examples:
+    """A container class for managing MUSICA examples.
+
+    This class provides a centralized way to access and manage all available MUSICA
+    examples. It includes predefined examples and supports iteration, indexing, and
+    attribute access patterns.
+    """
+    CARMA_Aluminum = Example.from_config(
+        display_name='CARMA Aluminum',
+        short_name='CARMA_Aluminum',
+        path='carma_aluminum.py',
+        description='A CARMA example for simulating aluminum aerosol particles.')
+    CARMA_Sulfate = Example.from_config(
+        display_name='CARMA Sulfate',
+        short_name='CARMA_Sulfate',
+        path='carma_sulfate.py',
+        description='A CARMA example for simulating sulfate aerosol particles.')
+    Sulfate_Box_Model = Example.from_config(
+        display_name='Sulfate Box Model',
+        short_name='Sulfate_Box_Model',
+        path='sulfate_box_model.py',
+        description='A box model example for simulating sulfate aerosol particles.')
+    TS1LatinHyperCube = Example.from_config(
+        display_name='TS1 Latin Hypercube',
+        short_name='TS1LatinHyperCube',
+        path='ts1_latin_hypercube.py',
+        description='A Latin hypercube sampling example for the TS1 mechanism. This script shows how to sample an input space and run multiple box models in parallel on a single mechanism.')
+
+    @classmethod
+    def get_all(cls):
+        """Get all available examples.
+
+        Returns:
+            list[Example]: A list of all available Example instances.
+        """
+        return [cls.CARMA_Aluminum, cls.CARMA_Sulfate, cls.Sulfate_Box_Model, cls.TS1LatinHyperCube]
+
+    def __iter__(self):
+        """Make the class iterable over examples.
+
+        Returns:
+            iterator: An iterator over all available examples.
+        """
+        return iter(self.get_all())
+
+    def __getattr__(self, item):
+        """Handle attribute access for examples.
+
+        Args:
+            item (str): The attribute name to access.
+
+        Returns:
+            Any: The requested attribute value.
+
+        Raises:
+            AttributeError: If the attribute doesn't exist.
+        """
+        # Check if the attribute exists in the class definition
+        if hasattr(self.__class__, item):
+            return getattr(self.__class__, item)
+        raise AttributeError(f"'{self.__class__.__name__}' object has no attribute '{item}'")
+
+    def __getitem__(self, item):
+        """Support indexing to access examples by position.
+
+        Args:
+            item (int): The index of the example to retrieve.
+
+        Returns:
+            Example: The example at the specified index.
+
+        Raises:
+            IndexError: If the index is out of range.
+        """
+        return self.get_all()[item]
+
+    def __repr__(self):
+        """Return a string representation for debugging.
+
+        Returns:
+            str: A formatted string showing all available examples.
+        """
+        return f'Examples: {self.get_all()}'
+
+    def __str__(self):
+        """Return a string representation of the examples collection.
+
+        Returns:
+            str: A formatted string showing all available examples.
+        """
+        return f'Examples: {self.get_all()}'
+
+
+Examples = _Examples()