Docs/adr eigenpy vec aliasing

.github/workflows/build_docs.yml

@@ -104,7 +104,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 +115,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/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

.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

@@ -63,10 +63,24 @@ ctest --test-dir build/core
 
 ### 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:
@@ -101,11 +115,43 @@ 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/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")`.

CMakeLists.txt

@@ -105,6 +105,16 @@ include("${JRL_CMAKE_MODULES}/base.cmake")
 compute_project_args(PROJECT_ARGS LANGUAGES CXX)
 project(${PROJECT_NAME} ${PROJECT_ARGS})
 
+option(USE_CCACHE "Use ccache to speed up rebuilds if available" ON)
+if(USE_CCACHE)
+  find_program(CCACHE_PROGRAM ccache)
+  if(CCACHE_PROGRAM)
+    set(CMAKE_CXX_COMPILER_LAUNCHER "${CCACHE_PROGRAM}")
+    set(CMAKE_C_COMPILER_LAUNCHER   "${CCACHE_PROGRAM}")
+    message(STATUS "ccache enabled: ${CCACHE_PROGRAM}")
+  endif()
+endif()
+
 include("${JRL_CMAKE_MODULES}/boost.cmake")
 
 if(BUILD_PYTHON_BINDINGS)
@@ -200,8 +210,6 @@ endif(WIN32)
 
 #target_link_boost_python(${PROJECT_NAME} PUBLIC)
 
-#set_property(TARGET bertini2_exe PROPERTY OUTPUT_NAME bertini2)
-
 add_subdirectory(core)
 
 

README.md

@@ -1,13 +1,15 @@
 
 # Quick links
 
