CLI, so many bugfixes, block structured systems, mhom exposed, user homotopy, two-level parallelism...

.git-blame-ignore-revs

@@ -0,0 +1,13 @@
+# Commits listed here are skipped by `git blame` so that large, purely mechanical
+# changes (whitespace, indentation, reformatting) do not obscure the real authorship
+# of each line.  GitHub honours this file automatically.  Locally, run once:
+#
+#     git config blame.ignoreRevsFile .git-blame-ignore-revs
+#
+# RULES:
+#   * Only add commits that are PURELY formatting -- no behavioural or semantic
+#     change, no documentation-content change.  Keep such passes in their own
+#     isolated commit so the whole commit can be safely ignored.
+#   * Add the full 40-character commit SHA, with a comment naming what it did.
+#
+# (No revisions yet -- add the whitespace/indentation pass SHA here when it lands.)

.github/workflows/build_docs.yml

@@ -79,7 +79,10 @@ jobs:
       - name: Install system dependencies (Doxygen)
         run: |
           sudo apt-get update
-          sudo apt-get install -y doxygen graphviz
+          # texlive-binaries provides bibtex, which Doxygen needs to number and
+          # render the \cite references (CITE_BIB_FILES in the Doxyfile) into a
+          # bibliography in the published C++ docs.
+          sudo apt-get install -y doxygen graphviz texlive-binaries
 
       - name: Fetch doxygen-awesome-css
         run: |
@@ -104,7 +107,7 @@ jobs:
           python -m pip install --upgrade pip
           pip install \
             sphinx sphinx-rtd-theme sphinxcontrib-bibtex gitpython \
-            scikit-build-core build numpy
+            scikit-build-core build numpy matplotlib pandas
 
       - name: Download built wheel
         uses: actions/download-artifact@v5
@@ -115,6 +118,13 @@ jobs:
       - name: Install bertini from built wheel
         run: pip install --no-index --find-links dist/ bertini2
 
+      - name: Run tutorial doctests (Sphinx)
+        # Execute the `.. testcode::` / `>>>` blocks in the docs against the installed wheel, so
+        # the tutorials are verified code, not just prose.  Fails the build if any doctest fails.
+        working-directory: python/docs
+        run: |
+          sphinx-build -b doctest --keep-going source ../../build/docs/doctest
+
       - name: Build Python docs (Sphinx)
         working-directory: python/docs
         env:

.github/workflows/doc_lint.yml

@@ -0,0 +1,63 @@
+name: Documentation lint 📑
+
+# Cheap, fast doc-correctness gate -- runs Doxygen only (no compilation, no wheel,
+# no graphviz) so it can run on every PR in well under a minute.  This is the first
+# foothold of a broader linting initiative; future linters (clang-format,
+# clang-tidy, include-what-you-use, ...) can be added as additional jobs here.
+#
+# It does NOT belong in build_and_test.yml: that workflow is the expensive
+# build/test matrix, and it already `paths-ignore`s Doxyfile/doc_resources/docs, so
+# doc-only changes skip it and hit only this lint -- exactly the fast feedback we want.
+
+# Header (core/include) changes reach this lint through build_and_test.yml, which
+# calls it as a prerequisite gate (see workflow_call below).  The standalone
+# triggers here cover only the doc-config/tooling paths that build_and_test
+# deliberately `paths-ignore`s, so the lint still runs for doc-only changes without
+# double-running on a typical code PR.
+on:
+  push:
+    branches:
+      - develop
+      - main
+    paths:
+      - 'Doxyfile'
+      - 'doc_resources/**'
+      - 'tools/doclint.sh'
+      - 'tools/doc_undocumented_baseline.txt'
+      - '.github/workflows/doc_lint.yml'
+  pull_request:
+    paths:
+      - 'Doxyfile'
+      - 'doc_resources/**'
+      - 'tools/doclint.sh'
+      - 'tools/doc_undocumented_baseline.txt'
+      - '.github/workflows/doc_lint.yml'
+  workflow_dispatch:
+  # Called by build_and_test.yml as a prerequisite gate, so no C++ compilation
+  # starts until the docs lint is green.
+  workflow_call:
+
+# The undocumented-entity ratchet count in tools/doc_undocumented_baseline.txt is
+# specific to this Doxygen version; CI must use the same one that seeded the
+# baseline, not whatever the runner's apt happens to ship.  Bump both together.
+env:
+  DOXYGEN_VERSION: "1.13.2"
+
+jobs:
+  doc_lint:
+    name: Doxygen doc lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install pinned Doxygen
+        run: |
+          url="https://github.com/doxygen/doxygen/releases/download/Release_${DOXYGEN_VERSION//./_}/doxygen-${DOXYGEN_VERSION}.linux.bin.tar.gz"
+          curl -sSL "$url" | tar -xz
+          echo "$PWD/doxygen-${DOXYGEN_VERSION}/bin" >> "$GITHUB_PATH"
+
+      - name: Show Doxygen version
+        run: doxygen --version
+
+      - name: Lint C++ documentation
+        run: bash tools/doclint.sh

