MUSICA Python API#

C++ Bindings#

Core#

Wrapper classes for MICM

class musica._musica._micm.MICM#

Bases: pybind11_object

_pybind11_conduit_v1_()#

class musica._musica._micm.VectorConditions#

Bases: pybind11_object

_pybind11_conduit_v1_()#

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

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

extend(*args, **kwargs)#

Overloaded function.

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

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

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

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

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

pop(*args, **kwargs)#

Overloaded function.

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

Remove and return the last item

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

Remove and return the item at index i

class musica._musica._micm._BackwardEulerSolverParameters#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property absolute_tolerances#

property max_number_of_steps#

property relative_tolerance#

property time_step_reductions#

class musica._musica._micm._Conditions(temperature: float | int | None = None, pressure: float | int | None = None, air_density: float | int | None = None)#

Bases: pybind11_object

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.

temperature#

Temperature in Kelvin.

Type:: float

pressure#

Pressure in Pascals.

Type:: float

air_density#

Air density in mol m-3

Type:: float

_pybind11_conduit_v1_()#

property air_density#

property pressure#

property temperature#

class musica._musica._micm._RosenbrockSolverParameters#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property absolute_tolerances#

property h_max#

property h_min#

property h_start#

property max_number_of_steps#

property relative_tolerance#

class musica._musica._micm._SolverResult#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property state#

property stats#

class musica._musica._micm._SolverResultsStats#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property accepted#

property decompositions#

property final_time#

property function_calls#

property jacobian_updates#

property number_of_steps#

property rejected#

property solves#

class musica._musica._micm._SolverState#

Bases: pybind11_object

Members:

NotYetCalled

Running

Converged

ConvergenceExceededMaxSteps

StepSizeTooSmall

RepeatedlySingularMatrix

NaNDetected

InfDetected

AcceptingUnconvergedIntegration

AcceptingUnconvergedIntegration = <_SolverState.AcceptingUnconvergedIntegration: 8>#

Converged = <_SolverState.Converged: 2>#

ConvergenceExceededMaxSteps = <_SolverState.ConvergenceExceededMaxSteps: 3>#

InfDetected = <_SolverState.InfDetected: 7>#

NaNDetected = <_SolverState.NaNDetected: 6>#

NotYetCalled = <_SolverState.NotYetCalled: 0>#

RepeatedlySingularMatrix = <_SolverState.RepeatedlySingularMatrix: 5>#

Running = <_SolverState.Running: 1>#

StepSizeTooSmall = <_SolverState.StepSizeTooSmall: 4>#

_pybind11_conduit_v1_()#

_SolverState.name -> str

property value#

class musica._musica._micm._State#

Bases: pybind11_object

_pybind11_conduit_v1_()#

concentration_strides(self: musica._musica._micm._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._micm._State) → int#