+- [Documentation](https://bertini2.org)
+- [`bertini2` PyPI package](https://pypi.org/project/bertini2/)
 - [Wiki](https://github.com/bertiniteam/b2/wiki)
 
 ---
 
 # Overview
 
-The solution of arbitrary polynomial systems is an area of active research, and has many applications in math, science and engineering.  This software, Bertini 2, is a complete re-implementation of [Bertini 1](https://bertini.nd.edu) from C into C++/Python.
+The solution of arbitrary polynomial systems is an area of active research, and has many applications in math, science and engineering.  This software, Bertini 2, is a re-implementation of [Bertini 1](https://bertini.nd.edu) from C into C++/Python.
 
 The theoretical basis for the solution of polynomials with Bertini is a theorem which bounds the number of solutions a system may have. It sits together with the numerical computational tool of "homotopy continuation". the act of "continuing" from one system into another through a "homotopy", as depicted in the below diagram:
 
@@ -18,29 +20,30 @@ The theoretical basis for the solution of polynomials with Bertini is a theorem
 
 # Current capabilites
 
-Bertini 2 currently has implemented the foundations of Numerical Algebraic Geometry.  Development is ongoing, and here's what we have so far:
+Bertini 2 has already implemented most of the foundations of Numerical Algebraic Geometry.  Development is ongoing, and here's what we have so far:
 
-- C++ functions and types, with Python bindings.
-- Through Python, runtime scriptable construction of systems and interactivity with their zero-dimensional solutions.
-- Construction of multivariate polynomial and non-polynomial systems.
-- Evaluation of systems and their Jacobians in double and arbitrary multiple precision, using two different methods.
+- A blackbox that implements tracktype 0 (zerodim solving) for the total degree and mhom start systems.  User homotopy not yet exposed
+- Through Python bindings, runtime scriptable construction of systems and interactivity with their zero-dimensional solutions.
+- Python construction of multivariate polynomial and non-polynomial systems, including from linear algebra operations via numpy and Bertini 2's variables and extended numeric types.  
+- Evaluation of systems and their Jacobians in double and arbitrary multiple precision.
 - Construction of the Total Degree and Multihomogeneous start systems.
 - Construction of homotopies (they're just systems with path variables defined).
 - Tracking of a start point x_0, corresponding to a particular time $t_0 \in \mathbb{C}^n$ in a homotopy $H$, from $t_0$ to $t_1$.
 - Running of the Power Series and Cauchy endgames, in double, multiple, and adaptive precision.
 
-Development is ongoing, and we want your help!
+See the published docs for latest the officially released documentation (which will always lag behind the doc from the dev version).
 
 ---
 
 # Missing functionality
 
-* Parallel solving
+✨ In-progress!!!  
+
 * Numerical irreducible decomposition
 * Membership testing
 * and other algorithms
 
-Users wanting a more developed implementation are recommended to use [Bertini 1](https://bertini.nd.edu) or [homotopycontinuation.jl](https://www.juliahomotopycontinuation.org/), or one of the other packages implementing the theory.  
+Users wanting a more stable implementation are recommended to use [Bertini 1](https://bertini.nd.edu) or [homotopycontinuation.jl](https://www.juliahomotopycontinuation.org/), or one of the other packages implementing the theory.  
 
 ---
 
@@ -55,12 +58,12 @@ The Python package `bertini2` provides pre-built wheels for Linux, macOS, and Wi
 pip install bertini2
 ```
 
-Once it's installed, you `import bertini`
+Once it's installed, you `import bertini` (not `import bertini2`!)
 
-* Linux: Python 3.9-3.14
-* MacOS (Apple Silicon): Python 3.9-3.14
-* MacOS (Intel): not supported
-* Windows: Python 3.9-3.14
+* Linux: Python 3.10-3.14
+* MacOS (Apple Silicon): Python 3.10-3.14
+* MacOS (Intel): not currently supported
+* Windows: Python 3.10-3.14
 
 
 ## Building from source

benchmark/README.md

@@ -0,0 +1,69 @@
+# Bertini2 Parallel Benchmark
+
+Scripts for measuring MPI + thread parallel speedup of the `bertini2` solver.
+
+## Prerequisites
+
+- `bertini2` built with MPI support (`cmake -DENABLE_MPI=ON ...`)
+- `mpirun` on `PATH`
+- Python 3.7+, no external packages needed
+
+## Quick Start
+
+```bash
+# From the repo root
+python benchmark/run_benchmark.py \
+    --bertini2 ./build/core/bertini2 \
+    --input    benchmark/inputs/small.b2 \
+    --ranks    1 2 \
+    --threads  1 2
+```
+
+This runs the `small.b2` system (27 paths) with 4 combinations of ranks × threads,
+prints a speedup table, and writes `benchmark_results.csv`.
+
+## Sample Input Files
+
+| File | Variables | Degree | Paths |
+|------|-----------|--------|-------|
+| `inputs/small.b2`   | 3 | 3 |    27 |
+| `inputs/medium.b2`  | 5 | 3 |   243 |
+| `inputs/large.b2`   | 6 | 3 |   729 |
+| `inputs/xlarge.b2`  | 7 | 3 |  2187 |
+| `inputs/huge.b2`    | 9 | 3 | 19683 |
+
+Each system is diagonal (`xi^3 - ci = 0`) with distinct prime constants, so solutions
+are known analytically and correctness is easy to verify (solution count = number of
+paths for these fully real systems).
+
+## Options
+
+```
+--bertini2 PATH    Path to bertini2 executable (default: ./build/core/bertini2)
+--input    FILE    Bertini input file to solve (required)
+--ranks    N ...   MPI rank counts to sweep (default: 1 2 4)
+--threads  N ...   OMP thread counts per rank (default: 1)
+--output   FILE    CSV output path (default: benchmark_results.csv)
+--timeout  SECS    Per-run timeout (default: 600)
+--repeats  N       Timed repeats per combo; records minimum (default: 1)
+--mpirun   CMD     mpirun command (default: mpirun)
+```
+
+## Cluster Submission (SLURM)
+
+Edit `submit.slurm.sh` (paths, module loads, rank/thread sweep) and submit:
+
+```bash
+sbatch benchmark/submit.slurm.sh
+```
+
+Results are written to `benchmark/results_<JOBID>.csv`.
+
+## Notes
+
+- `--bind-to none` is passed to `mpirun` automatically so that threaded workers
+  can use all cores on a node without affinity conflicts.
+- Each (ranks, threads) combo runs in its own temp directory to avoid file conflicts.
+- The serial baseline (ranks=1, threads=1) is always run first; speedup is computed
+  relative to that measurement.
+- `OMP_NUM_THREADS` is set per-run by the script; do not set it externally when sweeping.

benchmark/baseline_large.csv

@@ -0,0 +1,2 @@
+ranks,threads,total_workers,wall_time_s,solutions_found,speedup_vs_serial
+1,1,1,66.8036,7,1.0000

benchmark/baseline_large_seeded.csv

@@ -0,0 +1,2 @@
+ranks,threads,total_workers,wall_time_s,solutions_found,speedup_vs_serial
+1,1,1,143.9177,7,1.0000

benchmark/baseline_medium.csv

@@ -0,0 +1,2 @@
+ranks,threads,total_workers,wall_time_s,solutions_found,speedup_vs_serial
+1,1,1,42.7632,6,1.0000

benchmark/baseline_medium_seeded.csv

@@ -0,0 +1,2 @@
+ranks,threads,total_workers,wall_time_s,solutions_found,speedup_vs_serial
+1,1,1,44.6928,6,1.0000

benchmark/baseline_small.csv

@@ -0,0 +1,2 @@
+ranks,threads,total_workers,wall_time_s,solutions_found,speedup_vs_serial
+1,1,1,3.7077,4,1.0000

benchmark/baseline_small_seeded.csv

@@ -0,0 +1,2 @@
+ranks,threads,total_workers,wall_time_s,solutions_found,speedup_vs_serial
+1,1,1,3.3135,4,1.0000

benchmark/inputs/huge.b2

@@ -0,0 +1,22 @@
+CONFIG
+
+tracktype: 0;
+
+END;
+
+INPUT
+
+variable_group x1, x2, x3, x4, x5, x6, x7, x8, x9;
+function f1, f2, f3, f4, f5, f6, f7, f8, f9;
+
+f1 = x1^3 - 2;
+f2 = x2^3 - 3;
+f3 = x3^3 - 5;
+f4 = x4^3 - 7;
+f5 = x5^3 - 11;
+f6 = x6^3 - 13;
+f7 = x7^3 - 17;
+f8 = x8^3 - 19;
+f9 = x9^3 - 23;
+
+END;

benchmark/inputs/huge_seeded.b2

@@ -0,0 +1,24 @@
+CONFIG
+
+tracktype: 0;
+
+randomseed: 314159;
+
+END;
+
+INPUT
+
+variable_group x1, x2, x3, x4, x5, x6, x7, x8, x9;
+function f1, f2, f3, f4, f5, f6, f7, f8, f9;
+
+f1 = x1^3 - 2;
+f2 = x2^3 - 3;
+f3 = x3^3 - 5;
+f4 = x4^3 - 7;
+f5 = x5^3 - 11;
+f6 = x6^3 - 13;
+f7 = x7^3 - 17;
+f8 = x8^3 - 19;
+f9 = x9^3 - 23;
+
+END;