A seeded solve gives the same bits on any number of threads or ranks; seed 0 is a seed; BERTINI_NUM_THREADS

[ofloveandhate]

A seeded solve now gives the same bits whatever runs it: one thread, many threads, or MPI ranks with any number of threads each. It also renames the thread-count variable to BERTINI_NUM_THREADS.

Fixes #378.
Fixes #475.

A path does not depend on the paths before it (#378, ADR-0071)

Each path already drew its random numbers from its own deterministic stream. But a tracker and an endgame are reused path after path, and five pieces of state flowed from one path into the next. With a thread pool, the scheduler decides which paths a thread runs before a given path, so a seeded threaded solve differed from run to run in step counts, precision and the last digits of its endpoints. A serial solve depended on path order: running cyclic-5's 120 paths in reverse changed 45 of them.

The five sources:

1. An adaptive track built its first step at the precision the previous track ended in, and kept that precision.
2. A drop from multiple precision to double re-precisioned only the end time. The step size, the time and its increment stayed at the old precision.
3. The condition-number probe was rounded in place at every precision change, so a drop destroyed digits a later rise could not restore.
4. The endgame's c/k probe was drawn the first time an endgame object needed it and kept for the object's life, or redrawn mid-path after an escalation.
5. An endgame run in double left an earlier run's multiprecision times in place, so final_time_used reported another path's last time.

Each is fixed where it lives, not by giving every path a fresh tracker, which would leave the trap for anyone reusing a tracker or an endgame by hand:

• A track builds its first step from its own start precision.
• Every conversion re-precisions all internals.
• Random directions are stored as drawn, and every working copy is derived from that copy.
• The c/k probe is drawn at the start of every run, after the per-path reseed.
• Both lanes of an adaptive endgame are cleared when a run begins.

Precision observers and the per-path precision record (ADR-0071)

The same investigation turned up a second kind of stale state: a record kept by an observer outliving the span it describes. The solver fills three fields of each path's metadata from precision observers attached to the tracker: precision_changed, time_of_first_prec_increase and max_precision_used. Those observers had three defects.

1. A per-track record read as a per-path one. The solver read MinMaxPrecisionRecorder, which started afresh at every TrackingStarted. The endgame tracks a path in many calls to TrackPath, so a precision raised in an earlier endgame sub-track and lowered before the last went unreported. On seeded cyclic-5, power-series path 59 reported 30 digits after tracking at 40, and six Cauchy paths were under-reported.
2. Recording from the wrong starting point. Both recorders started afresh at TrackingStarted, which a track sends only after its start point has been refined. So they missed any precision increase the refinement needed. A track whose refinement failed, such as one from a singular start point, never sends TrackingStarted at all, and was reported with the previous track's values.
3. Unsubscribing. FirstPrecisionRecorder unsubscribed at its first increase. Attached once to a tracker, it reported that track forever after. Its members were also left uninitialized until its first event.

The fixes, each where the record lives:

• FirstPrecisionRecorder and MinMaxPrecisionRecorder record one track each. They start afresh at the track's Initializing event, which comes before the start-point refinement, and they never unsubscribe. Attached once, they report every track, including one that fails to initialize. MinMaxPrecisionRecorder now counts both ends of every precision change, so a track's starting precision is included.
• A new PathPrecisionRecorder records a whole path across every call to TrackPath. It starts afresh only when its owner calls Reset. The solver resets and attaches it when a path begins, reads it after each stage, and detaches it when the path ends. All three metadata fields now come from it.

The other recorded field this PR corrects is final_time_used (item 5 above). It came from the endgame's stale times, not from an observer.

Seed 0 is a seed (#475, ADR-0072)

set_random_seed(0) meant "draw a seed from entropy", so a script that set seed 0 to make a run reproducible got a different run each time. 0 is now an ordinary seed, as in numpy and Python's random. set_random_seed() or set_random_seed(None) draws a seed from entropy and returns it. A classic input file keeps Bertini 1's meaning: randomseed: 0, its default, still draws from entropy in the command-line program. Seed 0 is therefore the one value that does not carry between a Python script and a classic input file.

BERTINI_NUM_THREADS (ADR-0070)

b2 took its thread count from OMP_NUM_THREADS, although it uses no OpenMP. numpy's OpenBLAS reads that variable too, so pinning b2 to one thread pinned numpy, and tuning numpy changed b2. b2 now reads BERTINI_NUM_THREADS and ignores OMP_NUM_THREADS. The order is the variable if set, then num_threads, then every CPU the process may run on, which is OpenMP's default. MPI ranks follow the same rule and no longer default to one thread. Several ranks on one machine should set the variable, and the CLI help and the scaling tutorial say so.

Tests

Each regression test was run against the code without its fix and fails there.

• Bit identity. A seeded cyclic-5 solve matches serial path by path at 1, 2, 3 and 8 threads, for both endgames: every endpoint, and every metadata field but the wall-clock time.
• Hand-driven reuse. A reused tracker matches a fresh one bit for bit, for every pairing of previous and next start precision, ending in double and in multiple precision. A reused endgame matches a fresh one, for every flavor and tracker type.
• Precision observers. A recorder attached once reports a failed singular-start track and then a regular one, each as itself. A reused tracker's recorders report a failed track exactly as a fresh tracker's do. Each path's max_precision_used equals the highest precision its tracker reported in any event, for both endgames. A Python test checks max_precision_used against the precision at every step, as recorded by SolutionPathCollector.
• Seeds. Seed 0 reproduces a run, entropy seeds are reported and reproduce it, and classic randomseed: 0 still draws from entropy.
• Python. Counterparts of the above, plus tests that BERTINI_NUM_THREADS decides the thread count and that OMP_NUM_THREADS does not reach b2. Under mpirun at 3 and 5 ranks, a distributed solve matches a serial one path by path.
• CI. The MPI smoke test used to compare solution counts. With a fixed seed, it now requires main_data to be byte-identical across a serial run, a threaded run, and mpirun -n 2 with one and two threads per worker.

For users

• Small numeric changes. Results differ from 4.0.0.dev1 in the last bits and, occasionally, in step counts. The old results depended on path order, so none of them is a reference.
• The thread variable. Scripts and job files that set OMP_NUM_THREADS for b2 should set BERTINI_NUM_THREADS.
• Precision metadata. max_precision_used, precision_changed and time_of_first_prec_increase can differ from 4.0.0.dev1, where they were wrong. Records written by earlier builds keep the values those builds computed.
• Hand-attached observers. C++ code that attaches FirstPrecisionRecorder or MinMaxPrecisionRecorder to a tracker now gets a record of the most recent track, every time. To record a whole path, use PathPrecisionRecorder.

🤖 Generated with Claude Code

[ofloveandhate]

i was all like "time to do the work, just before 4.0, to get these threaded cellular decompositions to decompose the same as the serial ones". (i'm doing work in a yet-private repo on a re-implementation of bertini_real). and then it uncovered a series of bugs that demanded solving. so this fixes two issues in the core. and brings some interface consistency with numpy (0 just a seed, it doesn't mean "no seed" or "use entropy"). and, along the way, further uncovered some incorrect metadata was being computed -- because i had not correctly reset the observers at the beginning of tracking a path. like, seriously, i am loving using AI coding tools. i steer, i guide, and i use my deep insight. claude starts trying to go off and do something, and i'm like, no buddy, you stay with me. here. this is the place, this is the bug. and i fix it.

this result permits me to do a 4.0 release (i'm doing semantic versioning, and this interface will break interface -- so this is the right place to do the rename of the env var that controls threading, separating it from the openmp variable i had used early on because it was convenient).

yes, i used an ai tool. i have faith this code is correct. i steered the whole time, and i personally intervened and made decisions the whole time. i am proud of this work.