JavaScript API#
MusicBox#
- class MusicBox()#
JavaScript implementation of the music-box atmospheric chemistry box model.
Accepts the same music-box v1 JSON config format as the Python implementation. For inline conditions, use conditions.data (array of row objects) — the same format supported by Python’s ConditionsManager.
- Can be built up programmatically instead of from JSON:
const box = new MusicBox(); box.chemTimeStep = 2.0; box.outputTimeStep = 6.0; box.simulationLength = 60.0; box.loadMechanism(mechanismInstanceOrJSON); box.setCondition(0, { temperature: 298.15, concentrations: { A: 1.0 } }); const result = await box.solve();
- static MusicBox.fromJson(jsonObject)#
Create a MusicBox instance from a plain JSON object.
- Arguments:
jsonObject (Object) – music-box v1 config object
- Returns:
MusicBox
- static MusicBox.fromJsonFile(filePath)#
Create a MusicBox instance from a JSON config file, resolving any CSV “conditions.filepaths” relative to it.
- Arguments:
filePath (string) – Path to the config file. A real path on disk in Node; elsewhere it must already be a path in the virtual filesystem (see virtual_fs.js).
- Returns:
Promise.<MusicBox>
- MusicBox.solve()#
Run the chemistry simulation.
- Returns:
Promise.<{columns: Array.<string>, height: number, data: Object.<string, Array.<number>>}> – Result with a columns array of column names, height (number of rows), and data object mapping each column name to its array of values. Columns are time.s, ENV.temperature.K, ENV.pressure.Pa, ENV.air number density.mol m-3, then CONC.<species>.mol m-3.
parseBoxModelOptions#
- parseBoxModelOptions(config)#
Parse box model options from a music-box v1 config object. Converts time values to seconds.
- Arguments:
config (Object) – Full music-box config JSON object
- Returns:
Object
parseConditions#
- parseConditions(conditionsJson)#
Parse inline conditions from a music-box v1 config.
Supports conditions[“data”]: an array of {headers, rows} blocks, matching the format Python’s ConditionsManager already accepts via _load_inline_data. Each block is equivalent to one CSV file.
- Example (two blocks mirroring two CSV files):
- [
- {
“headers”: [“time.s”, “ENV.temperature.K”, “CONC.O3.mol m-3”], “rows”: [[0.0, 217.6, 6.43e-6]]
}, {
“headers”: [“time.s”, “PHOTO.O2_1.s-1”, “PHOTO.O3_1.s-1”], “rows”: [[0, 1.47e-12, 4.25e-5], [3600, 1.12e-13, 1.33e-6]]
}
]
Returns a flat array of row objects for use by ConditionsManager.
- Arguments:
conditionsJson (Object) – The value of config.conditions
- Returns:
Array – Flat array of row objects (empty array if none present)
ConditionsManager#
- class ConditionsManager(dataRows)#
Manages simulation conditions from a flat array of time-indexed row objects.
Accepts the output of parseConditions() — an array of row objects matching the same column naming convention as the CSV files used by Python:
- [
{ “time.s”: 0, “ENV.temperature.K”: 217.6, “CONC.O3.mol m-3”: 6.43e-6, “PHOTO.O2_1.s-1”: 1.47e-12 }, { “time.s”: 3600, “PHOTO.O2_1.s-1”: 1.12e-13 }
]
- Column semantics:
ENV.temperature.K -> temperature (K), step-interpolated ENV.pressure.Pa -> pressure (Pa), step-interpolated ENV.air number density.mol m-3 -> air number density (mol/m³), step-interpolated;
falls back to the ideal gas law (P / (R·T)) when unset
CONC.<species>.<unit> -> concentration event at exact time (not interpolated) PHOTO/EMIS/LOSS/USER.* -> rate parameters, step-interpolated
- Arguments:
dataRows (Array) – Array of row objects from parseConditions()
- ConditionsManager.concentrationEvents#
Concentration events dict: {time: {species: value}}.
- ConditionsManager.getConditionsAtTime(t)#
Get step-interpolated conditions at a given simulation time. Returns the most recent value at or before t for each column.
airDensity stays null until a row sets it, so a single configured value applies from its time point onward; if it’s never set, the caller (state.setConditions) falls back to the ideal gas law.
concentrations is only populated on an exact match – unlike temperature/pressure/ rateParams, a concentration is a one-time perturbation applied at its own time, not a held value.
- Arguments:
t (number) – Simulation time in seconds
- Returns:
Object
Constants#
- BOLTZMANN_CONSTANT#
Boltzmann constant in J/K, used for Ea → C conversion
- GAS_CONSTANT#
Ideal gas constant in J/(mol·K)