Merge branch 'main' into release

Author: boulderdaze

.dockerignore

@@ -0,0 +1,3 @@
+# Exclude broken colon symlink (absolute path, unusable inside Docker)
+# The test recreates it with a relative path at runtime
+sample_waccm_data/20250820/wrf/wrfout_hourly_d01_2025-08-20_08:00:00

.github/ISSUE_TEMPLATE/release.md

@@ -0,0 +1,42 @@
+---
+name: Version Release
+about: Create an issue to make a new release
+title: 'Release X.X.X'
+labels: ''
+assignees: ''
+
+---
+
+## Dependency version update
+
+- [ ] Update musica python package version in `pyproject.toml`
+
+## Testing steps
+
+- [ ] GitHub Actions are passing on `main`
+- [ ] Launch Binder and run all tutorial examples
+
+## Deployment and release steps
+
+- [ ] on a new branch (call it anything but `release`)
+  - [ ] Update the music box version in `python/acom_music_box/__init__.py` 
+  - [ ] Update the music box version in `package.json`
+- [ ] Update the `CITATION.cff` file
+  - [ ] Update version number
+  - [ ] Ensure all contributors are listed as authors
+- [ ] On GitHub, merge `main` into `release` — **do NOT squash and merge**
+  - Alternatively, merge locally and push: `git checkout release && git merge main && git push`
+- [ ] Make a tag and add release notes on GitHub
+  - Be sure to choose the `release` branch for the target
+## Python (automatic)
+PyPI publishing happens automatically via the release action when a tag and release are created.
+
+- [ ] Verify the PyPI release was published successfully
+
+---
+
+## JavaScript (automatic)
+
+npm publishing happens automatically via the release action when a tag and release are created.
+
+- [ ] Verify the npm release was published successfully

.github/workflows/CI_Tests.yml

@@ -38,15 +38,15 @@ jobs:
     - uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
-        cache: 'pip' 
+        cache: 'pip'
 
     - name: Install this package
       run: pip install -e '.[dev]'
       env: 
         FC: gfortran-14
 
     - name: Run tests and generate coverage reports
-      run: pytest --cov src/
+      run: pytest --cov python/
 
     - name: Upload coverage reports to codecov
       if: runner.os == 'Linux'
@@ -57,7 +57,7 @@ jobs:
 
     - name: Run the smoke tests
       run: |
-        music_box -c src/acom_music_box/examples/configs/analytical/my_config.json -o output.csv
+        music_box -c examples/analytical/my_config.json -o output.csv
         music_box -e Analytical -o output.csv
         music_box -e Analytical -o output.csv -vv --color-output
         waccmToMusicBox --waccmDir "./sample_waccm_data" --date "20240904" --time "07:00" --latitude 3.1 --longitude 101.7

.github/workflows/javascript.yml

@@ -0,0 +1,73 @@
+name: Javascript Tests
+
+on:
+  push:
+    branches:
+      - main
+
+  pull_request:
+  workflow_dispatch:
+  release:
+    types:
+      - published
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        platform: [ubuntu-latest, windows-latest, macos-latest]
+        node-version: ["v22", "v24"]
+
+    runs-on: ${{ matrix.platform }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup node
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Test
+        run: npm test
+
+  publish:
+    runs-on: ubuntu-latest
+    if: (github.event_name == 'release' && github.event.action == 'published') || github.event_name == 'workflow_dispatch'
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Test
+        run: npm run test
+      
+      - name: Copy javascript readme
+        run: cp javascript/README.md README.md # npm uses the root README for the package page
+      
+      - name: List config
+        run: |
+          npm --version
+          node --version
+          npm config list -l
+
+      - name: Publish to npm
+        run: NODE_AUTH_TOKEN="" npm publish --access public --provenance

.github/workflows/parity_tests.yml

@@ -0,0 +1,40 @@
+name: JS/Python Parity Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  parity:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libnetcdf-dev netcdf-bin libnetcdff-dev liblapack-dev
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "v22"
+
+      - name: Install Python package
+        run: pip install -e '.[dev]'
+
+      - name: Install JS dependencies
+        run: npm ci
+
+      - name: Run parity tests
+        run: python tests/parity_test.py

.gitignore

@@ -12,3 +12,7 @@ dist
 .vscode/
 .coverage
 src/acom_music_box/examples/configs/ts1/initial_config.json*.csv
+sample_waccm_data/**/wrfout_hourly_d01_*:*
+.claude
+
+node_modules

.readthedocs.yaml

@@ -9,16 +9,20 @@ build:
   os: ubuntu-24.04
   tools:
     python: "3.13"
+    nodejs: "22"
+  jobs:
+    pre_build:
+      - npm install
+      - cp -r tutorials/* docs/source/tutorials/
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:
   configuration: docs/source/conf.py
 
-# Optionally, but recommended,
-# declare the Python requirements required to build your documentation
-# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# Install the package with doc extras (includes sphinx-js and all doc dependencies)
 python:
   install:
     - method: pip
       path: .
-    - requirements: docs/requirements.txt
+      extra_requirements:
+        - doc

CITATION.cff

@@ -1,7 +1,7 @@
 cff-version: 1.2.0
 message: If you use this software, please cite it as below.
 title: MusicBox
-version: v2.11.0
+version: v3.0.0
 authors:
   - family-names: Dawson
     given-names: Matthew