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

property constraint_init_tolerance#

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

rosenbrock_dae4

rosenbrock_dae4_standard_order

rosenbrock_dae6

rosenbrock_dae6_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_dae4 = <_SolverType.rosenbrock_dae4: 6>#

rosenbrock_dae4_standard_order = <_SolverType.rosenbrock_dae4_standard_order: 7>#

rosenbrock_dae6 = <_SolverType.rosenbrock_dae6: 8>#

rosenbrock_dae6_standard_order = <_SolverType.rosenbrock_dae6_standard_order: 9>#

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._Aerosol#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property constraints#

property processes#

property representations#

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._DiagnoseFromState#

Bases: pybind11_object

_pybind11_conduit_v1_()#

class musica._musica._mechanism_configuration._DissolvedEquilibrium#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property algebraic_species#

property equilibrium_constant#

property phase#

property products#

property reactants#

property solvent#

property solvent_floor#

class musica._musica._mechanism_configuration._DissolvedReaction#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property min_halflife#

property phase#

property products#

property rate_constant#

property reactants#

property solvent#

property solvent_floor#

class musica._musica._mechanism_configuration._DissolvedReversibleReaction#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property equilibrium_constant#

property forward_rate_constant#

property phase#

property products#

property reactants#

property reverse_rate_constant#

property solvent#

property solvent_floor#

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._EmissionsConfig#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property inventories#

property regridding#

property sources#

property species_maps#

class musica._musica._mechanism_configuration._Equilibrium#

Bases: pybind11_object

property A#

property C#

property T0#

_pybind11_conduit_v1_()#

class musica._musica._mechanism_configuration._FirstOrderLoss#

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._FixedConstant#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property value#

class musica._musica._mechanism_configuration._HenrysLawConstant#

Bases: pybind11_object

property C#

property HLC_ref#

property T0#

_pybind11_conduit_v1_()#

class musica._musica._mechanism_configuration._HenrysLawEquilibrium#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property condensed_phase#

property condensed_species#

property gas_phase#

property gas_species#

property henrys_law_constant#

property solvent#

property solvent_density#

property solvent_molecular_weight#

class musica._musica._mechanism_configuration._HenrysLawPhaseTransfer#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property accommodation_coefficient#

property condensed_phase#

property condensed_species#

property diffusion_coefficient#

property gas_phase#

property gas_species#

property henrys_law_constant#

property solvent#

class musica._musica._mechanism_configuration._Inventory#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property convention#

property directory#

property file_pattern#

property name#

class musica._musica._mechanism_configuration._LinearConstraint#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property algebraic_phase#

property algebraic_species#

property constant#

property terms#

class musica._musica._mechanism_configuration._LinearConstraintTerm#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property coefficient#

property name#

property phase#

class musica._musica._mechanism_configuration._Mechanism#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property aerosol#

property emissions#

property name#

property phases#

property reactions#

property relative_tolerance#

property species#

property version#

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

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

property other_properties#

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._Regridding#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property type#

class musica._musica._mechanism_configuration._RegriddingType#

Bases: pybind11_object

Members:

None_

None_ = <_RegriddingType.None_: 0>#

_pybind11_conduit_v1_()#

_RegriddingType.name -> str

property value#

class musica._musica._mechanism_configuration._SingleMomentMode#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property geometric_mean_radius#

property geometric_standard_deviation#

property name#

property phases#

class musica._musica._mechanism_configuration._SourceDescriptor#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property category#

property hierarchy#

property inventory#

property mode#

property name#

property other_properties#

property scaling_factor#

property sector#

property species_map#

property temporal_interpolation#

property type#

property vertical_injection#

class musica._musica._mechanism_configuration._SourceMode#

Bases: pybind11_object

Members:

Offline

Offline = <_SourceMode.Offline: 0>#

_pybind11_conduit_v1_()#

_SourceMode.name -> str

property value#

class musica._musica._mechanism_configuration._SourceType#

Bases: pybind11_object

Members:

Anthropogenic

Fire

Biogenic

Dust

SeaSalt

Lightning