.github/workflows/github-gitlab-sync.yml

@@ -1,12 +1,22 @@
-name: Sync to MPI GitLab
-on: 
+name: Sync to GitLab mirror
+on:
   push
+
+# Any repo (upstream or fork) that configures the three GITLAB_* secrets gets
+# mirrored to its own GitLab target; repos without the secrets skip silently.
+# This replaces the old hardcoded `if: github.repository == 'bertiniteam/b2'`,
+# which prevented forks from syncing even when their secrets were set.
+# Note: the `secrets` context is not available in job-level `if`, hence the
+# env indirection.
+
 jobs:
   sync:
-    if: github.repository == 'bertiniteam/b2' #only on official 
     runs-on: ubuntu-latest
+    env:
+      GITLAB_CONFIGURED: ${{ secrets.GITLAB_URL != '' }}
     steps:
     - name: Sync to GitLab
+      if: env.GITLAB_CONFIGURED == 'true'
       # You may pin to the exact commit or the version.
       # uses: kujov/gitlab-sync@b19399d43e81ac88acb6eefd5588e6ebde3d7d88
       uses: kujov/gitlab-sync@2.2.1
@@ -18,5 +28,4 @@ jobs:
         # Your GitLab Personal Access Token with required permissions
         gitlab_pat: ${{ secrets.GITLAB_PAT }}
         # Whether to force push to GitLab. Defaults to false.
-
-        force_push: true # optional, default is false
+        force_push: true

.github/workflows/publish.yml

@@ -15,7 +15,7 @@ concurrency:
 
 jobs:
   check_version:
-    name: Check pyproject.toml version matches tag
+    name: Check VERSION file matches tag
     runs-on: ubuntu-latest
     outputs:
       is_prerelease: ${{ steps.check.outputs.is_prerelease }}
@@ -31,17 +31,31 @@ jobs:
             exit 1
           fi
           TAG_VERSION="${TAG#v}"
-          PYPROJECT_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
-          if [ "$TAG_VERSION" != "$PYPROJECT_VERSION" ]; then
-            echo "Error: tag '$TAG' does not match pyproject.toml version '$PYPROJECT_VERSION'"
+          # The version is dynamic in pyproject.toml; its single source of truth
+          # is the top-level VERSION file (read by scikit-build-core and CMake).
+          FILE_VERSION=$(tr -d '[:space:]' < VERSION)
+          if [ "$TAG_VERSION" != "$FILE_VERSION" ]; then
+            echo "Error: tag '$TAG' does not match VERSION file '$FILE_VERSION'"
             exit 1
           fi
-          echo "OK: tag '$TAG' matches pyproject.toml version '$PYPROJECT_VERSION'"
+          echo "OK: tag '$TAG' matches VERSION file '$FILE_VERSION'"
           echo "$TAG" | grep -Eq '\.(dev|a|b|rc)[0-9]+$' && echo "is_prerelease=true" >> $GITHUB_OUTPUT || echo "is_prerelease=false" >> $GITHUB_OUTPUT
 