user_defined_rate_parameter_strides(self: musica._musica._micm._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._micm._create_solver(arg0: str, arg1: musica::MICMSolver) → musica._musica._micm.MICM#

musica._musica._micm._create_solver_from_mechanism(arg0: mechanism_configuration::v1::types::Mechanism, arg1: musica::MICMSolver) → musica._musica._micm.MICM#

musica._musica._micm._create_state(arg0: musica._musica._micm.MICM, arg1: SupportsInt) → musica::State#

musica._musica._micm._get_backward_euler_solver_parameters(arg0: musica._musica._micm.MICM) → musica._musica._micm._BackwardEulerSolverParameters#: Get Backward Euler solver parameters

musica._musica._micm._get_micm_version() → str#: Get the version of MICM

musica._musica._micm._get_rosenbrock_solver_parameters(arg0: musica._musica._micm.MICM) → musica._musica._micm._RosenbrockSolverParameters#: Get Rosenbrock solver parameters

musica._musica._micm._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._micm._micm_solve(arg0: musica._musica._micm.MICM, arg1: musica::State, arg2: SupportsFloat) → musica._musica._micm._SolverResult#: Solve the chemistry system

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

musica._musica._micm._set_backward_euler_solver_parameters(arg0: musica._musica._micm.MICM, arg1: musica._musica._micm._BackwardEulerSolverParameters) → None#: Set Backward Euler solver parameters

musica._musica._micm._set_rosenbrock_solver_parameters(arg0: musica._musica._micm.MICM, arg1: musica._musica._micm._RosenbrockSolverParameters) → None#: Set Rosenbrock solver parameters

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

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

musica._musica._micm._vector_size(arg0: musica::MICMSolver) → int#: Returns the vector dimension for vector-ordered solvers, 1 otherwise.

class musica._musica._micm._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>#

_SolverType.name -> str

rosenbrock = <_SolverType.rosenbrock: 1>#

rosenbrock_standard_order = <_SolverType.rosenbrock_standard_order: 2>#

property value#

Mechanism Configuration#

Wrapper classes for Mechanism Configuration for the chemical system configuration schema

class musica._musica._mechanism_configuration._Arrhenius#

Bases: pybind11_object

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#

property type#

class musica._musica._mechanism_configuration._Branched#

Bases: pybind11_object

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#

property type#

class musica._musica._mechanism_configuration._Emission#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property gas_phase#

property name#

property other_properties#

property products#

property scaling_factor#

property type#

class musica._musica._mechanism_configuration._FirstOrderLoss#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property gas_phase#

property name#

property other_properties#

property reactants#

property scaling_factor#

property type#

class musica._musica._mechanism_configuration._Mechanism#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property name#

property phases#

property reactions#

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, path: str, convert_reaction_units: bool = True) → musica._musica._mechanism_configuration._Mechanism#: Parse a v0 mechanism configuration file

class musica._musica._mechanism_configuration._Phase#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property name#

property other_properties#

property species#

class musica._musica._mechanism_configuration._PhaseSpecies#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property diffusion_coefficient_m2_s#

property name#

property other_properties#

class musica._musica._mechanism_configuration._Photolysis#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property gas_phase#

property name#

property other_properties#

property products#

property reactants#

property scaling_factor#

property type#

class musica._musica._mechanism_configuration._ReactionComponent#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property coefficient#

property other_properties#

property species_name#

class musica._musica._mechanism_configuration._Reactions#

Bases: pybind11_object

_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#

Bases: pybind11_object

_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#

class musica._musica._mechanism_configuration._Surface#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property gas_phase#

property gas_phase_products#

property gas_phase_species#

property name#

property other_properties#

property reaction_probability#

property type#

class musica._musica._mechanism_configuration._TaylorSeries#

Bases: pybind11_object

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#

property taylor_coefficients#

class musica._musica._mechanism_configuration._TernaryChemicalActivation#

Bases: pybind11_object

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#

property type#

class musica._musica._mechanism_configuration._Troe#

Bases: pybind11_object

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#

property type#

class musica._musica._mechanism_configuration._Tunneling#

Bases: pybind11_object

property A#

property B#

property C#

_pybind11_conduit_v1_()#

property gas_phase#

property name#

property other_properties#

property products#

property reactants#

property type#

class musica._musica._mechanism_configuration._UserDefined#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property gas_phase#

property name#

property other_properties#

property products#

property reactants#

property scaling_factor#

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_()#

_ReactionType.name -> str

property value#

Musica Types#

Mechanism Configuration#

Bases: CppWrapper

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.

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].

reactants#: A list of reactants involved in the reaction.

products#: A list of products formed in the reaction.

gas_phase#: The gas phase in which the reaction occurs.

other_properties#: A dictionary of other properties.

property type#: Get the reaction type.

Bases: CppWrapper

A branched reaction rate constant.

name#: The name of the branched reaction rate constant.

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

Y#: Exponential branching factor [K-1].

a0#: Z parameter [unitless].

n#: A parameter [unitless].

reactants#: A list of reactants involved in the reaction.

nitrate_products#: A list of products formed in the nitrate branch.

alkoxy_products#: A list of products formed in the alkoxy branch.

gas_phase#: The gas phase in which the reaction occurs.

other_properties#: A dictionary of other properties.

