Prepare cuvarbase 1.0.1 with verified external benchmark archives

.editorconfig

@@ -0,0 +1,53 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+trim_trailing_whitespace = true
+
+# Python files
+[*.py]
+indent_style = space
+indent_size = 4
+max_line_length = 88
+
+# CUDA files
+[*.cu]
+indent_style = space
+indent_size = 4
+max_line_length = 100
+
+# Markdown files
+[*.md]
+trim_trailing_whitespace = false
+max_line_length = off
+
+# YAML files
+[*.{yml,yaml}]
+indent_style = space
+indent_size = 2
+
+# Configuration files
+[*.{json,toml,cfg}]
+indent_style = space
+indent_size = 2
+
+# Shell scripts
+[*.sh]
+indent_style = space
+indent_size = 2
+
+# Makefiles require tabs
+[Makefile]
+indent_style = tab
+
+# reStructuredText
+[*.rst]
+indent_style = space
+indent_size = 3
+max_line_length = off

.gitattributes

@@ -0,0 +1,10 @@
+* text=auto eol=lf
+*.npz binary
+*.png binary
+*.jpg binary
+*.whl binary
+*.tar.gz binary
+
+# Frozen receipts include byte hashes; retain their line endings and whitespace.
+benchmarks/results/tls_survey_2026-09-10/** -text -whitespace
+docs/validation/release-prepared-20260927/** -text -whitespace

.github/workflows/tests.yml

@@ -0,0 +1,186 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  # CPU test suite: cuvarbase/tests/conftest.py stubs pycuda when it is
+  # not installed, so the pure-CPU tests (sparse BLS ground truth, TLS
+  # grids/models/stats, NUFFT-LRT algorithm, frequency grids, kernel
+  # inventory, lazy-import contract, input validation) run and every
+  # test that touches a device skips. GPU kernels are validated on a
+  # CUDA pod before releases (see tools/README.md).
+  test-cpu:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    # The `test` extra of pyproject.toml is listed by hand here because
+    # installing `.[test]` would pull in the runtime dependency pycuda,
+    # which cannot build without a CUDA toolkit (no binary wheels), so
+    # the runners have no way to satisfy it. Keep this line in step with
+    # [project.optional-dependencies] test. batman-package is a small C
+    # extension that builds from sdist in well under a minute.
+    - name: Install test dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install "numpy>=1.22" "scipy>=1.8" pytest nfft astropy batman-package transitleastsquares
+
+    - name: Run CPU test suite (GPU tests skip via stubbed pycuda)
+      run: |
+        # testpaths / -rs / --strict-markers come from [tool.pytest.ini_options]
+        python -m pytest -rs -v --tb=short
+
+  release-tools:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+    - name: Install host dependencies
+      run: python -m pip install numpy scipy matplotlib pytest batman-package
+    - name: Check benchmark qualification and monitoring recovery
+      run: python -m pytest -q benchmarks/tls_survey tools/test_watch_jobs.py tools/test_benchmark_archive.py
+    - name: Keep raw benchmark evidence out of Git
+      run: python tools/check_repository_artifacts.py
+
+  # Packaging smoke test: build the sdist and wheel, check the metadata,
+  # install each artifact into a clean environment (pycuda absent) and
+  # import/run it from OUTSIDE the source tree. This catches
+  # missing-subpackage, missing-package-data and metadata bugs that
+  # source-tree testing hides.
+  package-smoke:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+
+    - name: Build sdist and wheel
+      run: |
+        python -m pip install --upgrade pip build twine
+        python -m build
+        ls -l dist/
+        # setup.cfg's universal=1 once mis-tagged the wheel py2.py3
+        ls dist/cuvarbase-*-py3-none-any.whl
+
+    - name: Check metadata (twine)
+      run: |
+        python -m twine check --strict dist/*
+
+    - name: Install wheel (no deps), smoke-import, run the shipped tests
+      run: |
+        python -m venv /tmp/smoke-wheel
+        /tmp/smoke-wheel/bin/pip install --upgrade pip
+        /tmp/smoke-wheel/bin/pip install "numpy>=1.22" "scipy>=1.8" astropy nfft pytest
+        /tmp/smoke-wheel/bin/pip install --no-deps dist/*.whl
+        /tmp/smoke-wheel/bin/python tools/ci_wheel_smoke.py
+        # The shipped test package must pass from the installed wheel,
+        # away from the checkout (the command INSTALL.rst advertises).
+        mkdir -p /tmp/pyargs-run && cd /tmp/pyargs-run
+        /tmp/smoke-wheel/bin/python -m pytest --pyargs cuvarbase -rs -p no:cacheprovider
+
+    - name: Install sdist (no deps) and smoke-import
+      run: |
+        python -m venv /tmp/smoke-sdist
+        /tmp/smoke-sdist/bin/pip install --upgrade pip
+        /tmp/smoke-sdist/bin/pip install "numpy>=1.22" "scipy>=1.8"
+        /tmp/smoke-sdist/bin/pip install --no-deps dist/*.tar.gz
+        /tmp/smoke-sdist/bin/python tools/ci_wheel_smoke.py
+
+    - name: Upload dist/
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist
+        path: dist/
+        if-no-files-found: error
+
+  # Docs build: autodoc imports the package with pycuda mocked
+  # (conf.py autodoc_mock_imports), so the API pages build without a
+  # GPU. The plot-directive figures DO need a CUDA device; on the runner
+  # they fail as "Exception occurred in plotting ..." warnings and the
+  # pages keep their source listings. Those are the only warnings
+  # tolerated -- any other WARNING/ERROR (bad docstring markup, broken
+  # cross-references, missing toctree entries) fails the job.
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+
+    - name: Install docs dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install "numpy>=1.22" "scipy>=1.8" -r docs/requirements.txt
+
+    - name: Build HTML docs
+      run: |
+        python -m sphinx -b html -E -a -w warnings.log docs/source docs/build/html
+
+    - name: Fail on any warning other than the expected plot-directive GPU failures
+      run: |
+        # -w logs each warning as "<file>:<line>: WARNING: <text>" (or
+        # ERROR:/CRITICAL:); the plot directive's traceback continuation
+        # lines carry no such prefix. Keep only the diagnostic lines that
+        # are not the GPU-less "Exception occurred in plotting <name>".
+        grep -E ': (WARNING|ERROR|CRITICAL): ' warnings.log \
+          | grep -v -E ': WARNING: Exception occurred in plotting ' > unexpected.log || true
+        if [ -s unexpected.log ]; then
+          echo "::error::unexpected Sphinx warnings:"
+          cat unexpected.log
+          exit 1
+        fi
+        echo "docs build clean (plot-directive GPU failures only)"
+
+    - name: Upload HTML
+      uses: actions/upload-artifact@v4
+      with:
+        name: docs-html
+        path: docs/build/html/
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+
+    - name: Install linting tools
+      run: |
+        python -m pip install --upgrade pip
+        pip install flake8
+
+    - name: Lint with flake8 (errors only)
+      run: |
+        # Syntax errors, undefined names and invalid escape sequences
+        # (W605: a SyntaxError on future Pythons) are real failures
+        flake8 cuvarbase --count --select=E9,F63,F7,F82,W605 --show-source --statistics
+
+    - name: Lint with flake8 (style, advisory)
+      run: |
+        flake8 cuvarbase --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics

.gitignore

@@ -48,7 +48,7 @@ coverage.xml
 *.mo
 *.pot
 
-# Django stuff:
+# Runtime logs
 *.log
 
 # Sphinx documentation
@@ -63,22 +63,33 @@ target/
 
 .ipynb_checkpoints
 .idea/*
-tools/repos
-Untitled*.ipynb
 
 # vim backups
 *.swp
 
 # LaTeX
 *.aux
 *.pdf
+!docs/figures/*.pdf
 
 # misc
-scripts/saved_results
 .DS_Store
 work/
 *.png
+# ... except published documentation and benchmark figures
+!docs/**/*.png
 *.gif