+  check_timing_freshness:
+    name: Check tutorial timings are fresh
+    # Only gate real releases -- prereleases (.dev/a/b/rc) are exactly when a timing refresh may not
+    # have happened yet.  A skipped job counts as satisfied for downstream `needs`.
+    if: needs.check_version.outputs.is_prerelease == 'false'
+    needs: check_version
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Verify the scaling-tutorial timings are not stale
+        run: python tools/check_timing_freshness.py
+
   build_and_test:
     name: Build and test
-    needs: check_version
+    needs: [check_version, check_timing_freshness]
     uses: ./.github/workflows/build_and_test.yml
 
   publish-to-testpypi:

.gitignore

@@ -95,3 +95,31 @@ _skbuild/
 build/
 bld/
 build_mine/
+
+# Wheel / sdist output
+dist/
+
+# Local Claude Code config and personal working notes
+.claude/
+z_notes/
+.mcp.json
+
+# C++ test runner logs (ctest/Boost.Test output at repo root)
+bertini2_tests_*.log
+
+# Serialization test output files (Boost.Serialization archives)
+/serialization_test_*
+
+# Classic Bertini CLI output files (written by bertini2_exe when run from repo root)
+/main_data
+/raw_data
+/raw_solutions
+/real_finite_solutions
+/midpath_data
+/finite_solutions
+/nonfinite_solutions
+/start
+/failed_paths
+
+# Compiled benchmark binaries (keep the .cpp sources)
+/tuning/arithmetic_cost

CLAUDE.md

@@ -14,9 +14,14 @@ Bertini 2 (b2) is a C++17 numerical algebraic geometry library with Python bindi
 # Configure (from repo root)
 cmake -DENABLE_UNIT_TESTING=ON -G Ninja -B build -S .
 
-# Build
+# Build everything (core library, bindings, exe, tests)
 cmake --build build --target all --config Release
 
+# For iterative C++ work, build just the core library first -- it's much faster, and
+# the heavy Boost.Python/eigenpy bindings (`_pybertini`) only need rebuilding when the
+# bindings themselves change:
+cmake --build build --target bertini2 --config Release
+
 # Run all C++ tests
 ctest --test-dir build/core
 ```
@@ -57,28 +62,43 @@ ctest --test-dir build/core
 ./build/core/test_generating
 ./build/core/test_nag_algorithms
 ./build/core/test_nag_datatypes
+./build/core/test_pool
 ./build/core/test_tracking_basics
 ./build/core/test_settings
 ```
 
 ### Python Tests
 
+`pytest` is the single way to run the Python tests (the suites are plain pytest
+functions + fixtures; the old `unittest` `TextTestRunner` aggregator scripts are gone):
+
 ```bash
 pytest python/test/
 ```
 
+The multiprecision default precision is **global mutable state**
+(`bertini.default_precision(n)`). An **autouse fixture in `python/test/conftest.py`**
+(`_reset_precision`) resets it to a known baseline (`DEFAULT_TEST_PRECISION = 30`) before
+every test and restores it afterward, so no test can inherit a neighbor's precision — do
+**not** re-introduce per-test `default_precision(...)` setup. To override the precision for
+a specific test, use the `precision` fixture (parametrize it indirectly, e.g.
+`@pytest.mark.parametrize("precision", [30, 50, 80], indirect=True)` with a
+precision-derived tolerance). When adding or debugging precision-sensitive tests, run the
+file on its own (`pytest python/test/classes/<file>.py`) to confirm it does not depend on
+cross-test state.
+
 ## Architecture
 
 The project has three layers, built in order:
 
 1. **`core/`** -- C++ shared library (`libbertini2`). Header-only-heavy design under `core/include/bertini2/`. Key subsystems:
-   - `function_tree/` -- Expression tree (nodes, operators, symbols) for representing polynomial systems
-   - `system/` -- Polynomial system construction, start systems (`start/total_degree.hpp`, `start/mhom.hpp`), patches, slices
+   - `function_tree/` -- Expression tree (nodes, operators, symbols) for *building and representing* polynomial systems. Nodes no longer evaluate: node-level recursive evaluation was removed -- the **SLP (`straight_line_program`) is the sole evaluator** (compile a system once, evaluate the compiled program). `Function`/`Handle` are gone; `NamedExpression` is the sole root node. See ADR-0027 (SLP: immutable Program + per-thread Memory) and ADR-0028 (named-node taxonomy).
+   - `system/` -- Polynomial system construction, start systems (`start/total_degree_linear_product.hpp`, `start/mhom.hpp`), patches, slices
    - `trackers/` -- Path tracking (fixed-precision and adaptive-precision trackers, predictors, Newton correctors)
    - `endgames/` -- Power series and Cauchy endgames for singular endpoint handling
-   - `nag_algorithms/` -- Higher-level algorithms (zero-dim solve, numerical irreducible decomposition)
+   - `nag_algorithms/` -- Higher-level algorithms (zero-dim solve; numerical irreducible decomposition is *framework scaffolding* -- not yet implemented, its `Solve()` throws)
    - `io/parsing/` -- Boost.Spirit Qi parsers for classic Bertini input format
-   - `blackbox/` -- CLI executable entry point (`bertini2_exe`)
+   - `blackbox/` -- CLI executable entry point (CMake target `bertini2_exe`, binary named `bertini2`)
 
 2. **`python_bindings/`** -- Boost.Python + eigenpy bindings producing `_pybertini` native module. Each `*_export.cpp` wraps the corresponding C++ subsystem. Depends on `eigenpy` for NumPy/Eigen interop.
 
@@ -87,9 +107,9 @@ The project has three layers, built in order:
 ## Key Dependencies
 
 - **GMP/MPFR/MPC** -- Arbitrary-precision arithmetic (found via custom CMake modules in `cmake/`)
-- **Eigen 3.3** -- Linear algebra (pinned to v3.3)
-- **Boost** (serialization, filesystem, log, graph, regex, timer, chrono, thread, unit_test_framework, python) -- Boost >= 1.82 required; `boost_system` is conditionally linked for Boost < 1.89
-- **eigenpy** -- Eigen/NumPy bridge for Python bindings
+- **Eigen 3** -- Linear algebra. **Not** pinned in cmake (`find_package(Eigen3)`, no version floor). In practice the version is coupled to the eigenpy build: the wheel CI builds **eigen 3.4.0** and then builds eigenpy against it (a dev env may use newer, e.g. `eigen=5.0.1`). Newer Eigen is welcome -- we *want* upstream improvements -- but it must be matched by an eigenpy built against the same Eigen (they share Eigen types across the binding ABI).
+- **Boost** (serialization, filesystem, log, graph, regex, timer, chrono, thread, unit_test_framework, python) -- no minimum version pinned in cmake; `boost_system` is conditionally linked for Boost < 1.89 (header-only from 1.89). Boost.Python is ABI-locked to one CPython version, so CI rebuilds it per target Python.
+- **eigenpy** -- Eigen/NumPy bridge for Python bindings. Built **from source** in CI at a single pinned version (`EIGENPY_VERSION` in `build_and_test.yml`, currently `3.13.0`) against the chosen Eigen -- eigenpy and bertini must use the *same* Eigen. eigenpy >= 3.13 sets the Python floor (>= 3.10).
 - **jrl-cmakemodules** -- CMake helper macros (auto-fetched via FetchContent if not found)
 
 ## Build System Notes
@@ -101,11 +121,44 @@ The project has three layers, built in order:
 
 ## CI/CD
 
