Merge pull request #344 from NCAR/main

Version 2.8.1

Author: K20shores

.github/workflows/docker_tests.yml

@@ -21,7 +21,6 @@ jobs:
         os: [ubuntu-latest]
         dockerfile:
           - Dockerfile
-        build_type: [Release, Debug]
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -32,7 +31,7 @@ jobs:
         run: rm -rf /opt/hostedtoolcache
 
       - name: Build Docker image
-        run: docker build -t music-box -f docker/${{ matrix.dockerfile }} . --build-arg MUSIC_BOX_GIT_TAG=${{ github.sha }} --build-arg BUILD_TYPE=${{ matrix.build_type }}
+        run: docker build -t music-box -f docker/${{ matrix.dockerfile }} . --build-arg MUSIC_BOX_GIT_TAG=${{ github.sha }} 
 
       - name: Run tests in container
         run: docker run --name test-container -t music-box

.github/workflows/gh_pages.yml

@@ -3,8 +3,6 @@ name: GitHub Pages
 
 on: 
   push:
-    branches:
-      - main
   pull_request:
   workflow_dispatch:
 
@@ -86,18 +84,25 @@ jobs:
       # _gh-pages/branch/$brname (transforming '/' into '--')
       - name: Build and copy documentation (branch)
         if: |
-          contains(github.event_name, 'push') &&
+          (contains(github.event_name, 'push') ||
+          contains(github.event_name, 'pull_request')) &&
           !contains(github.ref, env.DEFAULT_BRANCH)
         run: |
           set -x
           docker build -t music_box -f docker/Dockerfile.docs .
           id=$(docker create music_box)
           docker cp $id:/music-box/docs/build/html tmpdocs
           docker rm -v $id
