Initial commit

.dockerignore

@@ -0,0 +1,3 @@
+.git/
+.cache/
+.github/workflows

.editorconfig

@@ -0,0 +1,15 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{json,yml,md,toml}]
+indent_style = space
+indent_size = 2

.github/.kodiak.toml

@@ -0,0 +1,9 @@
+# https://kodiakhq.com/docs/quickstart
+version = 1
+
+[merge]
+method = "squash"
+
+  [merge.message]
+  title = "pull_request_title"
+  body  = "pull_request_body"

.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: "/"
+    open-pull-requests-limit: 1
+    schedule:
+      interval: daily
+    labels:
+      - automerge
+  - package-ecosystem: pip
+    directory: "/"
+    open-pull-requests-limit: 1
+    schedule:
+      interval: daily
+    labels:
+      - automerge

.github/workflows/ci.yml

@@ -0,0 +1,225 @@
+name: CI with dynamic parallel matrix
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  TIMEOUT: '-1'    # nbconvert timeout
+  EXTRA_ARGS: ''   # Extra arguments for nbconvert
+  CACHE_NUM: '1'
+  JULIA_NUM_THREADS: 'auto'
+  JULIA_CONDAPKG_BACKEND: 'Null'
+  JULIA_CI: 'true'
+  PY_VER: '3.12'
+
+jobs:
+  setup:
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.set-matrix.outputs.matrix }}
+      hash: ${{ steps.cache-julia.outputs.cache-primary-key }}
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+    - name: Setup Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ env.PY_VER }}
+    - name: Cache pip
+      uses: actions/cache@v3
+      id: cache-pip
+      with:
+        path: ${{ env.pythonLocation }}
+        key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
+    - name: Install python packages
+      if: ${{ steps.cache-pip.outputs.cache-hit != 'true' }}
+      run: pip install -r requirements.txt
+    - name: Read Julia version
+      uses: SebRollen/[email protected]
+      id: read_toml
+      with:
+        file: 'Manifest.toml'
+        field: 'julia_version'
+    - name: Install Julia using jill.sh
+      run: |
+        wget -O /tmp/jill.sh https://raw.githubusercontent.com/abelsiqueira/jill/main/jill.sh
+        bash /tmp/jill.sh --version ${{ steps.read_toml.outputs.value }} -y
+        echo "$HOME/.local/bin" >> $GITHUB_PATH
+    - name: Cache Julia packages
+      uses: actions/cache/restore@v3
+      id: cache-julia
+      with:
+        path: |
+          ~/.julia
+          !~/.julia/registries
+        key: ${{ runner.os }}-julia-${{ env.CACHE_NUM }}-${{ hashFiles('src/**','Project.toml', 'Manifest.toml')}}
+        restore-keys: |
+          ${{ runner.os }}-julia-${{ env.CACHE_NUM }}-
+    - name: Install Julia packages
+      if: ${{ steps.cache-julia.outputs.cache-hit != 'true' }}
+      run: |
+        julia --color=yes -e 'using Pkg; Pkg.add(["IJulia"])'
+        julia --project=@. --color=yes -e 'using Pkg, Dates; Pkg.instantiate(); Pkg.resolve(); Pkg.precompile(); Pkg.gc(collect_delay=Day(0))'
+    - name: Save Julia packages
+      uses: actions/cache/save@v3
+      if: ${{ steps.cache-julia.outputs.cache-hit != 'true' }}
+      with:
+        path: |
+          ~/.julia
+          !~/.julia/registries
+        key: ${{ steps.cache-julia.outputs.cache-primary-key }}
+    - name: List notebooks as a JSON array
+      id: set-matrix
+      working-directory: docs
+      run: echo "matrix=$(python -c 'import glob, json; print(json.dumps(glob.glob("**/*.ipynb", recursive=True)))')" >> "$GITHUB_OUTPUT"
+
+  execute:
+    needs: setup
+    strategy:
+      max-parallel: 20
+      fail-fast: false
+      matrix:
+        # Notebooks need to be executed
+        notebook: ${{ fromJSON(needs.setup.outputs.matrix) }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Restore notebook if present
+        uses: actions/cache/restore@v3
+        id: cache
+        with:
+          path: docs/${{ matrix.notebook }}
+          key: ${{ runner.os }}-notebook-${{ hashFiles(format('docs/{0}', matrix.notebook)) }}-${{ needs.setup.outputs.hash }}
+      - name: Setup Python
+        if: ${{ steps.cache.outputs.cache-hit != 'true' }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PY_VER }}
+      - name: Cache pip
+        if: ${{ steps.cache.outputs.cache-hit != 'true' }}
+        uses: actions/cache@v3
+        id: cache-pip
+        with:
+          path: ${{ env.pythonLocation }}
+          key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
+      - name: Read Julia version
+        if: ${{ steps.cache.outputs.cache-hit != 'true' }}
+        uses: SebRollen/[email protected]
+        id: read_toml
+        with:
+          file: 'Manifest.toml'
+          field: 'julia_version'
+      - name: Install Julia using jill.sh
+        if: ${{ steps.cache.outputs.cache-hit != 'true' }}
+        run: |
+          wget -O /tmp/jill.sh https://raw.githubusercontent.com/abelsiqueira/jill/main/jill.sh
+          bash /tmp/jill.sh --version ${{ steps.read_toml.outputs.value }} -y
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+      - name: Restore Julia packages
+        if: ${{ steps.cache.outputs.cache-hit != 'true' }}
+        uses: actions/cache/restore@v3
+        with:
+          path: |
+            ~/.julia
+            !~/.julia/registries
+          key: ${{ needs.setup.outputs.hash }}
+      - name: Install Julia kernel
+        if: ${{ steps.cache.outputs.cache-hit != 'true' }}
+        run: |
+          julia --color=yes -e 'using IJulia; IJulia.installkernel("Julia", "--project=@.")'
+      - name: Execute Notebook
+        if: ${{ steps.cache.outputs.cache-hit != 'true' }}
+        run: >
+          jupyter nbconvert --to notebook --execute --inplace ${{ env.EXTRA_ARGS }}
+          --ExecutePreprocessor.timeout=${{ env.TIMEOUT }}
+          --ExecutePreprocessor.kernel_name=julia-1.$(julia -e 'print(VERSION.minor)')
+          docs/${{ matrix.notebook }}
+      - name: Cache notebook
+        uses: actions/cache/save@v3
+        if: ${{ steps.cache.outputs.cache-hit != 'true' }}
+        with:
+          path: docs/${{ matrix.notebook }}
+          key: ${{ steps.cache.outputs.cache-primary-key }}
+      - name: Upload Notebook
+        uses: actions/upload-artifact@v3
+        with:
+          name: notebooks
+          path: docs*/${{ matrix.notebook }}  # keep folder structure
+          retention-days: 1
+
+  render:
+    needs: execute
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Download notebooks
+        uses: actions/download-artifact@v3
+        with:
+          name: notebooks
+          path: out/
+      - name: Display structure of downloaded files
+        run: ls -R
+        working-directory: out
+      - name: Copy back built notebooks
+        run: cp --verbose -rf out/docs/* docs/
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PY_VER }}
+      - name: Cache pip
+        uses: actions/cache@v3
+        id: cache-pip
+        with:
+          path: ${{ env.pythonLocation }}
+          key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
+      - name: Build website
+        run: jupyter-book build docs/
+      - name: Upload pages artifact
+        if: ${{ github.ref == 'refs/heads/main' }}
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: docs/_build/html/
+
+  # CI conclusion for GitHub status check
+  # Adaped from https://brunoscheufler.com/blog/2022-04-09-the-required-github-status-check-that-wasnt
+  CI:
+    needs: render
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - run: |
+          if [[ ${{ needs.render.result }} == "success" ]]; then
+            echo "Tests passed"
+            exit 0
+          else
+            echo "Tests failed"
+            exit 1
+          fi
+
+  # Deployment job
+  deploy:
+    name: Deploy to GitHub pages
+    needs: render
+    if: ${{ github.ref == 'refs/heads/main' }}
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v3

.github/workflows/linkcheck.yml

@@ -0,0 +1,41 @@
+name: Check markdown links
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 0 1 * *' # Every month
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - '.github/workflows/linkcheck.yml'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  linkcheck:
+    env:
+      DIR: 'docs'
+      PY_VER: '3.12'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PY_VER }}
+      - name: Cache pip
+        uses: actions/cache@v3
+        id: cache-pip
+        with:
+          path: ${{ env.pythonLocation }}
+          key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
+      - name: Install python packages
+        if: ${{ steps.cache-pip.outputs.cache-hit != 'true' }}
+        run: pip install -r requirements.txt
+      - name: Build website
+        run: jupyter-book build ${DIR} --builder linkcheck

.github/workflows/update-manifest.yml

@@ -0,0 +1,50 @@
+name: Auto update Julia dependencies
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 0 * * 1' # Every week
+  push:
+    branches:
+      - main
+    paths:
+      - .github/workflows/update-manifest.yml
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  APP_ID: '189113' # https://github.com/apps/wen-wei-s-pr-bot
+
+jobs:
+  update-manifest:
+    permissions:
+      contents: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Julia
+        uses: julia-actions/setup-julia@v1
+      - name: Update Julia dependencies
+        env:
+          JULIA_PKG_PRECOMPILE_AUTO: '0'
+        run: julia --color=yes --project=@. -e 'import Pkg; Pkg.update()'
+      # Authenticate with a custom GitHub APP
+      # https://github.com/peter-evans/create-pull-request/blob/main/docs/concepts-guidelines.md#authenticating-with-github-app-generated-tokens
+      - name: Generate token for PR
+        uses: tibdex/github-app-token@v2
+        id: generate-token
+        with:
+          app_id: ${{ env.APP_ID }}
+          private_key: ${{ secrets.APP_PRIVATE_KEY }}
+      - name: Create Pull Request
+        id: cpr
+        uses: peter-evans/create-pull-request@v5
+        with:
+          title: Julia Dependency Update
+          token: ${{ steps.generate-token.outputs.token }}
+          labels: |
+            automerge