Python interface & GHA workflow

.github/workflows/run_tests.yaml

@@ -0,0 +1,189 @@
+name: Run Tests
+
+on:
+  push:
+    branches: [ 'main', 'develop' ]
+    tags: ['*']
+  pull_request:
+
+  workflow_dispatch:
+
+jobs:
+
+  Monarch3Tests:
+
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, ubuntu-24.04-arm, ubuntu-22.04, ubuntu-22.04-arm, macos-26, macos-15-intel, macos-15]
+
+    steps:
+
+      - name: Checkout the repo
+        uses: actions/checkout@v7
+        with:
+          submodules: recursive
+
+      - name: Select CC version
+        # We require GCC 12 or higher if using GCC
+        # The default GCC for Ubuntu 22.04 is 11, but 12 is available
+        if: ${{ matrix.os == 'ubuntu-22.04' || matrix.os == 'ubuntu-22.04-arm' }}
+        run: |
+          echo "CC=gcc-12" >> $GITHUB_ENV
+          echo "CXX=g++-12" >> $GITHUB_ENV
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install Python packages
+        run: pip install pytest numpy
+
+      - name: Install dependencies -- Mac
+        # pybind11 is manually installed because we need to use v3.0.0 (as of 8/21/25)
+        # Fix the /usr/local directory structure
+        if: startsWith(matrix.os, 'macos')
+        run: |
+          brew install \
+            hdf5 \
+            boost \
+            pybind11 \
+            rapidjson \
+            yaml-cpp
+
+      - name: Install dependencies -- Linux
+        if: startsWith(matrix.os, 'ubuntu')
+        run: |
+          sudo apt-get update
+          DEBIAN_FRONTEND=noninteractive sudo apt-get install -y \
+            libhdf5-dev \
+            libboost-all-dev \
+            rapidjson-dev \
+            libyaml-cpp-dev
+          git clone https://github.com/pybind/pybind11.git
+          cd pybind11
+          git checkout v3.1.0
+          mkdir build
+          cd build
+          sudo cmake -DPYBIND11_TEST=FALSE ..
+          sudo make -j2 install
+
+      - name: Configure
+        run: |
+          mkdir build
+          cd build
+          cmake .. \
+            -DMonarch_BUILD_MONARCH3=TRUE \
+            -DMonarch_ENABLE_TESTING=TRUE \
+            -DMonarch_BUILD_PYTHON=TRUE
+
+      - name: Build
+        run: |
+          cd build
+          make -j2 install
+
+      - name: Run tests
+        run: |
+          cd build
+          ctest --output-on-failure
+
+# For debugging
+#      - name: Setup tmate session
+#        if: ${{ ! success() }}
+#        uses: mxschmitt/action-tmate@v3
+
+
+  Monarch2Tests:
+
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, ubuntu-24.04-arm, ubuntu-22.04, ubuntu-22.04-arm, macos-26, macos-15-intel, macos-15]
+
+    steps:
+
+      - name: Checkout the repo
+        uses: actions/checkout@v7
+        with:
+          submodules: recursive
+
+      - name: Select CC version
+        if: ${{ matrix.os == 'ubuntu-22.04' || matrix.os == 'ubuntu-22.04-arm' }}
+        run: |
+          echo "CC=gcc-12" >> $GITHUB_ENV
+          echo "CXX=g++-12" >> $GITHUB_ENV
+
+      - name: Install dependencies -- Mac
+        if: startsWith(matrix.os, 'macos')
+        run: |
+          brew install \
+            protobuf \
+            boost \
+            rapidjson \
+            yaml-cpp
+
+      - name: Install dependencies -- Linux
+        if: startsWith(matrix.os, 'ubuntu')
+        run: |
+          sudo apt-get update
+          DEBIAN_FRONTEND=noninteractive sudo apt-get install -y \
+            protobuf-compiler \
+            libprotobuf-dev \
+            libboost-all-dev \
+            rapidjson-dev \
+            libyaml-cpp-dev
+
+      - name: Configure
+        run: |
+          mkdir build
+          cd build
+          cmake .. \
+            -DMonarch_BUILD_MONARCH2=TRUE \
+            -DMonarch_BUILD_MONARCH3=FALSE \
+            -DMonarch_ENABLE_TESTING=TRUE \
+            -DScarab_BUILD_PYTHON=FALSE
+
+      - name: Build
+        run: |
+          cd build
+          make -j2 install
+
+# Tests have not been implemented
+#      - name: Run tests
+#        run: |
+#          cd build
+#          ctest --output-on-failure
+
+# For debugging
+#      - name: Setup tmate session
+#        if: ${{ ! success() }}
+#        uses: mxschmitt/action-tmate@v3
+
+
+  Release:
+
+    runs-on: ubuntu-24.04
+
+    if: ${{ github.event_name == 'push' && contains(github.ref, 'refs/tags/') }}
+
+    needs: [Monarch3Tests, Monarch2Tests]
+
+    steps:
+
+      - name: Checkout the repo
+        uses: actions/checkout@v7
+        with:
+          submodules: recursive
+
+      - name: Release with a changelog
+        uses: rasmus-saks/release-a-changelog-action@v1.2.0
+        with:
+          github-token: '${{ secrets.GITHUB_TOKEN }}'
+          path: 'changelog.md'
+          title-template: 'Monarch v{version} -- Release Notes'
+          tag-template: 'v{version}'

.readthedocs.yaml

@@ -0,0 +1,54 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-lts-latest
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+  apt_packages:
+    - cmake
+    - doxygen
+    - graphviz
+    - libboost-filesystem-dev
+    - libhdf5-dev
+    - pybind11-dev
+    - rapidjson-dev
+    - libyaml-cpp-dev
+    - tree
+  jobs:
+    pre_build:
+      - git submodule update --init --recursive
+      - cmake -S . -B _rtd_build -DMonarch_BUILD_PYTHON=ON -DPBUILDER_PY_INSTALL_IN_SITELIB=ON
+      - cmake --build _rtd_build --target install -- -j$(nproc)
+      - python ./Documentation/run_doxygen.py
+      - mkdir -p $READTHEDOCS_OUTPUT/html
+      - mv ./user_doxygen_out/html $READTHEDOCS_OUTPUT/html/_static
+      - tree
+
+# Build documentation in the "Documentation/" directory with Sphinx
+sphinx:
+   configuration: Documentation/conf.py
+
+submodules:
+  recursive: true
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+  - requirements: Documentation/requirements.txt