-          brname="${{github.ref}}"
-          brname="${brname##refs/heads/}"
+          # Determine branch name for deployment directory
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            brname="${{ github.head_ref }}"
+          else
+            brname="${{ github.ref }}"
+            brname="${brname##refs/heads/}"
+          fi
           brdir=${brname//\//--}   # replace '/' with '--'
           rm -rf   _gh-pages/branch/${brdir}
+          mkdir -p _gh-pages/branch/${brdir}
           rsync -a tmpdocs/ _gh-pages/branch/${brdir}
 
       # Go through each branch in _gh-pages/branch/, if it's not a
@@ -129,4 +134,23 @@ jobs:
           publish_branch: gh-pages
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: _gh-pages/
-          force_orphan: true
+          force_orphan: true
+
+  comment-doc-link:
+    name: Comment documentation link on PR
+    if: ${{ github.event_name == 'pull_request' && github.event.action == 'opened' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Post documentation link
+        uses: actions/github-script@v6
+        with:
+          script: |
+            const branchName = context.payload.pull_request.head.ref;
+            const docLink = `https://ncar.github.io/music-box/branch/${branchName}/`;
+            const commentBody = `📄 Documentation for this branch is available at: [${docLink}](${docLink})`;
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.payload.pull_request.number,
+              body: commentBody
+            });

README.md

@@ -16,6 +16,76 @@ Copyright (C) 2020 National Science Foundation - National Center for Atmospheric
 # Installation
 ```
 pip install acom-music-box
+```
+# Using the MusicBox API
+
+MusicBox 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](https://ncar.github.io/music-box/branch/main/index.html) for further tutorials and examples.
+```
+# Import MusicBox, MusicBox conditions, and Musica mechanisms:
+
+from acom_music_box import MusicBox, Conditions
+import musica.mechanism_configuration as mc                                      
+
+
+# Define the chemical system of interest
+
+# MusicBox uses Musica (https://ncar.github.io/musica/index.html) to create specific chemical species and phases of interest for chemical mechanisms.
+
+A = mc.Species(name="A")
+B = mc.Species(name="B")
+C = mc.Species(name="C")  
+
+species = {"A":A, "B":B, "C":C}
+
+gas = mc.Phase(name="gas", species=list(species.values()))
+
+# 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.
+
+arr1 = mc.Arrhenius(name="A->B", A=4.0e-3, C=50,reactants=[species["A"]], products=[species["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=[species["B"]], products=[species["C"]], gas_phase=gas)
+
+mechanism = mc.Mechanism(name="test_mechanism", species=list(species.values()),phases=[gas], reactions=[arr1, arr2])
+
+
+# Create a box model
+
+# To create a box model, including its mechanisms, conditions, length, time, and step times:
+
+box_model = MusicBox()
+box_model.load_mechanism(mechanism)
+
+
+# In the box model, the initial set of conditions represent the starting environment for the reactions.
+# Both initial and evolving conditions are typically created alongside the creation of the box model:
+
+box_model.initial_conditions = Conditions(temperature=300.0, pressure=101000.0, species_concentrations={ "A": 1.0, "B": 3.0, "C": 5.0})
+
+
+# Evolving conditions represent a set of environmental and species values or rate constants that the box model should use at a specific time step.
+# The following adds an evolving condition to the model, the first float represents the time when the condition evolves:
+
+box_model.add_evolving_condition(300.0,Conditions(temperature=290.0, pressure=100200.0, species_concentrations={"A": 1.0, "B": 3.0, "C": 10.0}))
+
+box_model.box_model_options.simulation_length = 20 # total simulation time
+box_model.box_model_options.chem_step_time = 1 # time step for chemical reaction
+box_model.box_model_options.output_step_time = 4 # time step between each output
+
+
+# Solve your newly-created box model and view results:
+
+df = box_model.solve()
+print(df)
+
+# To 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()
+
 ```
 
 # Command line tool

docker/Dockerfile

@@ -1,7 +1,7 @@
 FROM fedora:latest
 
 ARG MUSIC_BOX_TAG=main
-ARG MUSICA_TAG=v0.11.1
+ARG MUSICA_TAG=v0.11.1.4
 
 RUN dnf -y update \
     && dnf -y install \

docker/Dockerfile.docs

@@ -6,6 +6,7 @@ RUN dnf -y update \
         gcc \
         gcc-c++ \
         make \
+        pandoc \
         python3-devel \
         python3-pip \
     && dnf clean all
@@ -14,6 +15,7 @@ COPY . /music-box/
 
 WORKDIR /music-box
 
+
 RUN pip3 install -e .
 
 ARG SUFFIX=""
@@ -23,4 +25,4 @@ RUN echo "The suffix is '$SWITCHER_SUFFIX'"
 
 RUN cd docs \
     && pip install -r requirements.txt \
-    && make html
+    && make html

docs/requirements.txt

@@ -2,4 +2,5 @@ sphinx
 sphinx-book-theme
 sphinx-copybutton
 sphinx-design
-sphinxcontrib-bibtex
+sphinxcontrib-bibtex
+pydata-sphinx-theme

docs/source/_static/custom.css

@@ -5,3 +5,16 @@
   margin-right: auto;
   margin-top: 10px;
 }
+
+/* Hide input prompts (e.g., In [1]:) */
+div.nbinput .prompt,
+div.nboutput .prompt {
+    display: none;
+}
+
+/* Ensure full-width appearance for all code cells */
+div.nbinput pre,
+div.nboutput pre {
+    white-space: pre-wrap;
+    word-break: break-word;
+}

docs/source/_static/switcher.json

