MUSICA Python API#

C++ Bindings#

Core#

Wrapper classes for MUSICA C library structs and functions

class musica._musica._core.VectorConditions#

Bases: pybind11_object

_pybind11_conduit_v1_()#

append(self: musica._musica._core.VectorConditions, x: micm::Conditions) → None#: Add an item to the end of the list

clear(self: musica._musica._core.VectorConditions) → None#: Clear the contents

extend(*args, **kwargs)#

Overloaded function.

extend(self: musica._musica._core.VectorConditions, L: musica._musica._core.VectorConditions) -> None

Extend the list by appending all the items in the given list

extend(self: musica._musica._core.VectorConditions, L: collections.abc.Iterable) -> None

Extend the list by appending all the items in the given list

insert(self: musica._musica._core.VectorConditions, i: typing.SupportsInt, x: micm::Conditions) → None#: Insert an item at a given position.

pop(*args, **kwargs)#

Overloaded function.

pop(self: musica._musica._core.VectorConditions) -> micm::Conditions

Remove and return the last item

pop(self: musica._musica._core.VectorConditions, i: typing.SupportsInt) -> micm::Conditions

Remove and return the item at index i

class musica._musica._core._Conditions#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property air_density#

property pressure#

property temperature#

class musica._musica._core._Solver#

Bases: pybind11_object

_pybind11_conduit_v1_()#

class musica._musica._core._State#

Bases: pybind11_object

_pybind11_conduit_v1_()#

concentration_strides(self: musica._musica._core._State) → tuple[int, int]#

property concentrations#: native 1D list of concentrations, ordered by species and grid cell according to matrix type

property conditions#: list of conditions structs for each grid cell

number_of_grid_cells(self: musica._musica._core._State) → int#

user_defined_rate_parameter_strides(self: musica._musica._core._State) → tuple[int, int]#

property user_defined_rate_parameters#: native 1D list of user-defined rate parameters, ordered by parameter and grid cell according to matrix type

musica._musica._core._create_solver(arg0: str, arg1: musica._musica._core._SolverType) → musica._musica._core._Solver#

musica._musica._core._create_solver_from_mechanism(arg0: mechanism_configuration::v1::types::Mechanism, arg1: musica._musica._core._SolverType, arg2: bool) → musica._musica._core._Solver#

musica._musica._core._create_state(arg0: musica._musica._core._Solver, arg1: SupportsInt) → musica._musica._core._State#

musica._musica._core._is_cuda_available(*args, **kwargs)#

Overloaded function.

_is_cuda_available() -> bool

Check if CUDA is available

_is_cuda_available() -> bool

Check if CUDA is available

musica._musica._core._micm_solve(arg0: musica._musica._core._Solver, arg1: musica._musica._core._State, arg2: SupportsFloat) → None#: Solve the chemistry system

musica._musica._core._print_state(arg0: musica._musica._core._State, arg1: SupportsFloat) → None#: Print the state to stdout with the current time

musica._musica._core._species_ordering(arg0: musica._musica._core._State) → dict[str, int]#: Return map of species names to their indices in the state concentrations vector

musica._musica._core._user_defined_rate_parameters_ordering(arg0: musica._musica._core._State) → dict[str, int]#: Return map of reaction rate parameters to their indices in the state user-defined rate parameters vector

musica._musica._core._vector_size(arg0: musica._musica._core._SolverType) → int#: Returns the vector dimension for vector-ordered solvers, 0 otherwise.

class musica._musica._core._SolverType#

Bases: pybind11_object

Members:

rosenbrock

rosenbrock_standard_order

backward_euler

backward_euler_standard_order

cuda_rosenbrock

_pybind11_conduit_v1_()#

backward_euler = <_SolverType.backward_euler: 3>#

backward_euler_standard_order = <_SolverType.backward_euler_standard_order: 4>#

cuda_rosenbrock = <_SolverType.cuda_rosenbrock: 5>#

property name#

rosenbrock = <_SolverType.rosenbrock: 1>#

rosenbrock_standard_order = <_SolverType.rosenbrock_standard_order: 2>#

property value#

Mechanism Configuration#

Wrapper classes for Mechanism Configuration library structs and functions

Bases: pybind11_object

A class representing an Arrhenius rate constant.

k = A * exp( C / T ) * ( T / D )^B * exp( 1 - E * P )

where:: k = rate constant A = pre-exponential factor [(mol m-3)^(n-1)s-1] B = temperature exponent [unitless] C = exponential term [K-1] D = reference temperature [K] E = pressure scaling term [Pa-1] T = temperature [K] P = pressure [Pa] n = number of reactants

name#

The name of the Arrhenius rate constant.

Type:: str

A#

Pre-exponential factor [(mol m-3)^(n-1)s-1] where n is the number of reactants.

Type:: float

B#

Temperature exponent [unitless].

Type:: float

C#

Exponential term [K-1].

Type:: float

D#

Reference Temperature [K].

Type:: float

E#

Pressure scaling term [Pa-1].

Type:: float

reactants#

A list of reactants involved in the reaction.

Type:: List[Union[Species, Tuple[float, Species]]]

products#

A list of products formed in the reaction.

Type:: List[Union[Species, Tuple[float, Species]]]

gas_phase#

The gas phase in which the reaction occurs.

Type:: Phase

other_properties#

A dictionary of other properties of the Arrhenius rate constant.

Type:: Dict[str, Any]

property A#

property B#

property C#

property D#

property E#

_pybind11_conduit_v1_()#

property gas_phase#

property name#

property other_properties#

property products#

property reactants#

serialize() → Dict#