Anthropogenic = <_SourceType.Anthropogenic: 0>#

Biogenic = <_SourceType.Biogenic: 2>#

Dust = <_SourceType.Dust: 3>#

Fire = <_SourceType.Fire: 1>#

Lightning = <_SourceType.Lightning: 5>#

SeaSalt = <_SourceType.SeaSalt: 4>#

_pybind11_conduit_v1_()#

_SourceType.name -> str

property value#

class musica._musica._mechanism_configuration._Species#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property constant_concentration_mol_m3#

property constant_mixing_ratio_mol_mol#

property density_kg_m3#

property is_third_body#

property molecular_weight_kg_mol#

property name#

property other_properties#

class musica._musica._mechanism_configuration._SpeciesMap#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property mappings#

property name#

class musica._musica._mechanism_configuration._SpeciesMapping#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property inventory_species#

property mechanism_species#

property scaling_factor#

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._TemporalInterpolation#

Bases: pybind11_object

Members:

Linear

Nearest

None_

Linear = <_TemporalInterpolation.Linear: 0>#

Nearest = <_TemporalInterpolation.Nearest: 1>#

None_ = <_TemporalInterpolation.None_: 2>#

_pybind11_conduit_v1_()#

_TemporalInterpolation.name -> str

property value#

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._TwoMomentMode#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property geometric_standard_deviation#

property name#

property phases#

class musica._musica._mechanism_configuration._UniformSection#

Bases: pybind11_object

_pybind11_conduit_v1_()#

property max_radius#

property min_radius#

property name#

property phases#

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._VerticalInjection#

Bases: pybind11_object

Members:

Surface

Surface = <_VerticalInjection.Surface: 0>#

_pybind11_conduit_v1_()#

_VerticalInjection.name -> str

property value#

musica._musica._mechanism_configuration._parse(arg0: str) → musica._musica._mechanism_configuration._Mechanism#

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

Aerosol configuration attached to a Mechanism.

Collects the representations, processes, and constraints that define an aerosol or cloud system. Species and phases are defined on the owning Mechanism; aerosol entries reference them by object (resolved to names).

representations#: Aerosol/cloud representations.

processes#: Aqueous-phase processes.

constraints#: Algebraic equilibrium constraints.

serialize() → Dict#

Serialize to the two top-level mechanism configuration aerosol sections.

Returns a dict with "aerosol representations" and "aerosol processes" keys. In the configuration format, processes and constraints share the single "aerosol processes" section, so both are emitted there. The returned keys are merged into the owning Mechanism’s top-level configuration.

set_default_parameters(state)#

Set each representation’s default parameters on a MICM state.

Delegates to every representation’s set_default_parameters.

Parameters:: state – A musica.micm.State object.

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.

class musica.mechanism_configuration.DiagnoseFromState#

Bases: CppWrapper

RHS constant of a LinearConstraint computed per representation instance.

Bases: CppWrapper

Dissolved (aqueous-phase) equilibrium constraint.

phase#: Name of the condensed phase.

algebraic_species#: Name of the species solved for algebraically.

solvent#: Name of the solvent species.

reactants#: Reactant components.

products#: Product components.

equilibrium_constant#: Equilibrium constant.

solvent_floor#: Floor added to the solvent concentration in the rate denominator [mol m-3].

Bases: CppWrapper

Irreversible dissolved (aqueous-phase) reaction.

phase#: Name of the condensed phase where the reaction occurs.

solvent#: Name of the solvent species.

reactants#: Reactant components.

products#: Product components.

rate_constant#: Rate constant for the reaction.

solvent_floor#: Floor added to the solvent concentration in the rate denominator [mol m-3].

min_halflife#: Minimum reactant half-life used to cap the rate [s].

Bases: CppWrapper

Reversible dissolved (aqueous-phase) reaction.

Supply two of {forward, reverse, equilibrium}; the third is derived by the model.

phase#: Name of the condensed phase where the reaction occurs.

solvent#: Name of the solvent species.

reactants#: Reactant components.

products#: Product components.

forward_rate_constant#: Forward rate constant for the reaction.