-- `.github/workflows/build-and-publish-to-pypi.yml` -- Builds wheels on Ubuntu/macOS/Windows, publishes to TestPyPI on `develop` push, PyPI on version tags (`v*.*.*`).
-- Pushes to `develop` trigger TestPyPI publish; tagged releases go to PyPI with Sigstore signing and GitHub Releases.
+- `.github/workflows/build_and_test.yml` -- Builds wheels on Ubuntu/macOS/Windows and runs tests. Triggered by pull requests and pushes to `develop`/`main`.
+- `.github/workflows/doc_lint.yml` -- A cheap Doxygen doc-correctness gate that **the build matrix depends on** (it runs first; if it fails, nothing compiles). **Run `bash tools/doclint.sh` locally before pushing any C++ change**, or CI will bounce the whole build. It needs `doxygen` on PATH (`brew install doxygen`). Two passes: (1) *correctness* — `@param` names must match signatures, no doc blocks on removed signatures, no unresolved `\ref`/`\cite` (zero tolerance); (2) *undocumented ratchet* — the count of undocumented public entities in `tools/doc_undocumented_baseline.txt` may only **decrease** (currently `0`, so **every new public C++ entity — including each struct data member — needs a Doxygen comment**, e.g. `///< ...`). If you legitimately reduce the count, run `bash tools/doclint.sh --update-baseline` to lock it in.
+- `.github/workflows/publish.yml` -- Publishes to TestPyPI on `develop` push, PyPI on version tags (`v*.*.*`) with Sigstore signing and GitHub Releases.
+
+### Linux wheel test coverage
+
+Linux wheels are built inside a `manylinux_2_34` container (AlmaLinux 9, MPFR 4.1; set via `CIBW_MANYLINUX_X86_64_IMAGE`). The **full pytest suite runs on all three platforms** — on Linux it runs *inside* that container via `CIBW_TEST_COMMAND_LINUX`, and on macOS/Windows via the host-runner test jobs.
+
+This was not always so: for a while Linux ran an import smoke test only, because the suite was SIGABRT/SIGSEGV-crashing — a crash *misattributed* to the older `manylinux_2_28` container's MPFR 3.1.6. The real cause is a **version-independent** bug (uninitialized `mpfr`/`mpc` numpy slots), now fixed in the bindings. Do **not** try to fix Linux test crashes by bumping MPFR or the manylinux image (that was tried and does not work) or by building MPFR from source (specifically out of bounds). See `docs/adr/0006-eigenpy-uninitialized-numpy-slot-guards.md` for the fix and `docs/adr/0003-manylinux-no-full-pytest.md` for the (now reversed) smoke-test stopgap and its history.
+
+## Python Bindings — Known Pitfalls
+
+### eigenpy writable Ref + adjacent scalar (ADR-0001)
+
+Never place a writable `Eigen::Ref<Vec<mpc_complex>>` argument **adjacent** to a `mpc_complex const&` scalar argument in a Boost.Python binding. eigenpy's from-Python converter for the writable Ref writes into a static rvalue-converter slot that overlaps with the storage for adjacent `const&` scalars, corrupting them. The corrupted `mpc_complex` then triggers `MPFR_ASSERTN` → SIGABRT.
+
+**Rule:** If a binding takes a writable `Eigen::Ref<Vec<ComplexT>>` and also needs scalar `ComplexT` args, pass the scalars **by value**:
+
+```cpp
+// WRONG — start_time/end_time get corrupted
+SuccessCode wrap(Eigen::Ref<Vec<ComplexT>> result,
+                 ComplexT const& start_time,   // ← adjacent const& scalar
+                 ComplexT const& end_time);
+
+// CORRECT — by-value copy is taken before the Ref converter runs
+SuccessCode wrap(Eigen::Ref<Vec<ComplexT>> result,
+                 ComplexT start_time,           // ← by value
+                 ComplexT end_time);
+```
+
+Single-argument bindings and read-only `Vec<T> const&` bindings are unaffected. See `docs/adr/0001-eigenpy-writable-ref-scalar-by-value.md`.
+
+## Architecture Decision Records
+
+`docs/adr/` contains ADRs for load-bearing design decisions — where the *why* would not be obvious from reading the code. Check there before undoing anything that looks strange.
 
 ## Conventions
 
 - C++ standard: C++17. Headers use `.hpp` extension.
 - License: GPL v3 with additional terms (see `licenses/`, `core/ADDITIONAL_GPL_TERMS`).
-- Version is tracked in `python/bertini/_version.py` and `pyproject.toml`.
+- Version is tracked in `pyproject.toml` (the `version = "..."` line), read at runtime via `importlib.metadata.version("bertini2")`.