MUSICA is a Python library for performing computational simulations in atmospheric chemistry.

These details have not been verified by PyPI

Project links

homepage

Project description

MUSICA

Multi-Scale Infrastructure for Chemistry and Aerosols

MUSICA is a collection of modeling software, tools, and grids, that allow for robust modeling of chemistry in Earth's atmosphere.

At present the project encompasses these core components

TUV-x
- A photolysis rate calculator
MICM
- Model Independent Chemical Module
Mechanism Configuration
- The standardized format to describe atmospheric chemistry

These components are used to drive the MUSICA software ecosystem. This is a snapshot of how MUSICA can be used with different models.

MUSICA Ecosystem

Installation

MUSICA is installable via pip for Python or CMake for C++.

Pip

pip install musica

CMake

$ git clone https://github.com/NCAR/musica.git
$ cd musica
$ mkdir build
$ cd build
$ ccmake ..
$ make
$ make install

Using the MUSICA Python API

MUSICA makes its chemical mechanism analysis and visualization available through a Python API. The following example works through solving a simple chemistry system. Please refer to the official documentation for further tutorials and examples.

# --- Import Musica ---
import musica
import musica.mechanism_configuration as mc

# --- 1. Define the chemical system of interest ---
A = mc.Species(name="A")
B = mc.Species(name="B")
C = mc.Species(name="C")
species = [A, B, C]
gas = mc.Phase(name="gas", species=species)

# --- 2. Define a mechanism of interest ---
# Through Musica, several different mechanisms can be explored to define reaction rates. Here, we use the Arrhenius equation as a simple example.

r1 = mc.Arrhenius(name="A->B", A=4.0e-3, C=50, reactants=[A], products=[B], gas_phase=gas)
r2 = 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="musica_example", species=species, phases=[gas], reactions=[r1, r2])

# --- 3. Create MICM solver ---
# A solver must be initialized with either a configuration file or a mechanism:

solver = musica.MICM(mechanism=mechanism, solver_type=musica.SolverType.rosenbrock_standard_order)

# --- 4. Define environmental conditions ---
temperature=300.0
pressure=101000.0

# --- 5. Create and initialize State ---
# In the model, conditions represent the starting environment for the reactions and are assigned by modifying the state.

state = solver.create_state()
state.set_concentrations({"A": 1.0, "B": 3.0, "C": 5.0})
state.set_conditions(temperature, pressure)
initial_pressure = state.get_conditions()['air_density'][0] # store for visualization and output

# --- 6. Time parameters ---
time_step = 4  # stepping
sim_length = 20  # total simulation time

# --- (Optional) 7. Save initial state (t=0) for output visualization ---
initial_row = {"time.s": 0.0, "ENV.temperature.K": temperature, "ENV.pressure.Pa": pressure, "ENV.air number density.mol m-3": state.get_conditions()['air_density'][0]}
initial_row.update({f"CONC.{k}.mol m-3": v[0] for k, v in state.get_concentrations().items()})

# --- 8. Solve through time loop only ---
# The following loop simply solves the model per each time step:

curr_time = time_step
while curr_time <= sim_length:
    solver.solve(state, time_step)
    concentrations = state.get_concentrations()
    curr_time += time_step

# --- 9. Solve and create DataFrame ---
# It is likely more useful to solve at each time step and store the associated data:
import pandas as pd

output_data = [] # prepare to store output per time step
output_data.append(initial_row) # save t=0 data

curr_time = time_step
while curr_time <= sim_length:
    solver.solve(state, time_step)
    row = {
        "time.s": curr_time,
        "ENV.temperature.K": state.get_conditions()['temperature'][0],
        "ENV.pressure.Pa": state.get_conditions()['pressure'][0],
        "ENV.air number density.mol m-3": state.get_conditions()['air_density'][0]
    }
    row.update({f"CONC.{k}.mol m-3": v[0] for k, v in state.get_concentrations().items()})
    output_data.append(row)
    curr_time += time_step

df = pd.DataFrame(output_data)
print(df)

# --- 10. Visualize Specific 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()

Available grids

Pre-made grids for use in MUSICA are available here.

Developer Options

Specifying dependency versions via parameterization at configure time

Introduced in Pull Request #124, it is possible for developers to specify which versions of various dependencies should be used. These options are currently limited to those dependencies managed via FetchContent. This change allows for more easily testing musica against changes committed in different repositories and branches. The environmental variables introduced are outlined in the following table.

