78 lines
4.3 KiB
Markdown
78 lines
4.3 KiB
Markdown
# Root Finding by Similarity and Analogy — code, data and history
|
||
|
||
Code, data and full development history for the paper *Root Finding by Similarity and Analogy: A
|
||
Bracketing Method with a Data-Selected Decision Layer* (V. Sitnikov, 2026; manuscript, included in
|
||
`source/article/`). Everything behind the paper is here, under the Apache License 2.0: the method's
|
||
reference implementation, a compiled library of the proposed method A′, the benchmark harness, the
|
||
problem corpora, every results file, the records written before each run, the manuscript itself, and
|
||
the full development history.
|
||
|
||
## Contents
|
||
|
||
| path | what |
|
||
|---|---|
|
||
| `source/` | the repository at the commit the paper was built from: `simroot/` (the reference implementation of the base rule, A′ and every variant the paper measures), `lib/` (the source of the compiled library `simbracket`), the sweep scripts, corpora (`corpus_*.py`), diagnoses, the verifier `verify_article.py`, the tests, every results file (`sweep_*.json`, `results_*.txt`), the records written before the runs (`PREREG_*.md`, `POSTHOC_*.md`), the findings (`FINDINGS_*.md`) and the paper (`article/`) |
|
||
| `sim-numerics.bundle` | the full git history of that branch (`git clone sim-numerics.bundle`); the commits cited in the paper's Appendix D are in it |
|
||
| `wheels/` | `simbracket`, A′ as a compiled library (Python ≥ 3.10; Linux and Windows builds) |
|
||
| `requirements.txt`, `reproduce.sh` | the Python packages used, and the one-command reproduction |
|
||
| `SHA256SUMS` | checksums of every file in the archive |
|
||
|
||
## Requirements
|
||
|
||
**Linux x86_64 for reproducing the numbers.** The paper's numbers come from one Linux machine (Ubuntu
|
||
24.04, glibc 2.39, Python 3.12.3). The test functions call the platform's `libm`, whose last digit
|
||
differs between platforms; on Windows, TOMS 748 needs 2635 evaluations on the Alefeld–Potra–Shi set
|
||
instead of 2636, and two of the paper's fresh recomputations move by a few evaluations. Using the
|
||
method needs no particular platform.
|
||
|
||
## Reproduce
|
||
|
||
```bash
|
||
./reproduce.sh
|
||
```
|
||
|
||
creates a virtual environment, installs `requirements.txt` and the `simbracket` wheel, and in `source/`
|
||
runs
|
||
|
||
1. `python -u verify_article.py` — recomputes or re-reads every number stated in the paper (548) and
|
||
compares it with the value printed there; it ends with *every number stated in the paper matches the
|
||
sweep data*;
|
||
2. `python -m pytest tests/test_simbracket_equivalence.py` — the compiled library equals the reference
|
||
implementation bit for bit, point and evaluation count, on all 868 problems of the six corpora.
|
||
|
||
Any table can be recomputed from scratch with its sweep script; each script's docstring names the table
|
||
it produces (for example `python -u rescore_uniform.py` for the protocol tables, `python -u
|
||
sweep_fourth.py --fourth` for corpus 4, `python -u sweep_controls.py` and `python -u sweep_estimated.py`
|
||
for the controls). The full test suite is `python -m pytest tests`.
|
||
|
||
## Use A′ on your own problem
|
||
|
||
```python
|
||
from simbracket import find_root, evaluation_bound
|
||
|
||
x, nfev, converged = find_root(f, a, b, xtol=1e-12, maxfev=200)
|
||
# f(a) and f(b) of opposite signs; stops when the bracket is no wider than xtol or f(x) == 0;
|
||
# never more than evaluation_bound(a, b, xtol) = 2*ceil(log2(|b-a|/xtol)) + 3 evaluations
|
||
```
|
||
|
||
or, from source, `simroot.pure.pure_root` with the configuration named `APRIME` in `sweep_full.py`.
|
||
|
||
## The records and their order
|
||
|
||
`PREREG_*.md` were written, and committed, before the runs they describe; `POSTHOC_*.md` after, as
|
||
marked. Appendix D of the paper lists each record with its commit and the commit of its results;
|
||
`check_prereg_order.py` recomputes that table from the history in `sim-numerics.bundle`. The order is
|
||
attested by the author's git history, not by an external registry. Before publication the history was
|
||
rewritten to remove infrastructure details (a server address) and working notes not meant for
|
||
publication (a few files deleted; file names, comments and a few words in three advance records made
|
||
neutral, cited commit hashes mapped to the new commits; no rule, criterion or number of a record
|
||
changed); the commit hashes cited in the paper are those of the rewritten history in this archive.
|
||
|
||
## Citing
|
||
|
||
The archive: https://doi.org/10.5281/zenodo.22894337 (DOI 10.5281/zenodo.22894337). Cite this archive by its DOI.
|
||
|
||
## Licence
|
||
|
||
Apache License 2.0 (`LICENSE`); copyright Valeri Sitnikov (`NOTICE`).
|