property type#: Get the reaction type.

Bases: CppWrapper

An emission reaction rate constant.

name#: The name of the emission reaction rate constant.

scaling_factor#: The scaling factor for the emission rate constant.

products#: A list of products formed in the reaction.

gas_phase#: The gas phase in which the reaction occurs.

other_properties#: A dictionary of other properties.

property type#: Get the reaction type.

Bases: CppWrapper

A first-order loss reaction rate constant.

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

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

reactants#: A list of reactants involved in the reaction.

gas_phase#: The gas phase in which the reaction occurs.

other_properties#: A dictionary of other properties.

property type#: Get the reaction type.

Bases: CppWrapper

A chemical mechanism.

name#: The name of the mechanism.

reactions#: A list of reactions in the mechanism.

species#: A list of species in the mechanism.

phases#: A list of phases in the mechanism.

version#: The version of the mechanism.

property phases: List[Phase]#: List of phases in the mechanism.

property reactions: Reactions#

Reactions in the mechanism.

Note: This property wraps the C++ reactions object on each access, consistent with other properties like species and phases. This ensures that changes to the underlying C++ object are always reflected.

property species: List[Species]#: List of species in the mechanism.

property version#: Version of the mechanism.

class musica.mechanism_configuration.Parser#

Bases: object

Parser for mechanism configuration files.

parse(path: str)#

Parse a mechanism configuration file.

Parameters:: path – Path to the configuration file.
Returns:: A Mechanism object.
Return type:: Mechanism

parse_and_convert_v0(path: str, convert_reaction_units: bool = True)#

Parse a v0 mechanism configuration file and convert to v1.

Parameters:

path – Path to the v0 configuration file.
convert_reaction_units – Whether to convert reaction units.

Returns:

A Mechanism object.

Return type:

Mechanism

class musica.mechanism_configuration.Phase(name: str | None = None, species: List[Species] | List[PhaseSpecies] | None = None, other_properties: Dict[str, Any] | None = None)#

Bases: CppWrapper

A phase in a chemical mechanism.

name#: The name of the phase.

species#: A list of species in the phase.

other_properties#: A dictionary of other properties of the phase.

property species: List[PhaseSpecies]#: List of species in the phase.

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

Bases: CppWrapper

A chemical species within a specific phase of a mechanism.

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.

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

other_properties#: A dictionary of other phase-specific properties of the species.

Bases: CppWrapper

A photolysis reaction rate constant.

name#: The name of the photolysis reaction rate constant.

scaling_factor#: The scaling factor for the photolysis rate constant.

reactants#: A list of reactants involved in the reaction.

products#: A list of products formed in the reaction.

gas_phase#: The gas phase in which the reaction occurs.

other_properties#: A dictionary of other properties.

property type#: Get the reaction type.

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

Bases: CppWrapper

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.

coefficient#: The stoichiometric coefficient of the species in the reaction.

other_properties#: A dictionary of other properties relevant to the reaction component.

musica.mechanism_configuration.ReactionType#: alias of _ReactionType

class musica.mechanism_configuration.Reactions(reactions: List[Any] | None = None)#

Bases: CppWrapper

A collection of reactions in a chemical mechanism.

reactions#: A list of reactions in the mechanism.

property arrhenius#: List of Arrhenius reactions.

property branched#: List of Branched reactions.

property emission#: List of Emission reactions.

property first_order_loss#: List of FirstOrderLoss reactions.

property photolysis#: List of Photolysis reactions.

property surface#: List of Surface reactions.

property taylor_series#: List of TaylorSeries reactions.

property ternary_chemical_activation#: List of TernaryChemicalActivation reactions.

property troe#: List of Troe reactions.

property tunneling#: List of Tunneling reactions.

property user_defined#: List of UserDefined reactions.

class 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: CppWrapper

A species in a chemical mechanism.

name#: The name of the species.

molecular_weight_kg_mol#: Molecular weight [kg mol-1].

constant_concentration_mol_m3#: Constant concentration of the species (mol m-3).