CMake Dependency Variables

Musica Dependency	Repository	Branch, Tag or Hash
Google Test	GOOGLETEST_GIT_REPOSITORY	GOOGLETEST_GIT_TAG
MICM	MICM_GIT_REPOSITORY	MICM_GIT_TAG
TUV-X	TUVX_GIT_REPOSITORY	TUVX_GIT_TAG
PyBind11	PYBIND11_GIT_REPOSITORY	PYBIND11_GIT_TAG
Mechanism Configuration	MECH_CONFIG_GIT_REPOSITORY	MECH_CONFIG_GIT_TAG

Example Usage

The following examples assume the working directory is a build/ directory inside the musica source directory.

Specifying a different version of tuv-x, to ensure a change won't break anything.

$ cmake .. \
    -DTUVX_GIT_REPOSITORY="https://github.com/WardF/tuv-x.git" \
    -DTUVX_GIT_TAG=test-fix

Specifying a specific version of tuv-x by has, but using the official repository.

$ cmake .. \
    -DTUVX_GIT_TAG=a6b2c4d8745

Python build

Musica has python bindings. If you want to install the python package, you may pip install musica.

PyPi

If you only want to use the CPU components,

pip install musica

Note that GPU support has only been tested on linux. If you have an NVIDIA GPU and would like to take advantage of our GPU solver, you must first add the NVIDIA pypi index and then install musica with our gpu option.

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

Local build

Musica has python bindings. To build the package locally,

pip install -e .

If you have an NVIDIA GPU and cuda installed, you can enable a build of musica with GPU support by setting the environment variable BUILD_GPU.

BUILD_GPU=1 pip install -e .

Contributing

We welcome contributions from the community! Please see our Contributing Guide for information on how to get involved.

For a complete list of contributors and authors, see AUTHORS.md.

Citations

MUSICA can be cited in at least two ways:

Cite the foundational paper that defines the vision of the MUSICA software:

Pfister et al., 2020, Bulletin of the American Meteorological Society

Use the following BibTeX entry:

@Article { acom.software.musica-vision,
    author = "Gabriele G. Pfister and Sebastian D. Eastham and Avelino F. Arellano and Bernard Aumont and Kelley C. Barsanti and Mary C. Barth and Andrew Conley and Nicholas A. Davis and Louisa K. Emmons and Jerome D. Fast and Arlene M. Fiore and Benjamin Gaubert and Steve Goldhaber and Claire Granier and Georg A. Grell and Marc Guevara and Daven K. Henze and Alma Hodzic and Xiaohong Liu and Daniel R. Marsh and John J. Orlando and John M. C. Plane and Lorenzo M. Polvani and Karen H. Rosenlof and Allison L. Steiner and Daniel J. Jacob and Guy P. Brasseur",
    title = "The Multi-Scale Infrastructure for Chemistry and Aerosols (MUSICA)",
    journal = "Bulletin of the American Meteorological Society",
    year = "2020",
    publisher = "American Meteorological Society",
    address = "Boston MA, USA",
    volume = "101",
    number = "10",
    doi = "10.1175/BAMS-D-19-0331.1",
    pages= "E1743 - E1760",
    url = "https://journals.ametsoc.org/view/journals/bams/101/10/bamsD190331.xml"
}

Cite the MUSICA software and its evaluation (MUSICAv0):

Schwantes et al., 2022, Journal of Advances in Modeling Earth Systems

Use the following BibTeX entry:

