MUSICA JavaScript API#

The JavaScript API exposes MUSICA’s MICM chemical kinetics solver through a WebAssembly (WASM) module. For installation and usage examples, see the JavaScript User Guide.

API Reference#

Module Initialization#

initModule()#

Initialize the MUSICA WASM module Must be called before using any WASM functionality

Returns:: Promise.<Object> – The initialized WASM module

getBackend()#

Get the initialized WASM module

Returns:: Object – WASM module

getVersion()#

Get MUSICA version

Returns:: Promise.<string>

getMicmVersion()#

Get MICM version

Returns:: Promise.<string>

Constants#

AVOGADRO#: Avogadro’s number (mol⁻¹)

BOLTZMANN#: Boltzmann constant (J K⁻¹)

GAS_CONSTANT#: Universal gas constant: AVOGADRO × BOLTZMANN (J K⁻¹ mol⁻¹)

Enumerations#

SolverType#

type: number

Enum for solver types

Solver backend selection. Pass to MICM factory methods.

Key	Value	Description
`rosenbrock`	1	Vector-ordered Rosenbrock solver
`rosenbrock_standard_order`	2	Standard-ordered Rosenbrock solver (default)
`backward_euler`	3	Vector-ordered Backward Euler solver
`backward_euler_standard_order`	4	Standard-ordered Backward Euler solver

SolverState#

Enum representing the state of the solver after execution

Outcome of a MICM.solve() call.

Key	Value	Meaning
`NotYetCalled`	0	`solve` has not been called yet
`Running`	1	Solver is executing (internal use)
`Converged`	2	Solution accepted within tolerances
`ConvergenceExceededMaxSteps`	3	Maximum internal steps reached
`StepSizeTooSmall`	4	Step size fell below numerical limit
`RepeatedlySingularMatrix`	5	Jacobian factorisation failed repeatedly
`NaNDetected`	6	NaN appeared in the solution
`InfDetected`	7	Inf appeared in the solution
`AcceptingUnconvergedIntegration`	8	Solution accepted despite not fully converging

Classes#

class Conditions(options)#

Environmental conditions for a single grid cell.

If air_density is not provided and both temperature and pressure are given, air density is computed from the Ideal Gas Law: P / (R * T).

Arguments:

options (Object)
options.temperature (number|null) – Temperature in Kelvin
options.pressure (number|null) – Pressure in Pascals
options.air_density (number|null) – Air number density in mol m⁻³; computed from the Ideal Gas Law when null and both temperature and pressure are set

Conditions.Conditions#

class RosenbrockSolverParameters(options)#

Parameters for configuring Rosenbrock solvers.

Arguments:

options (Object)
options.relative_tolerance (number)
options.absolute_tolerances (Array.<number>|null)
options.h_min (number)
options.h_max (number)
options.h_start (number)
options.max_number_of_steps (number)

RosenbrockSolverParameters.RosenbrockSolverParameters#

class BackwardEulerSolverParameters(options)#

Parameters for configuring Backward Euler solvers.

Arguments:

options (Object)
options.relative_tolerance (number)
options.absolute_tolerances (Array.<number>|null)
options.max_number_of_steps (number)
options.time_step_reductions (Array.<number>) – Must have exactly 5 elements

BackwardEulerSolverParameters.BackwardEulerSolverParameters#

class SolverStats()#

Class representing solver statistics

SolverStats.SolverStats#

class SolverResult(state, stats)#

Class representing the combined solver result

Arguments:

state (number) – The solver state (from SolverState enum)
stats (SolverStats) – The solver statistics

SolverResult.SolverResult#

class MICM(nativeMICM, solverType)#: Private constructor - use static factory methods instead

class State()#

Chemical state for one or more grid cells.