constant_mixing_ratio_mol_mol#: Constant mixing ratio of the species (mol mol-1).

is_third_body#: Whether the species is a third body.

other_properties#: A dictionary of other properties of the species.

Bases: CppWrapper

A surface reaction in a chemical mechanism.

name#: The name of the surface.

reaction_probability#: The probability of a reaction occurring on the surface.

gas_phase_species#: The gas phase species involved in the reaction.

gas_phase_products#: The gas phase products formed in the reaction.

gas_phase#: The gas phase in which the reaction occurs.

other_properties#: A dictionary of other properties of the surface.

property type#: Get the reaction type.

Bases: CppWrapper

A Taylor series rate constant.

The rate constant k is represented as a Taylor series expansion in temperature:

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

name#: The name of the Taylor series rate constant.

A#: Optional parameter for extended forms.

B#: Optional parameter for extended forms.

C#: Optional parameter for extended forms.

D#: Optional parameter for extended forms.

E#: Optional parameter for extended forms.

taylor_coefficients#: Coefficients for the Taylor series expansion.

reactants#: A list of reactants involved in the reaction.

products#: A list of products formed in the reaction.

gas_phase#: The gas phase in which the reaction occurs.

other_properties#: A dictionary of other properties.

property type#: Get the reaction type.

Bases: CppWrapper

A Ternary Chemical Activation rate constant.

name#: The name of the rate constant.

k0_A#: Pre-exponential factor for the low-pressure limit.

k0_B#: Temperature exponent for the low-pressure limit.

k0_C#: Exponential term for the low-pressure limit.

kinf_A#: Pre-exponential factor for the high-pressure limit.

kinf_B#: Temperature exponent for the high-pressure limit.

kinf_C#: Exponential term for the high-pressure limit.

Fc#: Ternary Chemical Activation parameter [unitless].

N#: Ternary Chemical Activation parameter [unitless].

reactants#: A list of reactants involved in the reaction.

products#: A list of products formed in the reaction.

gas_phase#: The gas phase in which the reaction occurs.

other_properties#: A dictionary of other properties.

property type#: Get the reaction type.

Bases: CppWrapper

A Troe rate constant.

name#: The name of the Troe rate constant.

k0_A#: Pre-exponential factor for the low-pressure limit.

k0_B#: Temperature exponent for the low-pressure limit.

k0_C#: Exponential term for the low-pressure limit.

kinf_A#: Pre-exponential factor for the high-pressure limit.

kinf_B#: Temperature exponent for the high-pressure limit.

kinf_C#: Exponential term for the high-pressure limit.

Fc#: Troe parameter [unitless].

N#: Troe parameter [unitless].

reactants#: A list of reactants involved in the reaction.

products#: A list of products formed in the reaction.

gas_phase#: The gas phase in which the reaction occurs.

other_properties#: A dictionary of other properties.

property type#: Get the reaction type.

Bases: CppWrapper

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.

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

B#: Tunneling parameter [K^-1].

C#: Tunneling parameter [K^-3].

reactants#: A list of reactants involved in the reaction.

products#: A list of products formed in the reaction.

gas_phase#: The gas phase in which the reaction occurs.

other_properties#: A dictionary of other properties.

Bases: CppWrapper

A user-defined reaction rate constant.

name#: The name of the user-defined reaction rate constant.

scaling_factor#: The scaling factor for the rate constant.

reactants#: A list of reactants involved in the reaction.

products#: A list of products formed in the reaction.

gas_phase#: The gas phase in which the reaction occurs.

other_properties#: A dictionary of other properties.

property type#: Get the reaction type.

MICM#

class musica.micm.BackwardEulerSolverParameters(relative_tolerance: float = 1e-06, absolute_tolerances: List[float] | None = None, max_number_of_steps: int = 11, time_step_reductions: List[float] | None = None)#

Bases: object

Parameters for configuring Backward Euler solvers.

relative_tolerance#

Relative tolerance for the solver (default: 1e-6).

Type:: float

absolute_tolerances#

Absolute tolerances per species. None uses MICM defaults.

