acom-music-box 3.0.2

An atmospheric chemistry box model. Powered by MUSICA.

acom_music_box (Python)

Python implementation of the MusicBox atmospheric chemistry box model, built on the MUSICA framework.

Installation

pip install acom_music_box

GPU Support

GPU-accelerated solving requires the NVIDIA PyPI index:

pip install --upgrade setuptools pip wheel
pip install nvidia-pyindex
pip install acom_music_box[gpu]

Quick Start

In-code mechanism

Define species, reactions, and initial conditions entirely in Python:

from acom_music_box import MusicBox, Conditions
import musica.mechanism_configuration as mc

# Define species
A = mc.Species(name="A")
B = mc.Species(name="B")
C = mc.Species(name="C")

gas = mc.Phase(name="gas", species=[A, B, C])

# Define reactions
arr1 = mc.Arrhenius(name="A->B", A=4.0e-3, C=50, reactants=[A], products=[B], gas_phase=gas)
arr2 = mc.Arrhenius(name="B->C", A=1.2e-4, B=2.5, C=75, D=50, E=0.5, reactants=[B], products=[C], gas_phase=gas)

mechanism = mc.Mechanism(name="example", species=[A, B, C], phases=[gas], reactions=[arr1, arr2])

# Create and configure the box model
box = MusicBox()
box.load_mechanism(mechanism)

box.initial_conditions = Conditions(
    temperature=300.0,
    pressure=101000.0,
    species_concentrations={"A": 1.0, "B": 3.0, "C": 5.0},
)

# Optionally add evolving conditions at a specific time (seconds)
box.add_evolving_condition(300.0, Conditions(
    temperature=290.0,
    pressure=100200.0,
    species_concentrations={"A": 1.0, "B": 3.0, "C": 10.0},
))

box.box_model_options.simulation_length = 20   # seconds
box.box_model_options.chem_step_time = 1       # seconds
box.box_model_options.output_step_time = 4     # seconds

df = box.solve()
print(df)

From a JSON configuration file

Load a music-box v1 JSON config from disk:

from acom_music_box import MusicBox

box = MusicBox()
box.readConditionsFromJson("my_config.json")
df = box.solve()
print(df)

Plotting results

import matplotlib.pyplot as plt

df.plot(
    x='time.s',
    y=['CONC.A.mol m-3', 'CONC.B.mol m-3', 'CONC.C.mol m-3'],
    title='Concentration over time',
    ylabel='Concentration (mol m-3)',
    xlabel='Time (s)',
)
plt.show()

Command Line Tool

MusicBox includes a music_box CLI for running configurations and built-in examples.

music_box -h

Run a built-in example (output printed to terminal as CSV):

music_box -e Chapman

Save output to a file:

music_box -e Chapman -o output.csv
music_box -e Chapman -o output.nc        # NetCDF format
music_box -e Analytical -o results.csv -o results.nc   # multiple outputs

Run your own configuration:

music_box -c my_config.json

Plotting from the CLI

Plot species concentrations using matplotlib:

music_box -e Chapman -o output.csv --plot O1D

Plot multiple species groups:

music_box -e TS1 --plot O3 --plot PAN,HF

Change output units (default is mol m-3):

music_box -e TS1 --plot O3 --plot-output-unit ppb

Tool: waccmToMusicBox

This tool allows you to extract chemical species concentrations from WACCM or WRF-Chem model output and write them as MusicBox initial conditions. Use the built-in help to display all options including template configurations and multiple output formats:

waccmToMusicBox --help

You may specify a single point in space and date-time by passing single values to date, time, latitude, and longitude. Altitude defaults to the surface. You may also specify a rectangle or cube by specifying multiple values for latitude, longitude, and altitude. Use a lat-lon variable (PBLH) to bound the vertical dimension at a specific height. If you request two date-time pairs, the tool will create evolving conditions over time rather than initial conditions.

waccmToMusicBox --waccmDir "./sample_waccm_data" --date "20260208" --time "07:00" --latitude 3.1 --longitude 101.7 --verbose

waccmToMusicBox --wrfchemDir "./sample_waccm_data" --date "20250820" --time "08:00" --latitude 47.0,49.0 --longitude "'-123.0,-121.0'"

waccmToMusicBox uses MUSICA configuration file to create a list of common chemical species between MusicBox and WACCM or WRF-Chem. The default configuration file is in the ts1 example because that example has many species. Use the --template parameter to specify your own configuration file (usually my_config.json).

waccmToMusicBox --wrfchemDir ~/MusicBox/WRF-Chem/model-output --date 20250820,20250822 --time 18:00,05:00 --stride 3 --latitude 47.0,49.0 --longitude "'-123.0,-121.0'" --altitude surface,PBLH --template ./examples/ts1 --output evolving_conditions.csv --verbose

waccmToMusicBox --waccmDir ~/MusicBox/WACCM/model-output --date 20240301,20240304 --time 17:00,04:00 --latitude "'-4.0,-2.0'" --longitude 101.0,103.0 --altitude 567.8,4567.8 --template ./examples/ts1 --output conditions/evolving_conditions.csv --verbose -v

Development

Install as an editable package with dev dependencies:

pip install -e '.[dev]'

Run the test suite:

pytest

Run only unit or integration tests:

pytest python/tests/unit/
pytest python/tests/integration/