reverse_rate_constant#: Reverse rate constant for the reaction.

equilibrium_constant#: Shared intrinsic equilibrium constant.

solvent_floor#: Floor added to the solvent concentration in the rate denominator [mol m-3].

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.

class musica.mechanism_configuration.EmissionsConfig(inventories: List[Inventory] | None = None, species_maps: List[SpeciesMap] | None = None, regridding: Regridding | None = None, sources: List[SourceDescriptor] | None = None)#

Bases: CppWrapper

Emissions configuration: inventories, species maps, regridding, and sources.

inventories#: A list of Inventory objects.

species_maps#: A list of SpeciesMap objects.

regridding#: The Regridding specification.

sources#: A list of SourceDescriptor objects.

class musica.mechanism_configuration.Equilibrium(A: float | None = None, C: float | None = None, T0: float | None = None)#

Bases: CppWrapper

Reference-temperature Arrhenius rate constant.

f(T) = A * exp( C * (1/T0 - 1/T) ) (C = +Ea/R)

A#: Value at the reference temperature T0 [units vary by use].

C#: Temperature-dependence parameter [K] (C = +Ea/R).

T0#: Reference temperature [K].

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.

products#: A list of products formed in the reaction. Normally, first-order loss reactions do not have products, but this can be used to compute the integrated reaction rate

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.FixedConstant(value: float | None = None)#

Bases: CppWrapper

Fixed RHS constant of a LinearConstraint, shared by all instances.

value#: Fixed value [mol m-3].

class musica.mechanism_configuration.HenrysLawConstant(HLC_ref: float | None = None, C: float | None = None, T0: float | None = None)#

Bases: CppWrapper

Henry’s law constant: HLC(T) = HLC_ref * exp( C * (1/T - 1/T0) ).

HLC_ref#: Reference HLC at T0 [mol m-3 Pa-1].

C#: Temperature-dependence parameter [K].

T0#: Reference temperature [K].

Bases: CppWrapper

Henry’s law equilibrium constraint.

gas_phase#: Name of the gas phase.

gas_species#: Name of the gas-phase species.

condensed_phase#: Name of the condensed phase.

condensed_species#: Name of the condensed-phase species.

solvent#: Name of the solvent species.

henrys_law_constant#: Henry’s law constant.

solvent_molecular_weight#: Solvent molecular weight [kg mol-1].

solvent_density#: Solvent density [kg m-3].

Bases: CppWrapper

Henry’s law gas-to-aqueous phase transfer.

gas_phase#: Name of the gas phase.

gas_species#: Name of the gas-phase species.

condensed_phase#: Name of the condensed phase receiving the species.

condensed_species#: Name of the dissolved species in the condensed phase.

solvent#: Name of the solvent species in the condensed phase.

henrys_law_constant#: Henry’s law constant with temperature dependence.

diffusion_coefficient#: Gas-phase diffusion coefficient [m2 s-1].

accommodation_coefficient#: Mass accommodation coefficient [-].

class musica.mechanism_configuration.Inventory(name: str | None = None, directory: str | None = None, file_pattern: str | None = None, convention: str | None = None)#

Bases: CppWrapper

An emissions inventory file source.

name#: The name of the inventory, referenced by SourceDescriptor.inventory.

directory#: Directory containing the inventory files.

file_pattern#: File name pattern, with optional {YYYY}{MM}{DD}{HH} tokens.

convention#: The on-disk inventory convention (e.g. “eccad”, “uptempo”).

Bases: CppWrapper

A linear algebraic constraint: G = sum(coeff_i * [species_i]) - C = 0.

algebraic_phase#: Name of the phase of the algebraic species.

algebraic_species#: Name of the species solved for algebraically.

terms#: The constraint terms.

constant#: A FixedConstant or DiagnoseFromState (defaults to FixedConstant(0)).

Bases: CppWrapper

A single term of a LinearConstraint: coefficient * [species] in a phase.

phase#: Name of the phase.

species#: Name of the species.

coefficient#: Term coefficient.

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.

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

version#: The version of the mechanism.

property aerosol: Aerosol | None#: Aerosol configuration (representations, processes, constraints), or None.