Holds species concentrations, environmental conditions, and user-defined rate parameters. Create via {@link MICM#createState} rather than directly.

State.delete()#: Free the underlying WASM object. Call when done with this instance.

State.getConcentrations()#

Get species concentrations for all grid cells.

Returns:: Object.<string, Array.<number>> – Map of species name to array of concentrations (one element per grid cell) in mol m⁻³.

State.getConditions()#

Get environmental conditions for all grid cells.

Returns:: Array.<{temperature: number, pressure: number, air_density: number}> – One object per grid cell.

State.getNumberOfGridCells()#

Get the number of grid cells in this state.

Returns:: number

State.getUserDefinedRateParameters()#

Get user-defined rate parameters for all grid cells.

Returns:: Object.<string, Array.<number>> – Map of parameter name to array of values (one element per grid cell).

State.setConcentrations(concentrations)#

Set species concentrations.

Arguments:

concentrations (Object.<string, (number|Array.<number>)>) – Map of species name to concentration(s) in mol m⁻³. For a single grid cell, values may be scalars. For multiple grid cells, provide arrays of length numberOfGridCells.

State.setConditions(options)#

Set environmental conditions for each grid cell.

All parameters accept a scalar (single grid cell) or an array of length numberOfGridCells. If airDensities is omitted, air density is computed from the Ideal Gas Law using the provided temperature and pressure.

Arguments:

options (Object)
options.temperatures (number|Array.<number>|null) – Temperature(s) in Kelvin
options.pressures (number|Array.<number>|null) – Pressure(s) in Pascals
options.airDensities (number|Array.<number>|null) – Air number density in mol m⁻³

State.setUserDefinedRateParameters(params)#

Set user-defined rate parameters (e.g. photolysis rates or emission fluxes).

Arguments:

params (Object.<string, (number|Array.<number>)>) – Map of parameter name to value(s). For a single grid cell, values may be scalars. For multiple grid cells, provide arrays of length numberOfGridCells.

Mechanism Configuration#

Classes for building a mechanism configuration in JavaScript and serializing it to MUSICA’s JSON format via getJSON() / getString(). Accessible under mechanismConfiguration (types, reactionTypes, and Mechanism).

class Mechanism(params)#

A complete mechanism — its species, phases, and reactions — serializable to MUSICA’s JSON configuration via {@link Mechanism#getJSON} / {@link Mechanism#getString}.

Arguments:

params (MechanismParams)

Core types#

class Species(params)#

A chemical species and its physical properties. Arbitrary extra properties may be supplied and are preserved on serialization.

Arguments:

params (SpeciesParams)

class PhaseSpecies(params)#

A species as it participates in a particular phase, optionally carrying a phase-specific diffusion coefficient.

Arguments:

params (PhaseSpeciesParams)

class Phase(params)#

A phase (for example the gas phase) and the set of species it contains.

Arguments:

params (PhaseParams)

class ReactionComponent(params)#

A reactant or product entry: a species name and its stoichiometric coefficient (defaulting to 1.0). A component always refers to a species, so the reference is simply name.

Arguments:

params (ReactionComponentParams)

Reaction types#

Every reaction class exposes its mechanism-configuration type string as both a static property (e.g. Arrhenius.type) and an instance property (new Arrhenius(...).type).

class Arrhenius(params)#

Arrhenius reaction-rate expression.

Arguments:

params (ArrheniusParams)

Arrhenius.type#: type: ‘ARRHENIUS’

class Branched(params)#

Branched (no-RO2) reaction-rate expression producing separate nitrate and alkoxy product channels.

Arguments:

params (BranchedParams)

Branched.type#: type: ‘BRANCHED_NO_RO2’

class Emission(params)#

Emission of one or more species at a scaled rate.

Arguments:

params (EmissionParams)

Emission.type#: type: ‘EMISSION’

class FirstOrderLoss(params)#

First-order loss of one or more species at a scaled rate.

Arguments:

params (FirstOrderLossParams)

FirstOrderLoss.type#: type: ‘FIRST_ORDER_LOSS’

class Photolysis(params)#

Photolysis reaction driven by a scaled photolysis rate.

Arguments:

params (PhotolysisParams)

Photolysis.type#: type: ‘PHOTOLYSIS’

class Surface(params)#

Surface (heterogeneous) reaction characterized by a reaction probability.

Arguments:

params (SurfaceParams)

Surface.type#: type: ‘SURFACE’

class TaylorSeries(params)#

Taylor-series reaction-rate expression.

Arguments:

params (TaylorSeriesParams)

TaylorSeries.type#: type: ‘TAYLOR_SERIES’

class Troe(params)#

Troe falloff reaction-rate expression.

Arguments:

params (TroeLikeParams)

Troe.type#: type: ‘TROE’

class TernaryChemicalActivation(params)#

Ternary chemical-activation reaction-rate expression.

Arguments:

params (TroeLikeParams)

TernaryChemicalActivation.type#: type: ‘TERNARY_CHEMICAL_ACTIVATION’

class Tunneling(params)#

Wigner tunneling reaction-rate expression.

Arguments:

params (TunnelingParams)

Tunneling.type#: type: ‘TUNNELING’

class UserDefined(params)#

User-defined reaction whose rate is supplied externally.

Arguments:

params (UserDefinedParams)

UserDefined.type#: type: ‘USER_DEFINED’

class LambdaRateConstant(params)#

Reaction whose rate constant is provided by a lambda callback (a C++ lambda string for the parser, or a JavaScript callback set at runtime).

Arguments:

params (LambdaRateConstantParams)

LambdaRateConstant.type#: type: ‘LAMBDA_RATE_CONSTANT’

MUSICA JavaScript API#

API Reference#

Module Initialization#

Constants#

Enumerations#

Classes#

Mechanism Configuration#

Core types#

Reaction types#

Further Reading#