Serialize the Arrhenius object to a dictionary using only Python-visible data.

Returns:: A dictionary representation of the Arrhenius object.
Return type:: Dict

property type#: Get the reaction type.

Bases: pybind11_object

A class representing a branched reaction rate constant.

name#

The name of the branched reaction rate constant.

Type:: str

X#

Pre-exponential branching factor [(mol m-3)^-(n-1)s-1].

Type:: float

Y#

Exponential branching factor [K-1].

Type:: float

a0#

Z parameter [unitless].

Type:: float

n#

A parameter [unitless].

Type:: float

reactants#

A list of reactants involved in the reaction.

Type:: List[Union[Species, Tuple[float, Species]]]

nitrate_products#

A list of products formed in the nitrate branch.

Type:: List[Union[Species, Tuple[float, Species]]]

alkoxy_products#

A list of products formed in the alkoxy branch.

Type:: List[Union[Species, Tuple[float, Species]]]

gas_phase#

The gas phase in which the reaction occurs.

Type:: Phase

other_properties#

A dictionary of other properties of the branched reaction rate constant.

Type:: Dict[str, Any]

property X#

property Y#

_pybind11_conduit_v1_()#

property a0#

property alkoxy_products#

property gas_phase#

property n#

property name#

property nitrate_products#

property other_properties#

property reactants#

serialize() → Dict#

Serialize the Branched object to a dictionary using only Python-visible data.

Returns:: A dictionary representation of the Branched object.
Return type:: Dict

property type#: Get the reaction type.

Bases: pybind11_object

A class representing an emission reaction rate constant.

name#

The name of the emission reaction rate constant.

Type:: str

scaling_factor#

The scaling factor for the emission rate constant.

Type:: float

products#

A list of products formed in the reaction.

Type:: List[Union[Species, Tuple[float, Species]]]

gas_phase#

The gas phase in which the reaction occurs.

Type:: Phase

other_properties#

A dictionary of other properties of the emission reaction rate constant.

Type:: Dict[str, Any]

_pybind11_conduit_v1_()#

property gas_phase#

property name#

property other_properties#

property products#

property scaling_factor#

serialize() → Dict#

property type#

Bases: pybind11_object

A class representing a first-order loss reaction rate constant.

name#

The name of the first-order loss reaction rate constant.

Type:: str

scaling_factor#

The scaling factor for the first-order loss rate constant.

Type:: float

reactants#

A list of reactants involved in the reaction.

Type:: List[Union[Species, Tuple[float, Species]]]

gas_phase#

The gas phase in which the reaction occurs.

Type:: Phase

other_properties#

A dictionary of other properties of the first-order loss reaction rate constant.

Type:: Dict[str, Any]

_pybind11_conduit_v1_()#

property gas_phase#

property name#

property other_properties#

property reactants#

property scaling_factor#

serialize() → Dict#

Serialize the FirstOrderLoss object to a dictionary using only Python-visible data.

Returns:: A dictionary representation of the FirstOrderLoss object.
Return type:: Dict

property type#

Bases: pybind11_object

A class representing a chemical mechanism.

name#

The name of the mechanism.

Type:: str

reactions#

A list of reactions in the mechanism.

Type:: List[Reaction]

species#

A list of species in the mechanism.

Type:: List[Species]

phases#

A list of phases in the mechanism.

Type:: List[Phase]

version#

The version of the mechanism.

Type:: Version

_pybind11_conduit_v1_()#

export(file_path: str) → None#

property name#

property phases#

property reactions#

serialize() → Dict#

property species#

property version#

class musica._musica._mechanism_configuration._Parser#

Bases: pybind11_object

_pybind11_conduit_v1_()#

parse(self: musica._musica._mechanism_configuration._Parser, arg0: str) → musica._musica._mechanism_configuration._Mechanism#

parse_and_convert_v0(self: musica._musica._mechanism_configuration._Parser, arg0: str) → musica._musica._mechanism_configuration._Mechanism#: Parse a v0 mechanism configuration file

class musica._musica._mechanism_configuration._Phase(name: str | None = None, species: List[_Species] | List[_PhaseSpecies] | None = None, other_properties: Dict[str, Any] | None = None)#

Bases: pybind11_object

A class representing a phase in a chemical mechanism.

name#

The name of the phase.

Type:: str

species#

A list of species in the phase.

Type:: List[Species]

other_properties#

A dictionary of other properties of the phase.

Type:: Dict[str, Any]

_pybind11_conduit_v1_()#

property name#

property other_properties#

serialize()#

property species#

class musica._musica._mechanism_configuration._PhaseSpecies(name: str | None = None, diffusion_coefficient_m2_s: float | None = None, other_properties: Dict[str, Any] | None = None)#

Bases: pybind11_object

Represents a chemical species within a specific phase of a mechanism, including phase-specific properties such as diffusion coefficients.

This class is distinct from a regular Species class in that it models properties relevant to the species’ behavior in a particular phase (e.g., gas, liquid, or solid), such as the diffusion coefficient.

name#

The name of the species.

Type:: str

diffusion_coefficient_m2_s#

Diffusion coefficient in the phase [m2 s-1].

Type:: float

other_properties#

A dictionary of other phase-specific properties of the species.

Type:: Dict[str, Any]

_pybind11_conduit_v1_()#

property diffusion_coefficient_m2_s#

property name#

property other_properties#

serialize() → Dict#

Bases: pybind11_object

A class representing a photolysis reaction rate constant.

name#

The name of the photolysis reaction rate constant.

Type:: str

scaling_factor#

The scaling factor for the photolysis rate constant.

Type:: float

reactants#