property emissions: EmissionsConfig | None#: Emissions configuration (inventories, species maps, sources), or None.

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.Phase(name: str | None = None, species: List[Species | 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.

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

density_kg_m3#: Density in the phase [kg m-3].

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.

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.Regridding(type: _RegriddingType | None = None)#

Bases: CppWrapper

Horizontal regridding specification for a Mechanism’s emissions.

type#: RegriddingType (only RegriddingType.None_ is currently supported).

musica.mechanism_configuration.RegriddingType#: alias of _RegriddingType

Bases: CppWrapper

A single-moment modal aerosol representation.

name#: The name of the representation.

phases#: Names of the phases carried by this mode.

geometric_mean_radius#: Geometric mean radius [m].

geometric_standard_deviation#: Geometric standard deviation [-].

set_default_parameters(state)#: Set this mode’s default size parameters on a MICM state (as rate parameters).

Bases: CppWrapper

Description of a single emission source.

name#: Diagnostic name for the source.

mode#: SourceMode (offline vs online).

type#: SourceType (inventory sector).

inventory#: Name of the referenced Inventory.

species_map#: Name of the referenced SpeciesMap.

temporal_interpolation#: TemporalInterpolation scheme between time slices.

vertical_injection#: VerticalInjection (where emissions are deposited).

category#: HEMCO-style category (sources in different categories are summed).

hierarchy#: HEMCO-style hierarchy (highest wins within a category).

scaling_factor#: Overall scaling factor applied to this source.

sector#: Diagnostic sector name.

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

musica.mechanism_configuration.SourceMode#: alias of _SourceMode

musica.mechanism_configuration.SourceType#: alias of _SourceType

class musica.mechanism_configuration.Species(name: str | None = None, molecular_weight_kg_mol: float | None = None, density_kg_m3: 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].

density_kg_m3#: Density [kg m-3].

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.

class musica.mechanism_configuration.SpeciesMap(name: str | None = None, mappings: List[SpeciesMapping] | None = None)#

Bases: CppWrapper

A named collection of inventory-to-mechanism species mappings.

name#: The name of the species map.

mappings#: The list of SpeciesMapping entries.

class musica.mechanism_configuration.SpeciesMapping(inventory_species: str | None = None, mechanism_species: str | None = None, scaling_factor: float | None = None)#

Bases: CppWrapper

A single inventory-species to mechanism-species mapping.

inventory_species#: Name of the species as it appears in the inventory file.

mechanism_species#: Name of the mechanism species it contributes flux to.

scaling_factor#: Fraction of the inventory species’ flux applied to this mapping.

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.

musica.mechanism_configuration.TemporalInterpolation#: alias of _TemporalInterpolation

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.

class musica.mechanism_configuration.TwoMomentMode(name: str | None = None, phases: List[Phase | str] | None = None, geometric_standard_deviation: float | None = None)#

Bases: CppWrapper

A two-moment modal aerosol representation.

name#: The name of the representation.

phases#: Names of the phases carried by this mode.

geometric_standard_deviation#: Geometric standard deviation [-].

set_default_parameters(state)#: Set this mode’s default size parameter on a MICM state (as rate parameters).

Bases: CppWrapper

A uniform (sectional) aerosol representation.

name#: The name of the representation.

phases#: Names of the phases carried by this section.

min_radius#: Minimum section radius [m].

max_radius#: Maximum section radius [m].

set_default_parameters(state)#: Set this section’s default radius bounds on a MICM state (as rate parameters).

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.

musica.mechanism_configuration.VerticalInjection#: alias of _VerticalInjection

musica.mechanism_configuration.parse(path: str)#

Parse a mechanism configuration file.

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

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, external_models: List[Any] | 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, constraint_init_max_iterations: int = 10, constraint_init_tolerance: float = 1e-10)#

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

constraint_init_max_iterations#

Maximum Newton iterations for DAE constraint initialization (default: 10).

Type:: int

constraint_init_tolerance#

Convergence tolerance for DAE constraint initialization (default: 1e-10).

Type:: float

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#