add user guide (#353)

angelapak · K20shores · web-flow · commit 55f452bf482b · 2025-06-24T13:54:25.000-06:00
* contributors updated

* set up user guide header page

* replace subpages with subheaders

* minor section reformatting

* complete box model page

* update output and visualization

* update running examples page

* link tutorial notebooks

* add reaction formulae and examples

* update installation guide

* add reaction rate parameters in drop down and example usages

* fix minor formatting inconsistencies

* minor grammatical/formatting fixes

* add links to premade examples

* fix pyproject error

* Update docs/source/user_guide/output/index.rst

Co-authored-by: Kyle Shores &lt;kyle.shores44@gmail.com&gt;

* Update docs/source/user_guide/box_model/index.rst

Co-authored-by: Kyle Shores &lt;kyle.shores44@gmail.com&gt;

* set up intersphinx links to micm and mechanism configuration

* clean redunant reaction info

* Update docs/source/user_guide/installation/index.rst

Co-authored-by: Kyle Shores &lt;kyle.shores44@gmail.com&gt;

* acom_music_box underscore consistency

* set up intersphinx links to micm and musica and sphinx references to musicbox objects

* Update docs/source/user_guide/species/index.rst

Co-authored-by: Kyle Shores &lt;kyle.shores44@gmail.com&gt;

* minor rewording/reorg in Defining chemical systems section

* add species concentration units

---------

Co-authored-by: Kyle Shores &lt;kyle.shores44@gmail.com&gt;
diff --git a/CITATION.cff b/CITATION.cff
@@ -23,5 +23,9 @@ authors:
     given-names: Montek
   - family-names: Kiran
     given-names: Aditya
+  - family-names: Winney
+    given-names: Aidan
+  - family-names: Pak
+    given-names: Angela
 license: Apache-2.0
 url: "https://github.com/NCAR/music-box"
diff --git a/README.md b/README.md
@@ -15,7 +15,7 @@ Copyright (C) 2020 National Science Foundation - National Center for Atmospheric
 
 # Installation
 ```
-pip install acom-music-box
+pip install acom_music_box
 ```
 # Using the MusicBox API
 
diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
@@ -1,3 +1,5 @@
+.. _api-ref:
+
 ###############
 API Reference
 ###############
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -42,6 +42,8 @@
 
 intersphinx_mapping = {
     'musica': ('https://ncar.github.io/musica/api/', None),
+    'micm': ('https://ncar.github.io/micm/', None),
+    'mc': ('https://ncar.github.io/MechanismConfiguration/', None)
 }
 
 # -- Options for HTML output -------------------------------------------------
diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
@@ -2,9 +2,7 @@
 Getting started
 ###############
 
-MusicBox User Tutorial
-----------------------
-Hello, and welcome to the MusicBox user tutorial! Here, we will be covering some basic usages of the MusicBox library.
+Hello, and welcome to MusicBox! Here, we will be covering some basic usages of the MusicBox library.
 
 What is MusicBox?
 ------------------
diff --git a/docs/source/user_guide/box_model/conditions.rst b/docs/source/user_guide/box_model/conditions.rst
diff --git a/docs/source/user_guide/box_model/configurations.rst b/docs/source/user_guide/box_model/configurations.rst
diff --git a/docs/source/user_guide/box_model/index.rst b/docs/source/user_guide/box_model/index.rst
@@ -1,13 +1,94 @@
 Box model
 =========
+.. note::
+    
+    MusicBox uses the Model-Independent Chemical Module (MICM) as its core chemistry solver. For more information about available reaction types,
+    species configuration, and solver behavior, see the `MICM documentation <micm:index>`_.
 
-This section details the components of the box model, including reactions, mechanisms, conditions, and solutions.
+This section details the components of the box model, a mechanism (the set of reactions and species), conditions, and solutions. To use the MusicBox model,
+import the :class:`acom_music_box.music_box.MusicBox` class::
+    
+    from acom_music_box import MusicBox, Conditions
 
-.. toctree::
-   :maxdepth: 1
+Using the previously defined in-code mechanism (see :ref:`Defining chemical systems <species>`), a box model can now be created and initialized with it::
+    
+    box_model = MusicBox()
+    box_model.load_mechanism(mechanism)
 
-   reactions
-   Chemical mechanisms <mechanisms>
-   Initial and evolving conditions <conditions>
-   Configuration options <configurations>
+Initial and evolving conditions
+--------------------------------
+Use :class:`acom_music_box.conditions.Conditions` to set environmental parameters and species concentrations (:math:`\textsf{mol m}^{-3}`). Initial conditions define the environment that 
+the mechanism takes place in at the start of the simulation through the parameters temperature (K), pressure (Pa), and optionally 
+air density. Without an air density provided, the Ideal Gas Law is used to calculate this parameter. The initial concentrations of each
+Species is also included::
+    
+    box_model.initial_conditions = Conditions( temperature=298.15, pressure=101325.0, species_concentrations={"X": 3.75, "Y": 5.0, "Z": 2.5,})
 
+Evolving conditions (see :class:`acom_music_box.evolving_conditions.EvolvingConditions`) change the environment of the mechanism at a defined time value (Seconds), its first argument. Like importnitial conditions,
+these changes can also include temperature, pressure, air density, and Species concentrations::
+    
+    box_model.add_evolving_condition(100.0, Conditions(temperature=310.0, pressure=100100.0))
+
+Additional model options
+-------------------------
+Each box model also contains three time parameters that must be defined:
+
+* simulation_length: the number of seconds that the simulation lasts for
+* chem_step_time: the number of time steps between each simulation calculation
+* output_step_time: the number of seconds between each output of the model
+
+See :mod:`acom_music_box.model_options` for further details. The time parameters can be used as follows::
+    
+    box_model.box_model_options.simulation_length = 200 # Units: Seconds (s)
+    box_model.box_model_options.chem_step_time = 1 # Units: Seconds (s)
+    box_model.box_model_options.output_step_time = 20 # Units: Seconds (s)
+
+For further descriptions of these MusicBox attributes, please see the `API Reference <https://ncar.github.io/music-box/branch/main/api/index.html>`_.
+
+Solving
+--------
+Once all components of the box model have been defined, it can be solved by calling::
+
+    df = box_model.solve()
+
+This returns the following dataframe of the conditions and Species concentrations as they've varied across time steps.
+
++----+----------+---------------------+-------------------+----------------------------------+------------------+------------------+------------------+
+|    |   time.s |   ENV.temperature.K |   ENV.pressure.Pa |   ENV.air number density.mol m-3 |   CONC.X.mol m-3 |   CONC.Y.mol m-3 |   CONC.Z.mol m-3 |
++====+==========+=====================+===================+==================================+==================+==================+==================+
+|  0 |        0 |              298.15 |            101325 |                          40.874  |          3.75    |          5       |          2.5     |
++----+----------+---------------------+-------------------+----------------------------------+------------------+------------------+------------------+
+|  1 |       20 |              298.15 |            101325 |                          40.874  |          3.41149 |          4.8714  |          2.96711 |
++----+----------+---------------------+-------------------+----------------------------------+------------------+------------------+------------------+
+|  2 |       40 |              298.15 |            101325 |                          40.874  |          3.10354 |          4.72528 |          3.42118 |
++----+----------+---------------------+-------------------+----------------------------------+------------------+------------------+------------------+
+|  3 |       60 |              298.15 |            101325 |                          40.874  |          2.82338 |          4.56584 |          3.86077 |
++----+----------+---------------------+-------------------+----------------------------------+------------------+------------------+------------------+
+|  4 |       80 |              298.15 |            101325 |                          40.874  |          2.56852 |          4.39669 |          4.28479 |
++----+----------+---------------------+-------------------+----------------------------------+------------------+------------------+------------------+
+|  5 |      100 |              298.15 |            101325 |                          40.874  |          2.33666 |          4.22086 |          4.69247 |
++----+----------+---------------------+-------------------+----------------------------------+------------------+------------------+------------------+
+|  6 |      120 |              310    |            100100 |                          38.8363 |          2.12702 |          4.04212 |          5.08087 |
++----+----------+---------------------+-------------------+----------------------------------+------------------+------------------+------------------+
+|  7 |      140 |              310    |            100100 |                          38.8363 |          1.93618 |          3.86147 |          5.45235 |
++----+----------+---------------------+-------------------+----------------------------------+------------------+------------------+------------------+
+|  8 |      160 |              310    |            100100 |                          38.8363 |          1.76247 |          3.6807  |          5.80683 |
++----+----------+---------------------+-------------------+----------------------------------+------------------+------------------+------------------+
+|  9 |      180 |              310    |            100100 |                          38.8363 |          1.60434 |          3.50128 |          6.14438 |
++----+----------+---------------------+-------------------+----------------------------------+------------------+------------------+------------------+
+| 10 |      200 |              310    |            100100 |                          38.8363 |          1.4604  |          3.32443 |          6.46517 |
++----+----------+---------------------+-------------------+----------------------------------+------------------+------------------+------------------+
+
+
+Loading premade configurations (optional)
+------------------------------------------
+As an alternative to using the steps thus far to define a chemical configuration in code, MusicBox
+also supports definitions via a configuration file in JSON format. This example assumes you are using a file called
+"custom_box_model.json" in a "config" subfolder::
+
+    import sys
+
+    box_model = MusicBox()
+    conditions_path = "config/custom_box_model.json"
+    box_model.loadJson(conditions_path)
+    df = box_model.solve()
diff --git a/docs/source/user_guide/box_model/mechanisms.rst b/docs/source/user_guide/box_model/mechanisms.rst
diff --git a/docs/source/user_guide/box_model/reactions.rst b/docs/source/user_guide/box_model/reactions.rst
diff --git a/docs/source/user_guide/examples/index.rst b/docs/source/user_guide/examples/index.rst
@@ -1,2 +1,37 @@
+Examples and tutorials
+===============================
+
 Running premade examples
-========================
+-------------------------
+MusicBox provides a selection of pre-made example configurations for the user to work with:
+
+* `Analytical <https://github.com/NCAR/music-box/tree/main/src/acom_music_box/examples/configs/analytical>`_
+* `CarbonBond5 <https://github.com/NCAR/music-box/tree/main/src/acom_music_box/examples/configs/carbon_bond_5>`_
+* `Chapman <https://github.com/NCAR/music-box/tree/main/src/acom_music_box/examples/configs/chapman>`_
+* `FlowTube <https://github.com/NCAR/music-box/tree/main/src/acom_music_box/examples/configs/flow_tube>`_
+* `TS1 <https://github.com/NCAR/music-box/tree/main/src/acom_music_box/examples/configs/ts1>`_
+* `WACCM <https://github.com/NCAR/music-box/tree/main/src/acom_music_box/examples/configs/waccm>`_
+
+Each example (found in `src/acom_music_box/examples/configs`) includes an associated set of JSON files acccessible through the Examples class::
+
+    from acom_music_box import MusicBox, Examples
+    import matplotlib.pyplot as plt
+
+    box_model = MusicBox()
+    conditions_path = Examples.Analytical.path
+    box_model.loadJson(conditions_path)
+    df = box_model.solve()
+    display(df)
+    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()
+
+Interactive tutorial notebooks
+-------------------------------
+Looking for hands on examples of the concepts covered in this guide? Explore our `tutorial notebooks <https://github.com/NCAR/music-box/tree/main/tutorial>`_ for detailed, interactive walkthroughs.
+The tutorials thus far cover:
+
+1. `a basic MusicBox workflow <https://github.com/NCAR/music-box/blob/main/tutorial/1.%20basic_workflow.ipynb>`_
+2. `overriding mechanisms <https://github.com/NCAR/music-box/blob/main/tutorial/2.%20override_mechanism.ipynb>`_
+3. `loading custom box models <https://github.com/NCAR/music-box/blob/main/tutorial/3.%20loading_custom_box_models.ipynb>`_
+
+and will continue to be updated!
diff --git a/docs/source/user_guide/index.rst b/docs/source/user_guide/index.rst
@@ -2,6 +2,13 @@
 User Guide
 ##########
 
+This guide serves as an overview of key features in the MusicBox library. Further details can be found in :ref:`API Reference <api-ref>`.
+Interactive Jupyter notebooks can also be found on our `Github <https://github.com/NCAR/music-box/tree/main/tutorial>`_.
+
+.. note::
+   Most chemistry classes (e.g., `Species`, `Phase`, `Mechanism`) are provided by the underlying `MUSICA <https://github.com/NCAR/musica>`_ framework. Refer to the `MUSICA documentation <https://ncar.github.io/musica/index.html#>`_
+   for full details on these classes and their parameters.
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents
diff --git a/docs/source/user_guide/installation/index.rst b/docs/source/user_guide/installation/index.rst
@@ -1,2 +1,51 @@
 Installing MusicBox
 ===================
+MusicBox is made pip installable. As with any other Python package, we recommend the use of MusicBox within a virtual environment
+to contain dependencies. This page provides instructions on setting up this environment with `conda <https://www.anaconda.com/docs/getting-started/miniconda/main>`_.
+
+Creating a Virtual environment (conda)
+---------------------------------------
+After `installing conda <https://docs.conda.io/projects/conda/en/stable/user-guide/install/index.html>`_, create a new conda environment
+with a minimum Python version of 3.9, and activate your new environment:
+
+.. code-block:: console
+
+    $ conda create --name musicbox python=<minimum-3.9> --yes
+    $ conda activate musicbox
+
+Pip
+~~~~
+Within your new conda environment, install MusicBox via pip:
+
+.. code-block:: console
+    
+    $ pip install acom_music_box
+
+Note that this step can also be performed without a virtual environment if a local installation is acceptable.
+
+Verifying installation
+~~~~~~~~~~~~~~~~~~~~~~
+To verify that MusicBox was installed, run the following command within your conda environment:
+
+.. code-block:: console
+    
+    $ conda list
+
+This should print a list of all available packages within your conda environment, one of which should be `acom_music_box` with
+the version listing matching the latest release as listed on our `Github <https://github.com/NCAR/music-box>`_.
+
+If you've chosen to install MusicBox locally, the following command will function in the same manner:
+
+.. code-block:: console
+    
+    $ pip list
+
+With MusicBox successfully installed, you should be able to import the package from a Python shell or script and print the version. Note that the
+full package name is `acom_music_box`::
+
+    import acom_music_box; print(acom_music_box.__version__)
+
+Developer installation
+----------------------
+For users that want to modify or contribute to MusicBox, please follow the editable installation instructions
+on the `Contributing <https://ncar.github.io/music-box/branch/main/contributing/index.html>`_ page.
diff --git a/docs/source/user_guide/output/index.rst b/docs/source/user_guide/output/index.rst
@@ -1,2 +1,13 @@
 Output and visualization
 ========================
+MusicBox simulation results can easily be visualized with `Matplotlib <https://matplotlib.org>`_. Matplotlib
+is a dependency of MusixBox and will be installed when MusicBox is installed. To utilize it, first::
+
+    import matplotlib.pyplot as plt
+
+Then, specific results of your box model simulation can be visualized::
+
+    df.plot(x='time.s', y=['CONC.X.mol m-3', 'CONC.Y.mol m-3', 'CONC.Z.mol m-3'], title='Concentration over time', ylabel='Concentration (mol m-3)', xlabel='Time (s)')
+    plt.show()  
+
+
diff --git a/docs/source/user_guide/species/definitions.rst b/docs/source/user_guide/species/definitions.rst
diff --git a/docs/source/user_guide/species/index.rst b/docs/source/user_guide/species/index.rst
@@ -1,10 +1,60 @@
-Chemical species
-================
+.. _species:
 
-This section covers the definitions and phases of chemical species used in MusicBox.
+Defining chemical systems
+=========================
 
-.. toctree::
-   :maxdepth: 1
+This section covers the components of a chemical system as defined in MusicBox:
 
-   definitions
-   phases
+- Species (see :class:`musica.mechanism_configuration.Species`)
+- Phases (see :class:`musica.mechanism_configuration.Phase`)
+- Reactions (see :class:`musica.mechanism_configuration.Reactions`)
+- Mechanisms (see :class:`musica.mechanism_configuration.Mechanism`)
+
+
+As a reminder, this section assumes you have imported::
+   
+   import musica.mechanism_configuration as mc
+
+Species
+--------
+Chemical species are the fundamental units that participate in reactions, they can be defined using::
+   
+   X = mc.Species(name="X")
+   Y = mc.Species(name="Y")
+   Z = mc.Species(name="Z")
+
+   species = {"X":X,"Y":Y,"Z":Z}
+
+Species can be initialized with various chemistry-related paramaters (e.g., molecular weight, density, etc.). See the :class:`musica.mechanism_configuration.Species`
+documentation for further details.
+
+Phases
+-------
+Species can be grouped into a phase. At present MUSICA and therefore MusicBox can only support a single gas phase,
+but support for more phases is coming in the future::
+   
+   gas = mc.Phase(name="gas",species=list(species.values()))
+
+Reactions
+----------
+Reactions are defined using rate-based classes such as :class:`musica.mechanism_configuration.Arrhenius`.
+Each class takes a unique set of rate parameters and the participating species::
+
+   arr1 = mc.Arrhenius(name="X->Y", A=4.0e-3, C=50, reactants=[species["X"]], products=[species["Y"]], gas_phase=gas)
+   arr2 = mc.Arrhenius(name="Y->Z", A=4.0e-3, C=50, reactants=[species["Y"]], products=[species["Z"]], gas_phase=gas)
+   
+For passing later on into a Mechanism (see :class:`musica.mechanism_configuration.Mechanism`), it is helpful to store your selected reactions into a dictionary::
+
+   rxns = {r.name: r for r in [arr1, arr2]}
+
+.. note::
+
+   Several other reaction types are made available for use in MusicBox. For a full list of supported reactions types as well as their parameters,
+   please see the :ref:`mc:reactions` page in the OpenAtmos Mechanism Configuration documentation.
+
+Mechanisms
+----------
+A mechanism defines a collection of chemical species, their associated phases, and the reactions between them. Mechanisms can be defined as
+follows::
+
+   mechanism = mc.Mechanism(name="tutorial_mechanism", species=list(species.values()), phases=[gas], reactions=list(rxns.values()))
diff --git a/docs/source/user_guide/species/phases.rst b/docs/source/user_guide/species/phases.rst
diff --git a/pyproject.toml b/pyproject.toml
@@ -12,7 +12,11 @@ authors = [
   { name = "Walker Drury"},
   { name = "Alexander Garza"},
   { name = "Brendan Fattig"},
-  { name = "Carl Drews", email = "drews@ucar.edu" }
+  { name = "Carl Drews", email = "drews@ucar.edu" },
+  { name = "Montek Thind"},
+  { name = "Aditya Kiran"},
+  { name = "Aidan Winney"},
+  { name = "Angela Pak"}
 ]
 maintainers = [{ name = "ACOM MUSICA Developers", email = "musica-support@ucar.edu" }]
 readme = "README.md"

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+.. _api-ref:`
	`2`	`+`
`1`	`3`	`###############`
`2`	`4`	`API Reference`
`3`	`5`	`###############`
Original file line number	Diff line number	Diff line change
`@@ -42,6 +42,8 @@`
`42`	`42`
`43`	`43`	`intersphinx_mapping = {`
`44`	`44`	`'musica': ('https://ncar.github.io/musica/api/', None),`
	`45`	`+ 'micm': ('https://ncar.github.io/micm/', None),`
	`46`	`+ 'mc': ('https://ncar.github.io/MechanismConfiguration/', None)`
`45`	`47`	`}`
`46`	`48`
`47`	`49`	`# -- Options for HTML output -------------------------------------------------`