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.

Further Reading#