A list of reactants involved in the reaction.

Type:: List[Union[Species, Tuple[float, Species]]]

products#

A list of products formed in the reaction.

Type:: List[Union[Species, Tuple[float, Species]]]

gas_phase#

The gas phase in which the reaction occurs.

Type:: Phase

other_properties#

A dictionary of other properties of the photolysis reaction rate constant.

Type:: Dict[str, Any]

_pybind11_conduit_v1_()#

property gas_phase#

property name#

property other_properties#

property products#

property reactants#

property scaling_factor#

serialize() → Dict#

property type#

class musica._musica._mechanism_configuration._ReactionComponent(name: str | None = None, coefficient: float | None = 1.0, other_properties: Dict[str, Any] | None = None)#

Bases: pybind11_object

A class representing a reaction component in a chemical reaction.

A reaction component typically consists of a chemical species, its stoichiometric coefficient in the reaction, and any additional properties relevant to its role in the reaction.

species_name#

The name of the chemical species involved in the reaction.

Type:: str

coefficient#

The stoichiometric coefficient of the species in the reaction.

Type:: float

other_properties#

A dictionary of other properties relevant to the reaction component.

Type:: Dict[str, Any]

_pybind11_conduit_v1_()#

property coefficient#

property other_properties#

serialize() → Dict#

property species_name#

class musica._musica._mechanism_configuration._Reactions(reactions: List[Any] | None = None)#

Bases: pybind11_object

A class representing a collection of reactions in a chemical mechanism.

reactions#

A list of reactions in the mechanism.

Type:: List[Any]

_pybind11_conduit_v1_()#

property arrhenius#

property branched#

property emission#

property first_order_loss#

property photolysis#

property surface#

property taylor_series#

property ternary_chemical_activation#

property troe#

property tunneling#

property user_defined#

class musica._musica._mechanism_configuration._ReactionsIterator#

Bases: pybind11_object

_pybind11_conduit_v1_()#

class musica._musica._mechanism_configuration._Species(name: str | None = None, molecular_weight_kg_mol: float | None = None, constant_concentration_mol_m3: float | None = None, constant_mixing_ratio_mol_mol: float | None = None, is_third_body: bool | None = False, other_properties: Dict[str, Any] | None = None)#

Bases: pybind11_object

A class representing a species in a chemical mechanism.

name#

The name of the species.

Type:: str

molecular_weight_kg_mol#

Molecular weight [kg mol-1]

Type:: float

constant_concentration_mol_m3#

Constant concentration of the species (mol m-3)

Type:: float

constant_mixing_ratio_mol_mol#

Constant mixing ratio of the species (mol mol-1)

Type:: float

is_third_body#

Whether the species is a third body.

Type:: bool

other_properties#

A dictionary of other properties of the species.

Type:: Dict[str, Any]

_pybind11_conduit_v1_()#

property constant_concentration_mol_m3#

property constant_mixing_ratio_mol_mol#

property is_third_body#

property molecular_weight_kg_mol#

property name#

property other_properties#

serialize() → Dict#

Bases: pybind11_object

A class representing a surface in a chemical mechanism.

name#

The name of the surface.

Type:: str

reaction_probability#

The probability of a reaction occurring on the surface.

Type:: float

gas_phase_species#

The gas phase species involved in the reaction.

Type:: Union[Species, Tuple[float, Species]]

gas_phase_products#

The gas phase products formed in the reaction.

Type:: List[Union[Species, Tuple[float, Species]]]

gas_phase#

The gas phase in which the reaction occurs.

Type:: Phase

other_properties#

A dictionary of other properties of the surface.

Type:: Dict[str, Any]

_pybind11_conduit_v1_()#

property gas_phase#

property gas_phase_products#

property gas_phase_species#

property name#

property other_properties#

property reaction_probability#

serialize() → Dict#

property type#

Bases: pybind11_object

A class representing a Taylor series rate constant.

The rate constant k is represented as a Taylor series expansion in temperature (and optionally other variables):

k = a0 + a1*T + a2*T^2 + a3*T^3 + … + an*T^n

where:: k = rate constant T = temperature [K] a0, a1, …, an = Taylor series coefficients

Optionally, additional parameters (A, B, C, D, E) may be provided for compatibility or extended forms.

name#

The name of the Taylor series rate constant.

Type:: str

taylor_coefficients#

Coefficients [a0, a1, …, an] for the Taylor series expansion.

Type:: List[float]

A#

Optional parameter for extended forms.

Type:: float, optional

B#

Optional parameter for extended forms.

Type:: float, optional

C#

Optional parameter for extended forms.

Type:: float, optional

D#

Optional parameter for extended forms.

Type:: float, optional

E#

Optional parameter for extended forms.

Type:: float, optional

reactants#

A list of reactants involved in the reaction.

Type:: List[Union[Species, Tuple[float, Species]]]

products#

A list of products formed in the reaction.

Type:: List[Union[Species, Tuple[float, Species]]]

gas_phase#

The gas phase in which the reaction occurs.

Type:: Phase

other_properties#

A dictionary of other properties of the Taylor series rate constant.

Type:: Dict[str, Any]

property A#

property B#

property C#

property D#

property E#

_pybind11_conduit_v1_()#

property gas_phase#

property name#

property other_properties#

property products#

property reactants#

serialize() → Dict#

property taylor_coefficients#

property type#

Bases: pybind11_object

A class representing a Ternary Chemical Activation rate constant.

name#

The name of the Ternary Chemical Activation rate constant.

Type:: str

k0_A#

Pre-exponential factor for the low-pressure limit [(mol m-3)^(n-1)s-1].

