soar-lite 0.1.0__tar.gz

soar_lite-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+/site/
+
+# Local scratch / working notes (never committed)
+.scratch/
+
+# Virtual environments. `.venv*/` also covers a side env built on another
+# backend (e.g. `.venv-cuda/`). uv writes its own `*` .gitignore inside a venv,
+# but that file is disposable, so the top-level rule is what we rely on.
+.venv*/
+venv/
+
+# Tooling caches
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+.pyright/
+.mypy/
+
+# Editors / OS
+.DS_Store
+*.swp
+
+# Byte-compiled / native
+*.so
+
+# Jupyter Notebooks. The notebook is source; the checkpoints beside it are not.
+.ipynb_checkpoints/
+
+# Experiment run artifacts (regenerated, not source)
+experiments/results/
+experiments/figures/

soar_lite-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+User-visible changes, newest first. This file starts at the first public
+release: what happened before it is in `git log`, and the internal record
+(a rename sweep, a default flipped three times before anyone could have
+depended on it) is not a thing a user upgrading between versions needs to read.
+
+## 0.1.0
+
+First public release. `README.md` and the site describe what this version is, so
+this entry is the inventory rather than a diff against something earlier.
+
+- `n_path_schedule` — the whole algorithm behind one call: `n_paths` descents
+  advance in lockstep under one budget, each re-drawn from the global model once
+  its own stopping test stalls it (`restart_stalled`, on by default), and the
+  report names the best point evaluated as `x`/`f` beside the flock the run
+  ended on.
+- `DiagonalPreconditioner` — a per-coordinate inverse-curvature scale estimated
+  from successive gradients, plus a momentum `mu` (0 by default). No matrix and
+  no learning rate to tune, and once the first secant pair exists the step is
+  invariant to rescaling of the objective.
+- Two plugin seams, `LocalSolver` and `GlobalModel` — `SampleGlobalModel` draws
+  restarts from the domain; `BLRGlobalModel` accumulates the run's evidence into
+  a Bayesian surrogate whose acquisition descent is injected.
+- `pointwise` and a batched `eval_f_g` — value and gradient in one call, with an
+  optional feasibility mask, so one engine serves a scalar objective, a batched
+  one, or a penalized transform of a constrained problem.
+
+Below `1.0.0` a breaking change bumps the minor version: `0.2.0` may not run code
+written for `0.1.0`, and only `1.0.0` starts the compatibility promise.

soar_lite-0.1.0/CITATION.cff

@@ -0,0 +1,25 @@
+cff-version: 1.2.0
+message: If soar-lite does useful work in something you publish, cite it with this entry.
+title: soar-lite
+abstract: >-
+  A JAX optimizer for objectives that are differentiable but expensive to
+  evaluate. A flock of n paths descends in parallel with a unit-invariant
+  diagonal secant preconditioner; a stalled path restarts from a Bayesian
+  linear surrogate fit on projected coordinates; and the report keeps every
+  served point, so an outside budget is spent against counted work.
+authors:
+  - family-names: Tree
+    given-names: Watson
+    email: watson.tree@outlook.com
+version: 0.1.0
+license: MIT
+type: software
+repository-code: https://github.com/watson-tree/soar_lite
+url: https://watson-tree.github.io/soar_lite/
+keywords:
+  - optimization
+  - first-order
+  - quasi-newton
+  - multi-start
+  - nonconvex
+  - jax

soar_lite-0.1.0/CONTEXT.md