Type:: list of float or None

max_number_of_steps#

Maximum number of internal steps (default: 11).

Type:: int

time_step_reductions#

Factors by which to reduce the time step after failed solves. Must have exactly 5 elements (default: [0.5, 0.5, 0.5, 0.5, 0.1]).

Type:: list of float

musica.micm.Conditions#: alias of _Conditions

class musica.micm.MICM(config_path: str | PathLike[str] = None, mechanism: _Mechanism = None, solver_type: Any = None, solver_parameters: RosenbrockSolverParameters | BackwardEulerSolverParameters | None = None)#

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

get_solver_parameters() → RosenbrockSolverParameters | BackwardEulerSolverParameters#

Get the current solver parameters.

Returns:: The current solver parameters, depending on the solver type.
Return type:: RosenbrockSolverParameters or BackwardEulerSolverParameters

set_solver_parameters(params: RosenbrockSolverParameters | BackwardEulerSolverParameters)#

Set solver-specific parameters.

Parameters:: params (RosenbrockSolverParameters or BackwardEulerSolverParameters) – The parameters to set. Must match the solver type.
Raises:: TypeError – If the parameter type does not match the solver type.

solve(state: State, time_step: float) → _SolverResult#

Solve the system of equations for the given state and time step.

Parameters:

state (State) – State object containing the initial conditions.
time_step (float) – Time step in seconds.

Returns:

A SolverResult object containing the solver state and statistics.

Return type:

SolverResult

solver_type() → _SolverType#

Get the type of solver used.

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

class musica.micm.RosenbrockSolverParameters(relative_tolerance: float = 1e-06, absolute_tolerances: List[float] | None = None, h_min: float = 0.0, h_max: float = 0.0, h_start: float = 0.0, max_number_of_steps: int = 1000)#

Bases: object

Parameters for configuring Rosenbrock solvers.

relative_tolerance#

Relative tolerance for the solver (default: 1e-6).

Type:: float

absolute_tolerances#

Absolute tolerances per species. None uses MICM defaults.

Type:: list of float or None

h_min#

Minimum step size in seconds (default: 0.0, meaning solver chooses).

Type:: float

h_max#

Maximum step size in seconds (default: 0.0, meaning solver chooses).

Type:: float

h_start#

Initial step size in seconds (default: 0.0, meaning solver chooses).

Type:: float

max_number_of_steps#

Maximum number of internal steps (default: 1000).

Type:: int

musica.micm.SolverResult#: alias of _SolverResult

musica.micm.SolverState#: alias of _SolverState

musica.micm.SolverStats#: alias of _SolverResultsStats

musica.micm.SolverType#: alias of _SolverType

class musica.micm.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_state() → Any#

Get the internal state object. This is used for passing the state to the solver.

Returns:: Internal state object.
Return type:: _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.micm.species_ordering()#

_species_ordering(arg0: musica::State) -> dict[str, int]

Return map of species names to their indices in the state concentrations vector

musica.micm.user_defined_rate_parameters_ordering()#

_user_defined_rate_parameters_ordering(arg0: musica::State) -> dict[str, int]

Return map of reaction rate parameters to their indices in the state user-defined rate parameters vector

TUVX#

class musica.tuvx.Grid(*, name: str, units: str, num_sections: int | None = None, edges: ndarray | None = None, midpoints: ndarray | None = None, **kwargs)#

Bases: CppWrapper

A grid on which TUV-x profiles are defined.

name#: Name of the grid.

units#: Units of the grid values.

num_sections#: Number of grid sections.

edges#: Array of edge values (length num_sections + 1). Shares memory with the C++ object (zero-copy).

midpoints#: Array of midpoint values (length num_sections). Shares memory with the C++ object (zero-copy).

property edges: ndarray#: Array of edge values (zero-copy view into C++ memory).

property midpoints: ndarray#: Array of midpoint values (zero-copy view into C++ memory).

property name: str#: Name of the grid.

property num_sections: int#: Number of grid sections.

property units: str#: Units of the grid values.