Type:: float

k0_B#

Temperature exponent for the low-pressure limit [unitless].

Type:: float

k0_C#

Exponential term for the low-pressure limit [K-1].

Type:: float

kinf_A#

Pre-exponential factor for the high-pressure limit [(mol m-3)^(n-1)s-1].

Type:: float

kinf_B#

Temperature exponent for the high-pressure limit [unitless].

Type:: float

kinf_C#

Exponential term for the high-pressure limit [K-1].

Type:: float

Fc#

Ternary Chemical Activation parameter [unitless].

Type:: float

N#

Ternary Chemical Activation parameter [unitless].

Type:: float

reactants#

A list of reactants involved in the reaction.

Type:: List[Union[Species, Tuple[float, Species]]]

products#

A list of products formed in the reaction.

Type:: List[Union[Species, Tuple[float, Species]]]

gas_phase#

The gas phase in which the reaction occurs.

Type:: Phase

other_properties#

A dictionary of other properties of the Ternary Chemical Activation rate constant.

Type:: Dict[str, Any]

property Fc#

property N#

_pybind11_conduit_v1_()#

property gas_phase#

property k0_A#

property k0_B#

property k0_C#

property kinf_A#

property kinf_B#

property kinf_C#

property name#

property other_properties#

property products#

property reactants#

serialize() → Dict#

Serialize the Ternary Chemical Activation object to a dictionary using only Python-visible data.

Returns:: A dictionary representation of the Ternary Chemical Activation object.
Return type:: Dict

property type#

Bases: pybind11_object

A class representing a Troe rate constant.

name#

The name of the Troe rate constant.

Type:: str

k0_A#

Pre-exponential factor for the low-pressure limit [(mol m-3)^(n-1)s-1].

Type:: float

k0_B#

Temperature exponent for the low-pressure limit [unitless].

Type:: float

k0_C#

Exponential term for the low-pressure limit [K-1].

Type:: float

kinf_A#

Pre-exponential factor for the high-pressure limit [(mol m-3)^(n-1)s-1].

Type:: float

kinf_B#

Temperature exponent for the high-pressure limit [unitless].

Type:: float

kinf_C#

Exponential term for the high-pressure limit [K-1].

Type:: float

Fc#

Troe parameter [unitless].

Type:: float

N#

Troe parameter [unitless].

Type:: float

reactants#

A list of reactants involved in the reaction.

Type:: List[Union[Species, Tuple[float, Species]]]

products#

A list of products formed in the reaction.

Type:: List[Union[Species, Tuple[float, Species]]]

gas_phase#

The gas phase in which the reaction occurs.

Type:: Phase

other_properties#

A dictionary of other properties of the Troe rate constant.

Type:: Dict[str, Any]

property Fc#

property N#

_pybind11_conduit_v1_()#

property gas_phase#

property k0_A#

property k0_B#

property k0_C#

property kinf_A#

property kinf_B#

property kinf_C#

property name#

property other_properties#

property products#

property reactants#

serialize() → Dict#

Serialize the Troe object to a dictionary using only Python-visible data.

Returns:: A dictionary representation of the Troe object.
Return type:: Dict

property type#

Bases: pybind11_object

A class representing a quantum tunneling reaction rate constant.

k = A * exp( -B / T ) * exp( C / T^3 )

where:: k = rate constant A = pre-exponential factor [(mol m-3)^(n-1)s-1] B = tunneling parameter [K^-1] C = tunneling parameter [K^-3] T = temperature [K] n = number of reactants

name#

The name of the tunneling reaction rate constant.

Type:: str

A#

Pre-exponential factor [(mol m-3)^(n-1)s-1].

Type:: float

B#

Tunneling parameter [K^-1].

Type:: float

C#

Tunneling parameter [K^-3].

Type:: float

reactants#

A list of reactants involved in the reaction.

Type:: List[Union[Species, Tuple[float, Species]]]

products#

A list of products formed in the reaction.

Type:: List[Union[Species, Tuple[float, Species]]]

gas_phase#

The gas phase in which the reaction occurs.

Type:: Phase

other_properties#

A dictionary of other properties of the tunneling reaction rate constant.

Type:: Dict[str, Any]

property A#

property B#

property C#

_pybind11_conduit_v1_()#

property gas_phase#

property name#

property other_properties#

property products#

property reactants#

serialize() → Dict#

Serialize the Tunneling object to a dictionary using only Python-visible data.

Returns:: A dictionary representation of the Tunneling object.
Return type:: Dict

property type#

Bases: pybind11_object

A class representing a user-defined reaction rate constant.

name#

The name of the photolysis reaction rate constant.

Type:: str

scaling_factor#

The scaling factor for the photolysis rate constant.

Type:: float

reactants#

A list of reactants involved in the reaction.

Type:: List[Union[Species, Tuple[float, Species]]]

products#

A list of products formed in the reaction.

Type:: List[Union[Species, Tuple[float, Species]]]

gas_phase#

The gas phase in which the reaction occurs.

Type:: Phase

other_properties#

A dictionary of other properties of the photolysis reaction rate constant.

Type:: Dict[str, Any]

_pybind11_conduit_v1_()#

property gas_phase#

property name#

property other_properties#

property products#

property reactants#

property scaling_factor#

serialize() → Dict#

property type#

class musica._musica._mechanism_configuration._Version#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property major#

property minor#

property patch#

to_string(self: musica._musica._mechanism_configuration._Version) → str#

class musica._musica._mechanism_configuration._ReactionType#

Bases: pybind11_object

Members:

Arrhenius

Branched

Emission

FirstOrderLoss