-*HAT*txt
-testing/*
-custom_test_ce.py
+
+# RunPod configuration (contains credentials)
+.runpod.env
+
+# Local service credentials
+.env
+.env.*
+!.env.example
+!.env.sample
+
+# Downloaded benchmark archives and restored validation output
+.benchmark-archives/
+docs/validation/**/*.log
+docs/validation/**/*.xml

.mailmap

@@ -0,0 +1,11 @@
+# Canonical author identities for git shortlog / blame.
+John Hoffman <johnh2o2@gmail.com> John Hoffman <johnhoffman@Johns-MacBook-Pro.local>
+John Hoffman <johnh2o2@gmail.com> John <johnh2o2@gmail.com>
+John Hoffman <johnh2o2@gmail.com> John Hoffman <jah5@princeton.edu>
+John Hoffman <johnh2o2@gmail.com> John <jah5@princeton.edu>
+John Hoffman <johnh2o2@gmail.com> John Hoffman <johnhoffman@fb.com>
+John Hoffman <johnh2o2@gmail.com> John <johnhoffman@fb.com>
+John Hoffman <johnh2o2@gmail.com> John Hoffman <john.hoffman@xaxis.com>
+John Hoffman <johnh2o2@gmail.com> John Hoffman <john.hoffman@strong.io>
+Attila Bódi <astrobatty@gmail.com> astrobatty <astrobatty@gmail.com>
+Michael Coughlin <coughlim@carleton.edu> Michael Coughlin <michael.coughlin@ligo.org>

AGENTS.md

@@ -0,0 +1,21 @@
+# Long-running cuvarbase work
+
+The user has requested automatic monitoring so they do not have to return to
+ask whether a background job failed. Follow [docs/JOB_MONITORING.md](docs/JOB_MONITORING.md).
+
+- Before leaving a long-running or paid cloud job unattended, register it with
+  the persistent job monitor and verify its budget guard and collector are live.
+- A process exiting, an archive copying, or a finalizer completing is not enough
+  to call the work successful. Inspect required step results and scientific
+  qualifications separately from preservation and shutdown receipts.
+- Handle queued monitoring events in this conversation: acknowledge receipt,
+  inspect the checkpoint, and continue already-authorized work. No new permission
+  is required for routine fixes within existing scope and budgets.
+- Preserve completed and partial experiments. Never silently replace failed
+  numerical results, weaken their gates, or rerun them until they pass. Record
+  operational repairs separately and resume from verified checkpoints.
+- Verify the actual command's environment and package import before expensive
+  stages. Source-tree pytest and a standalone script can have different import
+  paths; install the intended wheel or explicitly use the intended source path.
+- Keep final release review open until required validation and backup checks
+  have been reviewed. Acknowledge failures honestly rather than marking them done.