@@ -0,0 +1,325 @@
+# soar-lite
+
+A first-order multi-path optimizer: value and gradient come back together from
+the caller; `n_paths` independent descent paths advance in lockstep under one shared
+budget, each re-drawn from a global model once its own stopping test stalls it
+(the `restart_stalled` knob, on by default).
+
+## Glossary
+
+### Engine
+
+**path**:
+One independent descent: a current point plus that descent's own solver
+state. The engine runs `n_paths` of them in lockstep. A restart replaces its
+current point with a fresh draw, so the points one path holds across a run are
+continuous in identity, not in space — which is why `best`, the reported answer,
+need not be a point any path still holds.
+_Avoid_: chain, trajectory, thread, particle
+
+**n_paths**:
+The engine's width — the number of paths the engine drives together.
+_Avoid_: population size, swarm size
+
+**flock**:
+The paths' current points as one `(n_paths, d)` array: exactly one point per path,
+so a flock is the run's state at one moment, not the set of paths. Every path
+keeps its row whether or not it holds a usable point (`flock_f` is `nan` there),
+so a flock always has `n_paths` of them. A *batch* is a set of points too and is
+deliberately a different one: it is the work a single pass serves — a step's
+trials, or the settle set of redraw starts plus winners — so it holds no point
+for an idle path and is not the state. Iteration 0 places the flock from `x0`
+where one was handed in, and otherwise from the global model; the engine's copy
+is the flock as the run ended.
+_Avoid_: the set of paths, population, ensemble, all the paths
+
+**iteration**:
+One pass of the engine's main loop, counted in `n_iters`. Per iteration the engine
+splits the paths into a redraw set (no point yet, or stalled with
+`restart_stalled` on) and a cohort that steps: a path either redraws or steps
+this iteration, never both. The parallel wall-clock unit; an iteration serves
+one or more batches (the steppers' trials as the method reads them, and the one
+settle batch that buys whatever the iteration kept still owes). A flock in
+which every path is parked — nothing left to do, since restarts are off — ends
+the run on `all_stalled` instead of entering a batchless iteration.
+Iteration 0 is the flock's placement: an empty `x` redraws unconditionally,
+so starting the flock is the same operation as any later redraw. `n_iters`
+counts finished iterations only — one cut short by a refused batch is not
+counted, so a refused placement reports `n_iters = 0` and a refused first
+step `n_iters = 1`.
+_Avoid_: round (retired), epoch, iterations (as a name for the count)
+
+**redraw set**:
+The paths an iteration gives a fresh start: every path holding no point — always,
+whatever `restart_stalled` says, which is how iteration 0 places the flock and
+how a refused start eventually gets replaced — plus every stalled path when the
+knob is on. Its size is what the engine asks the model for, one start per path,
+so iteration 0 is the whole flock and a later one is only the paths that
+stalled. Iteration 0 with an `x0` is the one redraw set whose starts the caller
+supplied: `x0` is consumed there and no model is asked.
+_Avoid_: restart list, restart batch
+
+**cohort**:
+The paths that step this iteration: neither in the redraw set nor stalled. One
+`local_solver.propose` call is handed exactly this set, so a method never sees a
+path the engine has stopped — not even a step that would answer `None`. It is
+not the flock, and not just the redraw set's complement: a path parked by
+`restart_stalled=False` belongs to neither, and sits out while the rest moves.
+_Avoid_: the flock, active paths
+
+**best**:
+The run's running best, a single `f`/`x`: the best *feasible* point — the
+run's reported answer, and what `NPathResult` calls `f`/`x`. The engine is the
+sole owner. It starts at `nan` and stays there while no finite feasible value
+has arrived, so `nan` means "no answer" and `inf` is never a sentinel - it is
+left to mean a value an objective actually took. A *feasible* `-inf` is not
+weighed but taken: the objective has no floor there, so it becomes `f`/`x` and
+ends the run with `status` `unbounded`; a `nan`, a `+inf` or an infeasible
+`-inf` changes nothing.
+_Avoid_: incumbent (retired), best-so-far, current optimum
+
+**stall / stalled**:
+A path that moved nowhere this iteration — it neither redrew nor committed a
+step: its local method answered no winner (`None` — its own stopping test
+fired), or the point it was given was refused as not usable, whether the winner
+the method named or the start the model drew: a non-finite value or gradient in
+either.
+Stalled is not dead: unless the run turned `restart_stalled` off, the path is
+re-drawn by the global model on the next iteration; with the knob off it stays
+parked — still counted, still readable for `best` — but never moved again. A
+turn of the loop with every path parked that way is `all_stalled` — reachable
+only when `restart_stalled` is off, since with it on a stalled path is re-drawn
+rather than parked: no path can move and none is owed a start, so the run stops.
+A path with no point at all is a redraw that ignores `restart_stalled`: the
+machine's own initial state is not a stall. A start refused while the path held
+nothing sets the bit anyway, but the no-point rule is asked first, so the flag
+never sees that case.
+_Avoid_: paused, idle, dead
+
+**domain** (type `Domain`):
+The object that carries everything the engine knows about the search space: the
+per-dimension `(lb, ub)` sides (either may be unbounded), the per-dimension
+`scale` the draws use, and the injected per-dimension samplers. It is the sole
+authority on the dimension `d`, and the box every point the run serves must lie
+inside: the engine checks each point a seam hands over and refuses one that
+misses, instead of moving it onto a wall. Bounds are data, never a unit-cube
+assumption.
+_Avoid_: box (the box is only the bounded-sides part of the domain)
+
+**sampler**:
+The injected per-dimension callable that draws starts; the default is uniform on
+a bounded side, `N(0, scale²)` on a free one, and that same normal truncated to
+the declared side on a half-bounded one. The *domain* remains the sole
+authority on `d`.
+_Avoid_: initializer, prior (as a name for the *callable*)
+
+### Evaluation
+
+**batch**:
+The `(M, d)` points served by one pass — fused (`eval_f_g`) or value-only
+(`eval_f`). The engine composes each batch from either one trial round — one
+point per path the round names — or the settle set: the redraw starts and
+the winners still owing a half.
+_Avoid_: group, lot, chunk
+
+**point**:
+One candidate — one row of a batch. The four counters (below) count the billed
+ones. Once settled it is a `PathPoint`: the `x`/`f`/`g` triple a path commits,
+assembled only once both halves exist (see *settle*), so a point that arrived
+fused travels on as one object rather than three arrays.
+_Avoid_: query, sample, evaluation (retired)
+
+**settle**:
+The iteration's one fused batch that buys whatever a kept point still owes, and
+the only place a produced `Point` becomes a settled `PathPoint`. A redraw start
+and a winner the method never read owe both halves and take f and g from this
+one pass; a winner the method read through `serve_trials` owes only its gradient
+when the `eval_f` seam served it value-only — with no such seam the same call
+served the fused pair, so the winner already carries both and passes through as
+it stands, never served twice. Everything is bought before anything is placed,
+so nothing commits before it is settled.
+_Avoid_: commit batch, gradient round
+
+**four counters** (`n_f_g_points` / `n_f_g_batches` / `n_f_points` / `n_f_batches`, all four in one `Work`):
+The run's reported work, on two axes and two seams. `points` counts billed
+points (a batch bills its actual size), `batches` counts billed batches (a batch
+bills 1); `f_g` is the fused value+gradient pair, `f` the value-only pair. All
+four are counted — "billed" means "actually served out" — and none of them
+decides the stop. Points and batches are different numbers on different axes
+and must never share a chart, and the `f` pair must never be read as the `f_g`
+pair. They replace scipy's single `nfev`. The four live in one frozen `Work`,
+reached as `result.work` and read flat on the result as well; that object is
+what the budget gate is handed — as it stands at the loop head, and as a
+pending batch would leave it at a serve site — so a gate reads counts on their
+way into the report and cannot write them.
+_Avoid_: nfev (retired)
+
+**objective**:
+The scalar function being minimized; its per-point values are the f values the
+engine records. Distinct from the *cost model* (the four counters), which
+counts work.
+_Avoid_: loss, cost, fitness
+
+**eval_f_g**:
+The caller's per-batch callable (type `EvalFG`): points in,
+`(f, gradient, feas?)` out. The seam to the objective's values and
+gradients; the engine is blind to it otherwise.
+_Avoid_: oracle, evaluator, black box
+
+**eval_f**:
+The optional value-only sibling (type `EvalF`): points in, `(f, feas?)` out,
+no gradient.
+It exists so a step's trials are read by value alone and only the winner's
+gradient is bought once at *settle*, instead of once per trial. Without it
+every trial is itself a fused batch.
+_Avoid_: value oracle, cheap evaluator
+
+**feasibility mask**:
+The optional per-point boolean saying which served points may count toward the
+reported best (`f`/`x`). It is
+read as 0/1 and nothing else: only `0` (or `False`) marks a point infeasible, so
+a mask holding anything else — a signed constraint margin, whose violated points
+are all negative, or a `nan` — is refused with a `ValueError` instead of being
+read as truthiness, where every one of those flags would have counted as
+feasible and quietly promoted a point into the answer.
+_Avoid_: validity mask
+
+### Local method
+
+**step**:
+One move along a single path: propose → (trial)× → a winner, or none (`None`).
+Each path takes at most one move per iteration — a step, or a redraw start; a
+step consumes zero or more trials. The method lands it through `step(points)`: the
+engine hands back the settled `PathPoint` `(x, f, g)` the path now stands at, so
+the method moves the matching state forward. The **method** named the winner in
+`propose`; the engine bought its owed halves in *settle* and commits here, so
+`step` is the only commit and the only place a method may advance its model — a
+secant pair is a move that was taken, and only this callback is told one was. It
+is never called for a winner the engine refused (not usable) or for a path whose
+stopping test held.
+_Avoid_: update, move; accept, commit (as names for this handoff)
+
+**round**:
+One `serve_trials` call: one point per path it names, served and reported as
+one batch. It is the unit of both price and memory — a method that enumerates
+reads its candidates as successive rounds, so however far it looks it holds one
+point per path at a time and pays one batch per look. The method sets how many
+rounds a step reads; the engine sets the width of each.
+_Avoid_: trial (that is one point inside a round)
+
+**trial**:
+One served proposal within a step — this path's point on one round the method
+reads through `serve_trials`. What a trial carries is the seam's business: with
+`eval_f` connected it is the coords and value alone — the winner's gradient is
+bought later (see *settle*), so a method that needs a gradient to rule needs the
+fused seam — and without `eval_f` the same round serves the fused pair, gradient
+included. There is no engine-side cap: the method's own stopping test (or its
+own trial budget) ends the enumeration, one batch per round. A step that reads no
+trial — a single full proposal, like the shipped method's — serves none at all.
+_Avoid_: line-search round (retired)
+
+**secant pair**:
+The `(Δx, Δg)` between two consecutive points of one path — the only curvature
+evidence the local method reads.
+_Avoid_: gradient difference, step pair
+
+**diagonal preconditioner**:
+The local method itself: a per-coordinate inverse-curvature estimate read off
+the secant pair, applied as `-precon ⊙ m` where `m` is the momentum (a blend of
+the gradient and its history; the bare gradient `g` at `mu = 0`). No matrix, no
+linear solve, no scalar learning rate.
+_Avoid_: diagonal Newton (it is a biased `1/H` estimate, not Newton)
+
+**floor (λ)**:
+The guard that keeps a coordinate's denominator positive when the secant
+vanishes (a flat but unconverged coordinate).
+_Avoid_: epsilon, addend, regularizer
+
+**warmup**:
+A path's first step, before any secant pair exists: one full proposal along
+`-g₀` at `alpha0`, committed as proposed. It carries no value guard of its own —
+the phase enters only the direction; like the steady step, it is read by no
+value and compared against no start.
+_Avoid_: initialization step
+
+### Restart
+
+**global model** (type `GlobalModel`):
+The engine's second seam, owner of *where* a redrawn path starts. It observes
+every served batch as a mapping from path to the point served there
+(`observe(served)`, one entry per path, so a model that only wants stacked rows
+stacks them itself) and answers `propose(paths, domain)`
+with one fresh start per path it was asked about, keyed by that path. `None` for
+a path is the model declining it — its own stopping rule, as `None` from a
+method's `propose` is the method's — and that path starts nowhere this
+iteration. The default `SampleGlobalModel` fits nothing: it draws starts
+from the `domain`. An `x0` the caller hands the entry states the first flock
+directly and the model is not asked; with `x0=None` it draws that flock too, as
+iteration 0's one ask. `BLRGlobalModel`
+fits a Bayesian linear posterior and proposes the local minimum of `-log EI` —
+EI there is an acquisition function deciding *where is worth trying*, not a
+restart decision.
+_Avoid_: restart rule, sampler (the sampler is a per-dimension draw inside the
+domain)
+
+**inner minimizer** (`minimize`, type `MinimizeFn`):
+The global model's own seam, one level further in, owning *how* to descend the
+acquisition the model builds (`-log EI` for `BLRGlobalModel`). The model holds
+the acquisition and never searches it itself: `propose` hands the acquisition,
+the ask's `domain`, the paths and a fresh subkey to `minimize`, and carries its
+answer out as one start per path, `None` for a path it could not place. The
+shipped default is `descent_minimize`, the engine run restart-free at the
+cohort's width, so the acquisition is descended by the method it will later
+drive; a caller that needs an inner knob the default does not expose — e.g. a
+`time_limit`, another local solver, `budget_check`, restarts inside — passes its
+own `MinimizeFn` instead.
+_Avoid_: inner loop, acquisition optimizer (the model does not optimize the
+acquisition, it asks for one)
+
+**restart_stalled**:
+The run's one restart bit, deciding *whether* a stall restarts: on (the
+default), the stalled path is re-drawn by the global model next iteration; off,
+it stays parked, and a flock that is all parked is a deadlock — the run ends on
+`all_stalled` rather than idling to its horizon. It is orthogonal to *when* (the
+local method's own stopping test) and *where* (the global model). A run that
+never restarts needs no model of its own:
+`restart_stalled=False` with the default `SampleGlobalModel` is pure descent
+from the initial flock — the model runs once, drawing that flock, when `x0` is
+left `None`, and never again.
+_Avoid_: restart check, reset decision
+
+### Cost model
+
+**horizon (`max_iters`)**:
+The engine's own stop, counted in iterations: every completed iteration costs
+one, and iteration 0 places the flock. A deterministic bound, not a cost
+proxy — one iteration serves however many trial rounds the method's own search
+reads, plus the one settle batch that buys what it kept still owing, while a
+flock with nothing left to do stops the run
+(`all_stalled`) instead of billing a batchless iteration — so the four counters
+report what a run actually billed. At least one of `max_iters`/`time_limit` must
+be given, validated once at entry: `stop` asks the caller's gate like the other
+two, but a gate is the caller's own predicate and the engine cannot see it
+advance, so it cannot tell a gate that will close from one that never does — a
+run may not rest on that alone.
+_Avoid_: eval budget, cost estimate, time limit
+
+**deadline (`time_limit`)**:
+The same stop in seconds, for callers whose per-iteration cost is too uneven to
+count iterations. Checked before every batch (fused or value-only) and at the
+loop head, like the horizon, so the over-run is under one batch plus the one
+call in flight.
+_Avoid_: budget, timeout (that is a per-call concern)
+
+**budget gate** (`budget_check`):
+The caller's predicate, asked as one of the run's three stops at every loop head
+and again before each batch — serve the whole batch or nothing, never a partial
+prefix. It is handed the run's `Work`, the same four counts the result reports,
+so it gates on any axis it likes (points, batches, both seams together) without
+keeping a tally of its own. Before a batch it is handed the ledger that batch
+would leave, and a batch it refuses is never charged: a ceiling on points is one
+the run cannot cross, met from below by up to one batch width since a batch is
+served whole or not at all. At the loop head it is handed the ledger as it
+stands. It exists for a budget the engine cannot see (points, wall-clock,
+dollars). It is an extra gate, never a horizon.
+_Avoid_: stopping budget

soar_lite-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,110 @@
+# Contributing
+
+Welcome. Whether you have a question, a bug report or a change in mind, feel
+free to open an issue or a pull request — the sections below say what a change
+has to clear.
+
+## Proposing a change
+
+Open a pull request; GitHub runs the checks below on it. An issue is the right
+place for a question, a bug report, or an idea that has no implementation yet.
+
+## The checks a change has to pass
+
+```bash
+uv sync --all-groups          # jax, the dev tools, and the docs build
+uv run python -m pytest -q    # all tests in one go
+uv run --no-sync python -m tests.test_local_solver   # or one module at a time,
+uv run --no-sync python -m tests.test_global_model   # each module also runs
+uv run --no-sync python -m tests.test_scheduler      # as a plain script
+uv run --no-sync python -m tests.test_plugin_seam
+uv run ruff check && uv run ruff format --check && uv run pyright
+uv run mkdocs build --strict  # the docs site; a warning fails the build
+```
+
+The tests are assert-style self-checks: plain `assert` in `test_*` functions,
+pytest-collectable, no recorded golden numbers that would encode this
+repository's history. The four `python -m` modules above double as plain
+scripts; the rest, like everything under `experiments/tests`, are pytest-only
+and some use fixtures.
+
+## Commits and releases
+
+A commit subject names the kind of change before it describes it —
+`type(scope): what changed` — so `engine: settle only the points that still owe
+a gradient` becomes `fix(engine): settle only the points that still owe a
+gradient`. The types are `feat`, `fix`, `docs`, `test`, `refactor`, `perf`,
+`build`, `ci` and `chore`; the scope is optional — the module or the area the
+change lands in, added as `fix(engine): …` when the type alone does not say
+where. The rule starts with this release: earlier subjects are a mix of untyped
+`area: …` and occasional typed ones, and they stay as written, so read them as
+prose and type every subject you author from here on. The type earns its place
+because a user is the intended reader of `CHANGELOG.md`: `docs`, `test`, `ci`,
+`build` and `chore` never reach them, and that is the set a changelog generated
+from the log skips.
+
+Versions are SemVer read under its `0.x` rule: below `1.0.0`, any change a caller
+can notice — including one that breaks their code — bumps the minor version, and
+a patch is only for a fix that leaves the API as it was. `1.0.0` is where the
+compatibility promise starts.
+
+A release is four steps, in this order:
+
+1. Put the version in every place it is written: `version` in `pyproject.toml`,
+   `version` in `CITATION.cff`, the `## ` heading of a new top entry in
+   `CHANGELOG.md`, and a `uv lock` so `uv.lock` re-syncs it. The heading
+   carries no date; the tag is the date.
+2. Land it behind the checks above.
+3. Tag that commit on `main` `v<version>` and push the tag. Publishing is a
+   tag's business: nothing ships from a branch or a pull request, and the tag
+   must start with `v` — a tag like `0.1.0` matches no workflow and ships
+   nothing.
+4. Watch `publish.yml` run the tests, build and upload.
+
+PyPI never lets a version number be used twice — a published version can be
+yanked but not replaced, so an upload is the irreversible step. That is what the
+release-tag check in `publish.yml` stands in front of: a tag that does not name
+the version in `pyproject.toml` fails the build before anything is uploaded, and
+the tag can be deleted and pushed again.
+
+## Front doors
+
+`docs/site/index.md` is the canonical home page and the root `README.md` mirrors it
+for the sections both carry. A fact in the opening, or in any section either one
+carries from the other — `Install`, `Minimal run`, `What's inside`, `Citing` — is
+corrected in `docs/site/index.md` and copied across;
+`tests/test_front_doors_agree.py` fails if the two drift apart, or if a link in
+either one stops resolving. Link destinations are the sole exception — the site
+addresses its neighbours from inside `docs/`, the README from the root.
+
+## Names
+
+Names have fixed meanings: `CONTEXT.md` is the glossary, including the terms to
+avoid. Consult it before introducing one.
+
+## Records are append-only
+
+`DEPRECATED.md`, `experiments/DEPRECATED.md`, `experiments/RESULTS.md` and
+`CHANGELOG.md` are records, not living documents: nothing in them is deleted or
+rewritten to say something else, and a measured number is never re-edited — a
+new measurement or a superseded direction is a new entry, and the old one stays
+as written. `experiments/DESIGN.md` is the opposite: a current-state document,
+so a passage that is no longer true there is rewritten in place.
+
+## The benchmark suite
+
+`experiments/` holds the comparison harness behind the figures in the README. It
+is a sub-library, not a dependency: it imports `soar_lite`, nothing in the
+package or the docs imports it, and neither the wheel nor the sdist ships it. Run
+instructions are in `experiments/README.md`, what it measures and the rules it
+follows in `experiments/DESIGN.md`, and the numbers in `experiments/RESULTS.md`.
+
+## Open directions
+
+The two plugin seams (`LocalSolver`, `GlobalModel`) are the natural extension
+points. Writing your own is currently documented only as the contracts in
+`docs/site/reference/api.md` and the `Protocol`s in `soar_lite/engine/contracts.py`,
+not yet as a how-to guide. `BLRGlobalModel`'s acquisition has a known upgrade
+(see the `shortcut:` note in `soar_lite/global_model/blr.py`), and more global
+models or local solvers (e.g. line search) are welcome — `experiments/RESULTS.md`
+records where the tuned baselines stand.