@@ -1,7 +1,22 @@
 [
-    {
-      "name": "dev",
-      "version": "dev",
-      "url": "https://ncar.github.io/music-box/branch/main/"
-    }
+  {
+    "name": "v2.8.0 (stable)",
+    "version": "2.8.0",
+    "url": "https://ncar.github.io/music-box"
+  },
+  {
+    "name": "v2.7.0 (stable)",
+    "version": "v2.7.0 (stable)",
+    "url": "https://ncar.github.io/music-box/versions/2.7.0"
+  },
+  {
+    "name": "v2.6.0",
+    "version": "v2.6.0",
+    "url": "https://ncar.github.io/music-box/versions/2.6.0"
+  },
+  {
+    "name": "dev",
+    "version": "dev",
+    "url": "https://ncar.github.io/music-box/branch/main/"
+  }
 ]

docs/source/api/acom_music_box.rst

@@ -1,8 +1,10 @@
 MusicBox
 ========
 
-Submodules
-----------
+.. automodule:: acom_music_box
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
 acom\_music\_box.music\_box module
 ----------------------------------
@@ -12,90 +14,42 @@ acom\_music\_box.music\_box module
    :undoc-members:
    :show-inheritance:
 
-acom\_music\_box.music\_box\_conditions module
+acom\_music\_box.conditions module
 ----------------------------------------------
 
-.. automodule:: acom_music_box.music_box_conditions
+.. automodule:: acom_music_box.conditions
    :members:
    :undoc-members:
    :show-inheritance:
 
-acom\_music\_box.music\_box\_evolving\_conditions module
+acom\_music\_box.evolving\_conditions module
 --------------------------------------------------------
 
-.. automodule:: acom_music_box.music_box_evolving_conditions
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-acom\_music\_box.music\_box\_model\_options module
---------------------------------------------------
-
-.. automodule:: acom_music_box.music_box_model_options
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-acom\_music\_box.music\_box\_product module
--------------------------------------------
-
-.. automodule:: acom_music_box.music_box_product
+.. automodule:: acom_music_box.evolving_conditions
    :members:
    :undoc-members:
    :show-inheritance:
 
-acom\_music\_box.music\_box\_reactant module
---------------------------------------------
-
-.. automodule:: acom_music_box.music_box_reactant
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-acom\_music\_box.music\_box\_reaction module
---------------------------------------------
+acom\_music\_box.data\_output module
+----------------------------------------------
 
-.. automodule:: acom_music_box.music_box_reaction
+.. automodule:: acom_music_box.data_output
    :members:
    :undoc-members:
    :show-inheritance:
 
-acom\_music\_box.music\_box\_reaction\_list module
---------------------------------------------------
+acom\_music\_box.plot_output module
+----------------------------------------------
 
-.. automodule:: acom_music_box.music_box_reaction_list
+.. automodule:: acom_music_box.plot_output
    :members:
    :undoc-members:
    :show-inheritance:
 
-acom\_music\_box.music\_box\_reaction\_rate module
+acom\_music\_box.model\_options module
 --------------------------------------------------
 
-.. automodule:: acom_music_box.music_box_reaction_rate
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-acom\_music\_box.music\_box\_species module
--------------------------------------------
-
-.. automodule:: acom_music_box.music_box_species
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-acom\_music\_box.music\_box\_species\_concentration module
-----------------------------------------------------------
-
-.. automodule:: acom_music_box.music_box_species_concentration
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-acom\_music\_box.music\_box\_species\_list module
--------------------------------------------------
-
-.. automodule:: acom_music_box.music_box_species_list
+.. automodule:: acom_music_box.model_options
    :members:
    :undoc-members:
    :show-inheritance:
@@ -108,10 +62,3 @@ acom\_music\_box.utils module
    :undoc-members:
    :show-inheritance:
 
-Module contents
----------------
-
-.. automodule:: acom_music_box
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/source/api/index.rst

@@ -1,8 +1,11 @@
-###
-API
-###
+###############
+API Reference
+###############
+
+This documentation describes the Python API for MusicBox.
+For detailed information on the chemistry-related objects and reaction definitions used in MusicBox via MUSICA, see the :mod:`musica.mechanism_configuration`
 
 .. toctree::
    :maxdepth: 4
 
-   acom_music_box
+   acom_music_box