FAQ: quick fixes for setup, tests, and running the demo

[niisaban]

Here are quick fixes for the most common issues.

CI: minimal smoke test (GitHub Actions)

name: ci(smoke)

on:
  push:
    paths: ["**.py", ".github/workflows/**"]
  workflow_dispatch:

jobs:
  smoke:
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Install deps
        run: |
          python -m pip install -U pip
          pip install -r requirements.txt
      - name: Run smoke tests
        env:
          PYTHONPATH: ${{ github.workspace }}
        run: |
          pytest -q --maxfail=1 -ra

Run the demo locally (Windows PowerShell)

# 1) Create + activate venv
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# 2) Install deps
pip install -r requirements.txt

# 3) Expose repo root to Python for this shell
$env:PYTHONPATH = (Get-Location).Path

# 4a) Quick demo (choose one you have)
# python scripts/run_quickstart.py
pytest -q --maxfail=1 -ra

Run the demo locally (macOS / Linux, bash/zsh)

# 1) Create + activate venv
python -m venv .venv && source .venv/bin/activate

# 2) Install deps
pip install -r requirements.txt

# 3) Expose repo root for this shell
export PYTHONPATH="$PWD"

# 4a) Quick demo (choose one you have)
# python scripts/run_quickstart.py
pytest -q --maxfail=1 -ra

Optional: execute the quickstart notebook from CLI

# If your repo has a notebooks/00_quickstart.ipynb:
pip install jupyter nbconvert
jupyter nbconvert --to notebook --execute notebooks/00_quickstart.ipynb \
  --output notebooks/00_quickstart.out.ipynb

Tests failing locally? Try these quick fixes

#Use Python 3.11 (matches CI).

#Upgrade packaging toolchain:

python -m pip install -U pip setuptools wheel

#Recreate the venv cleanly:

rm -rf .venv && python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
#Fast signal only:
```bash
pytest -q --maxfail=1 -ra

#Windows: ensure the repo is on PYTHONPATH for the current shell:

$env:PYTHONPATH = (Get-Location).Path

#Apple Silicon wheel hiccups:

pip install --only-binary=:all: numpy scipy