Configuration Files#

MusicBox accepts a JSON configuration file that describes the box model options, chemical mechanism, and simulation conditions. The same JSON format is understood by both the Python and JavaScript implementations.

The top-level structure of a configuration file looks like this:

{
  "box model options": { ... },
  "mechanism": { ... },
  "conditions": { ... }
}

To load a configuration file:

Python: use acom_music_box.music_box.MusicBox.loadJson()
JavaScript: use MusicBox.fromJson(configObject) or await MusicBox.fromJsonFile(path)

Box Model Options#

The "box model options" key controls simulation timing:

{
  "box model options": {
    "grid": "box",
    "chemistry time step [min]": 1.0,
    "output time step [min]": 1.0,
    "simulation length [day]": 3.0
  }
}

Time values may be specified in any of the following units by appending the unit in square brackets: [s], [min], [hr], or [day].

Mechanism#

The "mechanism" key defines the chemical system following the mc:index v1 format. It contains three sub-keys: species, phases, and reactions.

{
  "mechanism": {
    "version": "1.0.0",
    "name": "my_mechanism",
    "species": [
      { "name": "O3" },
      { "name": "O" }
    ],
    "phases": [
      { "name": "gas", "species": ["O3", "O"] }
    ],
    "reactions": [
      {
        "type": "ARRHENIUS",
        "gas phase": "gas",
        "name": "O3_decomposition",
        "reactants": [ { "species name": "O3" } ],
        "products":  [ { "species name": "O" } ],
        "A": 1.0e-3,
        "Ea": 1.5e-20
      }
    ]
  }
}

Supported reaction types include ARRHENIUS, PHOTOLYSIS, TROE, and others. See the mc:reactions page for the full list of types and their parameters.

Conditions#

The "conditions" key provides environmental data (temperature, pressure, photolysis rates, etc.) and species concentrations over time. Two formats are supported for supplying this data; both keys may appear together in the same config and their rows are merged.

Key	Supported by	Description
`data`	Python and JavaScript	Inline array of `{headers, rows}` blocks
`filepaths`	Python and Node.js	List of CSV file paths, resolved relative to the config file

Inline data (`data`)#

An array of {headers, rows} blocks — one block per logical data source, equivalent to one CSV file. This format works in both Python and JavaScript (including browser environments).

{
  "conditions": {
    "data": [
      {
        "headers": ["time.s", "ENV.temperature.K", "ENV.pressure.Pa", "CONC.O3.mol m-3"],
        "rows": [[0.0, 217.6, 1394.3, 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]
        ]
      }
    ]
  }
}

CSV filepaths (`filepaths`) — Python and Node.js#

A list of CSV file paths, resolved relative to the config JSON file. Each CSV file has a header row and one or more data rows. This format is not available in browser JavaScript environments.

{
  "conditions": {
    "filepaths": ["initial_concentrations.csv", "conditions.csv"]
  }
}

Both keys may be used together; rows from all sources are merged in the order they appear.

Column Naming#

Condition columns follow this naming convention regardless of whether data is loaded from CSV files (Python) or inline arrays (JavaScript):

Column	Example	Description
`time.s`	`0.0`	Time in seconds. Required in every data block.
`ENV.temperature.K`	`217.6`	Air temperature in Kelvin. Step-interpolated.
`ENV.pressure.Pa`	`1394.3`	Air pressure in Pascals. Step-interpolated.
`CONC.<species>.mol m-3`	`6.43e-6`	Species concentration in mol m⁻³. Applied as a concentration event at its exact time only.
`PHOTO.<name>.s-1`	`1.47e-12`	Photolysis rate in s⁻¹. Step-interpolated.
`EMIS.<name>.<unit>`	`0.001`	Emission rate. Step-interpolated.
`LOSS.<name>.<unit>`	`0.001`	Loss rate. Step-interpolated.
`USER.<name>.<unit>`	`1.0`	User-defined rate parameter. Step-interpolated.

CONC.* columns are treated as concentration events and applied only at their exact time. All other columns use step interpolation — the most recent value is held until the next time point.