@Article{acom.software.musica,
    author = {Schwantes, Rebecca H. and Lacey, Forrest G. and Tilmes, Simone and Emmons, Louisa K. and Lauritzen, Peter H. and Walters, Stacy and Callaghan, Patrick and Zarzycki, Colin M. and Barth, Mary C. and Jo, Duseong S. and Bacmeister, Julio T. and Neale, Richard B. and Vitt, Francis and Kluzek, Erik and Roozitalab, Behrooz and Hall, Samuel R. and Ullmann, Kirk and Warneke, Carsten and Peischl, Jeff and Pollack, Ilana B. and Flocke, Frank and Wolfe, Glenn M. and Hanisco, Thomas F. and Keutsch, Frank N. and Kaiser, Jennifer and Bui, Thao Paul V. and Jimenez, Jose L. and Campuzano-Jost, Pedro and Apel, Eric C. and Hornbrook, Rebecca S. and Hills, Alan J. and Yuan, Bin and Wisthaler, Armin},
    title = {Evaluating the Impact of Chemical Complexity and Horizontal Resolution on Tropospheric Ozone Over the Conterminous US With a Global Variable Resolution Chemistry Model},
    journal = {Journal of Advances in Modeling Earth Systems},
    volume = {14},
    number = {6},
    pages = {e2021MS002889},
    doi = {https://doi.org/10.1029/2021MS002889},
    url = {https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2021MS002889},
    eprint = {https://agupubs.onlinelibrary.wiley.com/doi/pdf/10.1029/2021MS002889},
    year = {2022}
}

Project details

These details have not been verified by PyPI

Project links

homepage

Release history Release notifications | RSS feed

This version

0.12.0

Jun 25, 2025

0.11.1.4

Jun 11, 2025

0.11.1.3

May 28, 2025

0.11.1.2

May 27, 2025

0.11.1.1

May 23, 2025

0.11.1

May 15, 2025

0.10.1

Apr 8, 2025

0.10.0

Apr 4, 2025

0.9.0

Dec 19, 2024

0.8.1

Oct 3, 2024

0.8.0

Sep 26, 2024

0.7.3

Aug 7, 2024

0.7.1

Aug 7, 2024

0.7.0

Jun 28, 2024

0.6.1

Apr 8, 2024

0.6.1.dev0 pre-release

Apr 10, 2024

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

musica-0.12.0.tar.gz (1.3 MB view details)

Uploaded Jun 25, 2025 Source

Built Distributions

musica-0.12.0-cp312-cp312-win_amd64.whl (579.9 kB view details)

Uploaded Jun 25, 2025 CPython 3.12Windows x86-64

musica-0.12.0-cp312-cp312-win32.whl (525.8 kB view details)

Uploaded Jun 25, 2025 CPython 3.12Windows x86

musica-0.12.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.3 MB view details)

Uploaded Jun 25, 2025 CPython 3.12manylinux: glibc 2.17+ x86-64

musica-0.12.0-cp312-cp312-manylinux_2_17_i686.manylinux2014_i686.whl (1.2 MB view details)

Uploaded Jun 25, 2025 CPython 3.12manylinux: glibc 2.17+ i686

musica-0.12.0-cp312-cp312-macosx_11_0_arm64.whl (653.0 kB view details)

Uploaded Jun 25, 2025 CPython 3.12macOS 11.0+ ARM64

musica-0.12.0-cp311-cp311-win_amd64.whl (577.7 kB view details)

Uploaded Jun 25, 2025 CPython 3.11Windows x86-64

musica-0.12.0-cp311-cp311-win32.whl (528.0 kB view details)

Uploaded Jun 25, 2025 CPython 3.11Windows x86

musica-0.12.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.3 MB view details)

Uploaded Jun 25, 2025 CPython 3.11manylinux: glibc 2.17+ x86-64

musica-0.12.0-cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl (1.2 MB view details)

Uploaded Jun 25, 2025 CPython 3.11manylinux: glibc 2.17+ i686

musica-0.12.0-cp311-cp311-macosx_11_0_arm64.whl (650.8 kB view details)

Uploaded Jun 25, 2025 CPython 3.11macOS 11.0+ ARM64

musica-0.12.0-cp310-cp310-win_amd64.whl (577.0 kB view details)

Uploaded Jun 25, 2025 CPython 3.10Windows x86-64

musica-0.12.0-cp310-cp310-win32.whl (527.1 kB view details)

Uploaded Jun 25, 2025 CPython 3.10Windows x86

musica-0.12.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.3 MB view details)

Uploaded Jun 25, 2025 CPython 3.10manylinux: glibc 2.17+ x86-64

musica-0.12.0-cp310-cp310-manylinux_2_17_i686.manylinux2014_i686.whl (1.2 MB view details)

Uploaded Jun 25, 2025 CPython 3.10manylinux: glibc 2.17+ i686

musica-0.12.0-cp310-cp310-macosx_11_0_arm64.whl (649.2 kB view details)

Uploaded Jun 25, 2025 CPython 3.10macOS 11.0+ ARM64

musica-0.12.0-cp39-cp39-win_amd64.whl (610.1 kB view details)

Uploaded Jun 25, 2025 CPython 3.9Windows x86-64

musica-0.12.0-cp39-cp39-win32.whl (527.2 kB view details)

Uploaded Jun 25, 2025 CPython 3.9Windows x86