Photolysis

Surface

TaylorSeries

TernaryChemicalActivation

Troe

Tunneling

UserDefined

Arrhenius = <_ReactionType.Arrhenius: 0>#

Branched = <_ReactionType.Branched: 1>#

Emission = <_ReactionType.Emission: 2>#

FirstOrderLoss = <_ReactionType.FirstOrderLoss: 3>#

Photolysis = <_ReactionType.Photolysis: 4>#

Surface = <_ReactionType.Surface: 5>#

TaylorSeries = <_ReactionType.TaylorSeries: 6>#

TernaryChemicalActivation = <_ReactionType.TernaryChemicalActivation: 7>#

Troe = <_ReactionType.Troe: 8>#

Tunneling = <_ReactionType.Tunneling: 9>#

UserDefined = <_ReactionType.UserDefined: 10>#

_pybind11_conduit_v1_()#

property name#

property value#

Musica Types#

class musica.types.Conditions(temperature: float | int | None = None, pressure: float | int | None = None, air_density: float | int | None = None)#

Bases: _Conditions

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.

Parameters:

temperature (float) – Temperature in Kelvin.
pressure (float) – Pressure in Pascals.
air_density (float) – Air density in mol m-3

class musica.types.MICM(config_path: str | PathLike[str] = None, mechanism: _Mechanism = None, solver_type: Any = None, ignore_non_gas_phases: bool = True)#

Bases: object

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.

create_state(number_of_grid_cells: int = 1) → State#

Create a new state object.

Returns:: A new state object.
Return type:: State

solve(state: State, time_step: float)#

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:

Updated state object after solving the system of equations.

Return type:

State

solver_type() → SolverType#

Get the type of solver used.

Returns:: The type of solver used.
Return type:: SolverType

class musica.types.SolverType#

Bases: _SolverType

Enum class for the type of solver to use.

class musica.types.State(solver: Any, number_of_grid_cells: int, vector_size: int = 0)#

Bases: object

State class for the MICM solver. It contains the initial conditions and species concentrations.

get_concentrations() → Dict[str, List[float]]#

Get the concentrations of the species in the state.

Returns:: Dictionary of species names and their concentrations.
Return type:: Dict[str, List[float]]

get_conditions() → Dict[str, List[float]]#

Get the conditions for the state.

Returns:: Dictionary of conditions names and their values.
Return type:: Dict[str, List[float]]

get_internal_states() → List[Any]#

Get the internal states of the MICM solver.

Returns:: List of internal states.
Return type:: List[_State]

get_species_ordering() → Dict[str, int]#

Get the species ordering for the state.

Returns:: Dictionary of species names and their indices.
Return type:: Dict[str, int]

get_user_defined_rate_parameters() → Dict[str, List[float]]#

Get the user-defined rate parameters in the state.

Returns:: Dictionary of user-defined rate parameter names and their values.
Return type:: Dict[str, List[float]]

get_user_defined_rate_parameters_ordering() → Dict[str, int]#

Get the user-defined rate parameters ordering for the state.

Returns:: Dictionary of user-defined rate parameter names and their indices.
Return type:: Dict[str, int]

set_concentrations(concentrations: Dict[str, float | int | List[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.

set_conditions(temperatures: float | int | List[float | int] | None = None, pressures: float | int | List[float | int] | None = None, air_densities: float | int | List[float | int] | None = 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.

set_user_defined_rate_parameters(user_defined_rate_parameters: Dict[str, float | int | List[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.

musica.types.is_scalar_number(x)#

TUVX#

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.

class musica.tuvx.TUVX(config_path: str | None = None, config_string: str | None = None)#

Bases: object

A Python interface to the TUV-x photolysis calculator.

This class provides a simplified interface that only requires a JSON/YAML configuration to set up and run TUV-x calculations. All parameters (solar zenith angle, earth-sun distance, atmospheric profiles, etc.) are specified in the JSON/YAML configuration.

The configuration can be in a file or provided as a string. Exactly one of config_path or config_string must be provided.

static create_config_from_dict(config_dict: Dict) → TUVX#

Create a TUVX instance from a configuration dictionary.

Parameters:

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

static create_config_from_json_string(json_string: str) → TUVX#

Create a TUVX instance from a JSON configuration string.

Parameters:

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

property dose_rate_names: dict[str, int]#

Get the names of dose rates.

Returns:: Dictionary mapping dose rate names to their indices in the output arrays

get_dose_rate(rate_name: str, dose_rates: ndarray) → ndarray#

Extract dose rates for a specific rate type.

Parameters:

rate_name – Name of the dose rate
dose_rates – Output from run() method

Returns:

1D array of dose rates for all layers [W m^-2]

Raises:

KeyError – If rate_name is not found

get_heating_rate(rate_name: str, heating_rates: ndarray) → ndarray#

Extract heating rates for a specific rate type.

Parameters:

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

get_photolysis_rate_constant(reaction_name: str, photolysis_rates: ndarray) → ndarray#

Extract photolysis rate constants for a specific reaction.

Parameters:

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

property heating_rate_names: dict[str, int]#

Get the names of heating rates.

Returns:: Dictionary mapping heating rate names to their indices in the output arrays

property photolysis_rate_names: dict[str, int]#

Get the names of photolysis rates.

Returns:: Dictionary mapping photolysis rate names to their indices in the output arrays

run() → Tuple[ndarray, ndarray, 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_sza, n_layers, n_reactions) [s^-1] - heating_rates: Shape (n_sza, n_layers, n_heating_rates) [K s^-1] - dose_rates: Shape (n_sza, n_layers, n_dose_rates) [W m^-2]

CARMA#

CARMA aerosol model Python interface.

This module provides a simplified Python interface to the CARMA aerosol model. It allows users to create a CARMA instance and run simulations with specified parameters.

Note: CARMA is only available on macOS and Linux platforms.

class musica.carma.CARMA(parameters: CARMAParameters)#

Bases: object

A Python interface to the CARMA aerosol model.

This class provides a simplified interface for running CARMA simulations with configurable parameters.

create_state(**kwargs) → CARMAState#

Create a CARMAState instance based on the current parameters.

Parameters:: **kwargs – Additional keyword arguments to pass to CARMAState
Returns:: Instance containing environmental variables for the simulation
Return type:: CARMAState

get_element_properties() → Tuple[Dataset, Dict[str, int]]#

Get the element properties for all elements

Returns:: The properties for each element and a dictionary of element indices
Return type:: Tuple[xr.Dataset, Dict[str, Any]]

get_gas_properties() → CARMAGasConfig#

Get the gas properties for all gases.

Returns:: The gas configurations
Return type:: CARMAGasConfig

get_group_properties() → Tuple[Dataset, Dict[str, int]]#

Get the group properties for all groups.

Returns:: The group properties for all groups and a dictionary with their indices
Return type:: Tuple[xr.Dataset, Dict[str, int]]

get_solute_properties() → CARMASoluteConfig#

Get the solute properties for all solutes.

Returns:: The solute configurations
Return type:: CARMASoluteConfig

class musica.carma.CARMACoagulationConfig(igroup1: int = 1, igroup2: int = 1, igroup3: int = 1, algorithm: int = ParticleCollectionAlgorithm.CONSTANT, ck0: float = -1.0, grav_e_coll0: float = 0.0, use_ccd: bool = False)#

Bases: object

Configuration for CARMA coagulation process.

This class defines how particles coagulate in the CARMA model.

to_dict() → Dict#: Convert to dictionary.

class musica.carma.CARMAElementConfig(igroup: int = 1, isolute: int = 0, name: str = 'default_element', shortname: str = '', itype: int = ParticleType.INVOLATILE, icomposition: int = ParticleComposition.OTHER, is_shell: bool = True, rho: float = 1000.0, rhobin: List[float] | None = None, arat: List[float] | None = None, kappa: float = 0.0, refidx: List[List[float]] | None = None)#

Bases: object

Configuration for a CARMA particle element.

A CARMA particle element represents one of the components of a cloud or aerosol particle.

to_dict() → Dict#: Convert to dictionary.

class musica.carma.CARMAGasConfig(name: str = 'default_gas', shortname: str = '', wtmol: float = 0.0, ivaprtn: VaporizationAlgorithm = VaporizationAlgorithm.NONE, icomposition: GasComposition = GasComposition.NONE, dgc_threshold: float = 0.0, ds_threshold: float = 0.0, refidx: List[List[float]] | None = None)#

Bases: object

Configuration for a CARMA gas.

A CARMA gas represents a gaseous species in the atmosphere.

to_dict() → Dict#: Convert to dictionary.

class musica.carma.CARMAGroupConfig(name: str = 'default_group', shortname: str = '', rmin: float = 1e-09, rmrat: float = 2.0, rmassmin: float = 0.0, ishape: int = ParticleShape.SPHERE, eshape: float = 1.0, swelling_approach: dict = {'algorithm': ParticleSwellingAlgorithm.NONE, 'composition': ParticleSwellingComposition.NONE}, fall_velocity_routine: int = ParticleFallVelocityAlgorithm.STANDARD_SPHERICAL_ONLY, mie_calculation_algorithm: int = MieCalculationAlgorithm.TOON_1981, optics_algorithm: int = OpticsAlgorithm.FIXED, is_ice: bool = False, is_fractal: bool = False, is_cloud: bool = False, is_sulfate: bool = False, do_wetdep: bool = False, do_drydep: bool = False, do_vtran: bool = True, solfac: float = 0.3, scavcoef: float = 0.1, dpc_threshold: float = 0.0, rmon: float = 0.0, df: List[float] | None = None, falpha: float = 1.0, neutral_volfrc: float = 0.0)#

Bases: object

Configuration for a CARMA particle group.

A CARMA particle group represents a collection of particles with similar properties.

to_dict() → Dict#: Convert to dictionary, serializing enums in swelling_approach as well.

class musica.carma.CARMAGrowthConfig(ielem: int = 0, igas: int = 0)#

Bases: object

Configuration for CARMA particle growth process.

This class defines how particles grow in the CARMA model.

to_dict() → Dict#: Convert to dictionary.

class musica.carma.CARMAInitializationConfig(do_cnst_rlh: bool = False, do_detrain: bool = False, do_fixedinit: bool = False, do_incloud: bool = False, do_explised: bool = False, do_substep: bool = False, do_thermo: bool = False, do_vdiff: bool = False, do_vtran: bool = False, do_drydep: bool = False, do_pheat: bool = False, do_pheatatm: bool = False, do_clearsky: bool = False, do_partialinit: bool = False, do_coremasscheck: bool = False, sulfnucl_method: SulfateNucleationMethod = SulfateNucleationMethod.NONE, vf_const: float = 0.0, minsubsteps: int = 1, maxsubsteps: int = 1, maxretries: int = 5, conmax: float = 0.1, dt_threshold: float = 0.0, cstick: float = 1.0, gsticki: float = 0.93, gstickl: float = 1.0, tstick: float = 1.0)#

Bases: object

Configuration for CARMA initialization.

This class defines how the CARMA model is initialized before running simulations.

to_dict() → Dict#: Convert to dictionary, converting Enums to ints.

class musica.carma.CARMANucleationConfig(ielemfrom: int = 0, ielemto: int = 0, algorithm: ParticleNucleationAlgorithm = ParticleNucleationAlgorithm.NONE, rlh_nuc: float = 0.0, igas: int = 0, ievp2elem: int = 0)#

Bases: object

Configuration for CARMA particle nucleation process.

This class defines how new particles are formed in the CARMA model.

to_dict() → Dict#: Convert to dictionary.

class musica.carma.CARMAParameters(nbin: int = 5, nz: int = 1, dtime: float = 1800.0, wavelength_bins: List[CARMAWavelengthBin] | None = None, groups: List[CARMAGroupConfig] | None = None, elements: List[CARMAElementConfig] | None = None, solutes: List[CARMASoluteConfig] | None = None, gases: List[CARMAGasConfig] | None = None, coagulations: List[CARMACoagulationConfig] | None = None, growths: List[CARMAGrowthConfig] | None = None, nucleations: List[CARMANucleationConfig] | None = None, initialization: CARMAInitializationConfig | None = None)#

Bases: object

Parameters for CARMA aerosol model simulation.

This class encapsulates all the parameters needed to configure and run a CARMA simulation, including model dimensions, time stepping, and spatial parameters.

add_coagulation(coagulation: CARMACoagulationConfig)#: Add a coagulation configuration.

add_element(element: CARMAElementConfig)#: Add an element configuration.

add_gas(gas: CARMAGasConfig)#: Add a gas configuration.

add_group(group: CARMAGroupConfig)#: Add a group configuration.

add_growth(growth: CARMAGrowthConfig)#: Add a growth configuration.

add_nucleation(nucleation: CARMANucleationConfig)#: Add a nucleation configuration.

add_solute(solute: CARMASoluteConfig)#: Add a solute configuration.

add_wavelength_bin(wavelength_bin: CARMAWavelengthBin)#: Add a wavelength bin configuration.

classmethod from_dict(params_dict: Dict) → CARMAParameters#: Create parameters from dictionary.

set_initialization(initialization: CARMAInitializationConfig)#: Set the initialization configuration.

to_dict() → Dict#: Convert parameters to dictionary for C++ interface.

class musica.carma.CARMASoluteConfig(name: str = 'default_solute', shortname: str = '', ions: int = 0, wtmol: float = 0.0, rho: float = 0.0)#

Bases: object

Configuration for a CARMA solute.

A CARMA solute represents a chemical species that can dissolve in water and affect particle properties.

to_dict() → Dict#: Convert to dictionary.

class musica.carma.CARMAState(carma_pointer: c_void_p, vertical_center: List[float], vertical_levels: List[float], pressure: List[float], pressure_levels: List[float], temperature: List[float], original_temperature: List[float] | None = None, relative_humidity: List[float] | None = None, specific_humidity: List[float] | None = None, radiative_intensity: List[List[float]] | None = None, time: float = 0.0, time_step: float = 1.0, latitude: float = 0.0, longitude: float = 0.0, coordinates: CarmaCoordinates = CarmaCoordinates.CARTESIAN, gases: List[CARMAGasConfig] | None = None)#

Bases: object

Represents the environmental variables used in CARMA simulations.

get_bins() → Dataset#

Get the CARMA aerosol state data for all bins and elements.

Returns:: Aerosol bin properties for all bins and elements
Return type:: Dataset

get_detrained_masses() → Dataset#

Get the mass of the detrained condensate for the bin for each particle in the grid

Returns:: Mass of the detrained condensate for the specified bin and element
Return type:: List[float]

get_environmental_values() → Dataset#

Get all environmental conditions for the current CARMAState.

Returns:: Dataset containing all environmental conditions
Return type:: xr.Dataset

get_gases() → Tuple[Dataset, Dict[str, int]]#

Get the values for all gases.

Returns:: Tuple[xr.Dataset, Dict[str, int]] A dataset containing values for all gases and a mapping of gas names to their indices.

get_step_statistics() → Dict[str, Any]#

Get the step statistics for the current CARMAState.

Returns:

Dictionary containing step statistics such as: number of substeps, convergence status, etc.

Return type:

Dict[str, Any]

set_air_density(air_density: float | List[float])#

Set the air density for the vertical levels.

Parameters:: air_density – Air density value to set, can be a single float or a list of floats

set_bin(bin_index: int, element_index: int, value: float | List[float], surface_mass: float | None = 0.0)#

Set the value for a specific bin and element.

Parameters:

bin_index – Index of the size bin (1-indexed)
element_index – Index of the element (1-indexed)
value – Value to set, can be a single float or a list of floats
surface_mass – Optional surface mass for the bin [kg m-2] (default: 0.0)

set_detrain(bin_index: int, element_index: int, value: float)#

Set the mass of the detrained condensate for the bin

Parameters:

bin_index – Index of the size bin (1-indexed)
element_index – Index of the element (1-indexed)
value – Value to set

set_gas(gas_index: int, value: float | List[float], old_mmr: List[float] | None = None, gas_saturation_wrt_ice: List[float] | None = None, gas_saturation_wrt_liquid: List[float] | None = None)#

Set the value for a specific gas.

Parameters:

gas_index – Index of the gas (1-indexed)
value – Value to set, can be a single float or a list of floats
old_mmr – Optional list of old mass mixing ratios for the gas (default: None)
gas_saturation_wrt_ice – Optional list of gas saturation with respect to ice (default: None)
gas_saturation_wrt_liquid – Optional list of gas saturation with respect to liquid (default: None)

set_temperature(temperature: float | List[float])#

Set the temperature for the vertical levels.

Parameters:: temperature – Temperature value to set, can be a single float or a list of floats

Perform a single step in the CARMA simulation.

Parameters:

cloud_fraction – Optional list of cloud fractions for each vertical level (default: None)
critical_relative_humidity – Optional list of critical relative humidities for each vertical level (default: None)
land – Optional CARMASurfaceProperties instance representing land surface properties (default: None)
ocean – Optional CARMASurfaceProperties instance representing ocean surface properties (default: None)
ice – Optional CARMASurfaceProperties instance representing ice surface properties (default: None)

to_dict() → Dict#: Convert CARMAState to dictionary.

class musica.carma.CARMASurfaceProperties(surface_friction_velocity: float = 0.0, aerodynamic_resistance: float = 0.0, area_fraction: float = 0.0)#

Bases: object

Represents the surface properties used in CARMA simulations.

This class encapsulates the surface properties such as friction velocity, aerodynamic resistance, and area fraction, which are used in CARMA simulations to model the interaction between the atmosphere and the surface.

to_dict() → Dict#: Convert surface properties to dictionary.

class musica.carma.CARMAWavelengthBin(center: float, width: float, do_emission: bool = True)#

Bases: object

Configuration for a CARMA wavelength bin.

A CARMA wavelength bin represents a specific wavelength range used in optical calculations.

to_dict() → Dict#: Convert to dictionary.

class musica.carma.CarmaCoordinates(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Enumeration for CARMA coordinates.

CARTESIAN = 1#

HYBRID = 7#

LAMBERT_CONFORMAL = 4#

LONGITUDE_LATITUDE = 3#

MERCATOR = 6#

POLAR_STEREOGRAPHIC = 5#

SIGMA = 2#

class musica.carma.GasComposition(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Enumeration for gas compositions used in CARMA.

H2O = 1#

H2SO4 = 2#

NONE = 0#

SO2 = 3#

class musica.carma.MieCalculationAlgorithm(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Enumeration for Mie calculation algorithms used in CARMA.

BOHREN_1983 = 2#

BOTET_1997 = 3#

TOON_1981 = 1#

class musica.carma.OpticsAlgorithm(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Enumeration for optics algorithms used in CARMA.

FIXED = 1#

MIXED_CORE_SHELL = 5#

MIXED_H2O_YU_2015 = 4#

MIXED_MAXWELL = 7#

MIXED_VOLUME = 6#

MIXED_YU_2015 = 2#

NONE = 0#

SULFATE = 8#

SULFATE_YU_2015 = 3#

class musica.carma.ParticleCollectionAlgorithm(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Enumeration for particle collection algorithms used in CARMA.

CONSTANT = 1#

DATA = 3#

FUCHS = 2#

NONE = 0#

class musica.carma.ParticleComposition(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Enumeration for particle compositions used in CARMA.

ALUMINUM = 1#

BLACK_CARBON = 6#

DUST = 3#

ICE = 4#

ORGANIC_CARBON = 7#

OTHER = 8#

SULFURIC_ACID = 2#

WATER = 5#

class musica.carma.ParticleFallVelocityAlgorithm(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Enumeration for particle fall velocity algorithms used in CARMA.

HEYMSFIELD_2010 = 3#

NONE = 0#

STANDARD_SHAPE_SUPPORT = 2#

STANDARD_SPHERICAL_ONLY = 1#

class musica.carma.ParticleNucleationAlgorithm(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Enumeration for particle nucleation algorithms used in CARMA.

AEROSOL_FREEZING = 512#

AEROSOL_FREEZING_KOOP_2000 = 2#

AEROSOL_FREEZING_MURRAY_2010 = 3#

AEROSOL_FREEZING_TABAZDEH_2000 = 1#

DROPLET_ACTIVATION = 256#

DROPLET_FREEZING = 1024#

HETEROGENEOUS_NUCLEATION = 4096#

HETEROGENEOUS_SULFURIC_ACID_NUCLEATION = 16384#

HOMOGENEOUS_NUCLEATION = 8192#

ICE_MELTING = 2048#

NONE = 0#

class musica.carma.ParticleShape(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Enumeration for particle shapes used in CARMA.

CYLINDER = 3#

HEXAGON = 2#

SPHERE = 1#

class musica.carma.ParticleSwellingAlgorithm(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Enumeration for particle swelling algorithms used in CARMA.

FITZGERALD = 1#

GERBER = 2#

NONE = 0#

PETTERS = 4#

WEIGHT_PERCENT_H2SO4 = 3#

class musica.carma.ParticleSwellingComposition(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Enumeration for particle swelling compositions used in CARMA.

AMMONIUM_SULFATE = 1#

NONE = 0#

RURAL = 4#

SEA_SALT = 2#

URBAN = 3#

class musica.carma.ParticleType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Enumeration for particle types used in CARMA.

CORE_MASS = 3#

CORE_MASS_TWO_MOMENTS = 5#

INVOLATILE = 1#

VOLATILE = 2#

VOLATILE_CORE = 4#

class musica.carma.SulfateNucleationMethod(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Enumeration for sulfate nucleation methods used in CARMA.

NONE = 0#

VEHKAMAKI = 2#

ZHAO_TURCO = 1#

class musica.carma.VaporizationAlgorithm(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Enumeration for vaporization algorithms used in CARMA.

H2O_BUCK_1981 = 1#

H2O_GOFF_1946 = 3#

H2O_MURPHY_2005 = 2#

H2SO4_AYERS_1980 = 4#

NONE = 0#