class musica.tuvx.GridMap(**kwargs)#

Bases: CppWrapper

A collection of TUV-x grids with dictionary-style access.

Grids are accessed using (name, units) tuples as keys.

add_grid(grid: Grid)#: Add a grid to the map.

clear()#: Remove all grids from the map.

get_grid(name: str, units: str) → Grid#: Get a grid by name and units.

get_grid_by_index(index: int) → Grid#: Get a grid by its index.

get_number_of_grids() → int#: Return the number of grids in the map.

items()#: Return an iterator over (key, grid) pairs, where key is (name, units).

keys()#: Return an iterator over grid keys (name, units) tuples.

remove_grid_by_index(index: int)#: Remove a grid by its index.

values()#: Return an iterator over Grid objects in the map.

class musica.tuvx.Profile(*, name: str, units: str, grid: Grid, edge_values: ndarray | None = None, midpoint_values: ndarray | None = None, layer_densities: ndarray | None = None, calculate_layer_densities: bool = False, exo_layer_density: float | None = 0.0, **kwargs)#

Bases: CppWrapper

A profile of physical quantities defined on a TUV-x grid.

name#: Name of the profile.

units#: Units of the profile values.

number_of_sections#: Number of sections in the underlying grid.

edge_values#: Array of values at grid edges (zero-copy).

midpoint_values#: Array of values at grid midpoints (zero-copy).

layer_densities#: Array of layer densities (zero-copy).

exo_layer_density#: Exoatmospheric layer density value.

calculate_exo_layer_density(scale_height: float)#

Calculate the exoatmospheric layer density.

Parameters:: scale_height – The scale height used for the calculation.

calculate_layer_densities(grid: Grid, conv: float | None = None)#

Calculate layer densities from midpoint values and grid spacing.

Parameters:

grid – Grid on which the profile is defined.
conv – Conversion factor to apply (default is 1.0 or 1.0e5 for height in km and concentrations in molecules cm-3).

property edge_values: ndarray#: Array of values at grid edges (zero-copy view into C++ memory).

property exo_layer_density: float#: Exoatmospheric layer density value.

property layer_densities: ndarray#: Array of layer densities (zero-copy view into C++ memory).

property midpoint_values: ndarray#: Array of values at grid midpoints (zero-copy view into C++ memory).

property name: str#: Name of the profile.

property number_of_sections: int#: Number of sections in the underlying grid.

property units: str#: Units of the profile values.

class musica.tuvx.ProfileMap(**kwargs)#

Bases: CppWrapper

A collection of TUV-x profiles with dictionary-style access.

Profiles are accessed using (name, units) tuples as keys.

add_profile(profile: Profile)#: Add a profile to the map.

clear()#: Remove all profiles from the map.

get_number_of_profiles() → int#: Return the number of profiles in the map.

get_profile(name: str, units: str) → Profile#: Get a profile by name and units.

get_profile_by_index(index: int) → Profile#: Get a profile by its index.

items()#: Return an iterator over (key, profile) pairs, where key is (name, units).

keys()#: Return an iterator over profile keys (name, units) tuples.

remove_profile_by_index(index: int)#: Remove a profile by its index.

values()#: Return an iterator over Profile objects in the map.

class musica.tuvx.Radiator(*, name: str, height_grid: Grid, wavelength_grid: Grid, optical_depths: ndarray | None = None, single_scattering_albedos: ndarray | None = None, asymmetry_factors: ndarray | None = None, **kwargs)#

Bases: CppWrapper

An optically active species for TUV-x radiative transfer calculations.

name#: Name of the radiator.

number_of_height_sections#: Number of height grid sections.

number_of_wavelength_sections#: Number of wavelength grid sections.

optical_depths#: 2D array of optical depths (zero-copy).

single_scattering_albedos#: 2D array of single scattering albedos (zero-copy).

asymmetry_factors#: 2D array of asymmetry parameters (zero-copy).

property asymmetry_factors: ndarray#: 2D array of asymmetry parameters (zero-copy view into C++ memory).

property name: str#: Name of the radiator.

property number_of_height_sections: int#: Number of height grid sections.

property number_of_wavelength_sections: int#: Number of wavelength grid sections.

property optical_depths: ndarray#: 2D array of optical depths (zero-copy view into C++ memory).

property single_scattering_albedos: ndarray#: 2D array of single scattering albedos (zero-copy view into C++ memory).

class musica.tuvx.RadiatorMap(**kwargs)#

Bases: CppWrapper

A collection of TUV-x radiators with dictionary-style access.

Radiators are accessed using their name as key.

add_radiator(radiator: Radiator)#: Add a radiator to the map.

clear()#: Remove all radiators from the map.

get_number_of_radiators() → int#: Return the number of radiators in the map.

get_radiator(name: str) → Radiator#: Get a radiator by name.

get_radiator_by_index(index: int) → Radiator#: Get a radiator by its index.

items()#

Iterator over (name, radiator) pairs in the map.

Yields:: Tuples of (radiator_name, Radiator instance).

keys()#

Iterator over radiator names in the map.

Yields:: Radiator names as strings.

remove_radiator_by_index(index: int)#: Remove a radiator by its index.

values()#

Iterator over Radiator instances in the map.

Yields:: Radiator instances.

class musica.tuvx.TUVX(grid_map: GridMap, profile_map: ProfileMap, radiator_map: RadiatorMap, 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_grid_map() → GridMap#

Get the GridMap used in this TUV-x instance.

Returns:: GridMap instance

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

get_profile_map() → ProfileMap#

Get the ProfileMap used in this TUV-x instance.

Returns:: ProfileMap instance

get_radiator_map() → RadiatorMap#

Get the RadiatorMap used in this TUV-x instance.

Returns:: RadiatorMap instance

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(sza: float, earth_sun_distance: float) → Dataset#

Run the TUV-x photolysis calculator.

All parameters (solar zenith angle, Earth-Sun distance, atmospheric profiles, etc.) are read from the JSON configuration file.

Parameters:

sza – Solar zenith angle in radians
earth_sun_distance – Earth-Sun distance in astronomical units (AU)

Returns:

photolysis_rate_constants: Shape (n_reactions, n_vertical_edge) [s^-1]
heating_rates: Shape (n_heating_rates, n_vertical_edge) [K s^-1]
dose_rates: Shape (n_dose_rates, n_vertical_edge) [W m^-2]
actinic_flux: Shape (n_wavelengths, n_vertical_edge, 3 components: direct, upwelling, downwelling) [photons cm^-2 s^-1 nm^-1]
spectral_irradiance: Shape (n_wavelengths, n_vertical_edge, 3 components: direct, upwelling, downwelling) [W m^-2 nm^-1]

Return type:

XArray Dataset with data variables

CARMA#

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(*values)#

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(*values)#

Bases: Enum

Enumeration for gas compositions used in CARMA.

H2O = 1#

H2SO4 = 2#

NONE = 0#

SO2 = 3#

class musica.carma.MieCalculationAlgorithm(*values)#

Bases: Enum

Enumeration for Mie calculation algorithms used in CARMA.

BOHREN_1983 = 2#

BOTET_1997 = 3#

TOON_1981 = 1#

class musica.carma.OpticsAlgorithm(*values)#

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(*values)#

Bases: Enum

Enumeration for particle collection algorithms used in CARMA.

CONSTANT = 1#

DATA = 3#

FUCHS = 2#

NONE = 0#

class musica.carma.ParticleComposition(*values)#

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(*values)#

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(*values)#

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(*values)#

Bases: Enum

Enumeration for particle shapes used in CARMA.

CYLINDER = 3#

HEXAGON = 2#

SPHERE = 1#

class musica.carma.ParticleSwellingAlgorithm(*values)#

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(*values)#

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(*values)#

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(*values)#

Bases: Enum

Enumeration for sulfate nucleation methods used in CARMA.

NONE = 0#

VEHKAMAKI = 2#

ZHAO_TURCO = 1#

class musica.carma.VaporizationAlgorithm(*values)#

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#