musica-0.12.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.3 MB view details)

Uploaded Jun 25, 2025 CPython 3.9manylinux: glibc 2.17+ x86-64

musica-0.12.0-cp39-cp39-manylinux_2_17_i686.manylinux2014_i686.whl (1.2 MB view details)

Uploaded Jun 25, 2025 CPython 3.9manylinux: glibc 2.17+ i686

musica-0.12.0-cp39-cp39-macosx_11_0_arm64.whl (649.3 kB view details)

Uploaded Jun 25, 2025 CPython 3.9macOS 11.0+ ARM64

File details

Details for the file musica-0.12.0.tar.gz.

File metadata

Download URL: musica-0.12.0.tar.gz
Upload date: Jun 25, 2025
Size: 1.3 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for musica-0.12.0.tar.gz
Algorithm	Hash digest
SHA256	`96bd07874f44eb05c2f3995058c52def4a6712e46e4d60bfb63e2372c798efee`
MD5	`0f7307c1066faae9b8c250bcc7861f68`
BLAKE2b-256	`1f4078f71eec526b5de4436c49a56d0ba7e4e341ac104c326fdee32dfc1c6912`

Algorithm	Hash digest
SHA256	`2d5589f710fffd415602415ae2a75433f1c0999d7917e42b0937a90ef244eeb6`
MD5	`22ab769a9e253fbefe8baae336bbdb8d`
BLAKE2b-256	`ff9d41e050c14257df63707861676e129d9513ae09afffbd75b67d0dd7e9686d`

Algorithm	Hash digest
SHA256	`2bfcc2e3a4ba2f76374eec932e664c907f662af1da67689d2df4f0dfd34eba19`
MD5	`b5ee26f21c0c1c498799cc7aae3f9c1a`
BLAKE2b-256	`6b0f147bd1793446f9b6bef1ca97e769d37785a8c0e506c5bcfa0cf6ea5a585d`

Algorithm	Hash digest
SHA256	`525be9c5d3a043fb2c810bf356e950368c1f00db71e8175b549c79ed5012ce8a`
MD5	`b65cacc69f06bfe4bf9c318ca118cd27`
BLAKE2b-256	`cfcef3a02921be98c37151d07fbfc3ead46a0a01cf25e2d949e109eb3e6adcf0`

Algorithm	Hash digest
SHA256	`210fc1f70face680a9eed0bb0937a8ec237f82cd9df96fbcad4bac6353c8da7a`
MD5	`142cc6a7c131fea4e9b3c19e830c6776`
BLAKE2b-256	`89515d39e1c0d6cca370f5fa8b6d0abe0a0758e5cbd7079fd73f4338b807497c`

Algorithm	Hash digest
SHA256	`bc32d72f33c081f517fe16f58b9aff9ddd41aab3890bcde85edac9f7e4f23e3b`
MD5	`c1b8081e235aa8efa79ec103f7f4c743`
BLAKE2b-256	`5df862deaa7ab0c4a3330f3844f8582d59e48458e2c13fac079ccf990bc786d9`

Algorithm	Hash digest
SHA256	`97329461f8183476eb7c40d1e83ba05ff2a801490937a7bee4bd41ae90e70c31`
MD5	`53edb66f47296c1adf800de2afec74b4`
BLAKE2b-256	`e8ec5edb35db07d89185e10857ee262d7133b0774707ce71ba579758650c01ee`

Algorithm	Hash digest
SHA256	`1ad7879fa520a4074bbd7bc1b4bf4045b8bd00a5604fdadbbed182eeb7cee4f7`
MD5	`eaeaa63956318629d31a222d9e99ce27`
BLAKE2b-256	`1f6aa52ff0f60a725f4306e9b880db5fbc34e69ba536ef130b8a7de280561f43`

Algorithm	Hash digest
SHA256	`17ec1a6a1b42cb9cee8fbc3386b399f57ca5e78e126785ca1efac3b35a31142c`
MD5	`43bac0b7a15fbec42e3d2e3b307a972e`
BLAKE2b-256	`106be12cce4d7b574a9eb42ce8280d618262e80884b0f45f726f3172e34cdbdb`

Algorithm	Hash digest
SHA256	`ca7fe6452494be94d693e6175d8897a46791c5fa17dc187b27c989e30cfa6fd6`
MD5	`ec072251d8df05a5afc7b14786c95229`
BLAKE2b-256	`769154a918cfbda2471aa991e44ec442e82305837236b707f9b901edb49620dc`

Algorithm	Hash digest
SHA256	`272746006b2adfaaea20eecc8f94afc46c218d8f8334ecd9325d6c448271bce7`
MD5	`c571104247c439d0595cc07f97c8a861`
BLAKE2b-256	`3bdeadedaa4d5120597e3a3850b778d6ac6b198e3b2b25bbf8a74b59546aa9ee`

Algorithm	Hash digest
SHA256	`3622afc70fa81bb4d501c3ecc466ee7c3f7a0be892840ba2e6ff33fc6f13689d`
MD5	`a1533f299d5518979d227edf829b540d`
BLAKE2b-256	`ff4d39fccd523881092df5b63c86e585621a19de6b2c79242388d4782ddac197`

Algorithm	Hash digest
SHA256	`62422a68318f7147b0ea84a77104e3179b24888209bec75d45263a37645c5faf`
MD5	`036eafa5e38963cba442c8d640f9441a`
BLAKE2b-256	`09966f109c24d7e26044c6a85480c73af266aaaafbe260fed3d6e1d9231b1fd6`

Algorithm	Hash digest
SHA256	`5a12c61f8c87781001b18d932fc501a94a86547e31904da8601be84a7e875f20`
MD5	`59bc3ea2dce485af3410b7eb2e113b81`
BLAKE2b-256	`3d02f5a5f392fe1a4f9f79a2564b22ff0252dea3886a3a66b21c5299d4aac2bd`

Algorithm	Hash digest
SHA256	`002eecfb495fb85300b7b788081291ceec1ae692c84939296a09b8985fb3297d`
MD5	`cfae7461ebea6759c9b5789a2582ef81`
BLAKE2b-256	`010f3cae5d706ca41787c8735ea73b72e704b39592358c02ad1ff4e0bce7a6d8`

Algorithm	Hash digest
SHA256	`24508c1db743824bdb8887ca2d2ae9b02665a4df6ba2d3ad8cb7cf25ee32b2cf`
MD5	`7488432fe7f332ddda9488550858cbb8`
BLAKE2b-256	`850d7b242b557704557b9c1a7f91f60abb40ba64ae76b2688eb6938132fcb33b`

Algorithm	Hash digest
SHA256	`59f197ec35a50b23bd9e4584567cfa86ab2b25bd605e5bc5445a374b52dee5b7`
MD5	`87c154796b1fefad6b865ea4cff17752`
BLAKE2b-256	`635064d9e1a8c0e7f5a9c89e3348f3b979eaae7de7b5052ec36f370cba405266`

Algorithm	Hash digest
SHA256	`0a2014b601fa2f3f5d35faad9a542195e5dcfa7ea80a66f406b841c5bceed610`
MD5	`e4ea4c07168fd01720a08bb8340bd311`
BLAKE2b-256	`50bcc018bfbefbb80eaaf63393d6911d4db772eec989e0f182193ad0f56db039`

Algorithm	Hash digest
SHA256	`032ab6a5015d21669f958b4d7d2aa3292ce2f9b68f7b34ba822f23bb44a1d4c3`
MD5	`410a20d67b9e420d0b88e6ac5018e994`
BLAKE2b-256	`fff4159dc4536041050b47c96af9e22011d1245b394b36c08037d51a4ec029f3`

Algorithm	Hash digest
SHA256	`19dbbf9296d3f62a61040e596b197cf3ce30a56b94a6b284902231a2c1572183`
MD5	`160d7bd2cc1ed83850333bc9cf8c4f9c`
BLAKE2b-256	`68075567e8980398bcc8883a9fb9669d64cfc865f3580e45ea3c04567295aed3`

Algorithm	Hash digest
SHA256	`6dca7157581b08bba8b4615cbcf5a65dd9805462b18cd2035c0205b490c6e4d6`
MD5	`320ec24746c8e41f5c585034f3ce89b0`
BLAKE2b-256	`d2c67528fab999636cdb1748debe030360e9facbedadb113b643c72859706fa4`

musica 0.12.0

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Project description

MUSICA

Installation

Pip

CMake

Using the MUSICA Python API

Available grids

Developer Options

Specifying dependency versions via parameterization at configure time

CMake Dependency Variables

Example Usage

Python build

PyPi

Local build

Contributing

Citations

Project details

Verified details

Maintainers

Unverified details

Project links

Meta

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes