Add Solver

Add a Basin Solver

Implement one public solver per invocation and carry it through code, tests, documentation, and catalogue integration. Preserve the solver and variant the user requested. If no solver has been selected and the user has not delegated the choice, identify the missing choice before implementation; recommendations should be based on a concrete gap in Basin's current catalogue.

Establish the Algorithm

Read AGENTS.md, the relevant sections of CONTRIBUTING.md, crates/basin/src/core/solver.rs, and the closest existing solver before designing the change. Inspect the state and math traits the algorithm appears to need rather than assuming a new abstraction is necessary.

Research the algorithm from authoritative sources before writing production code:

• Find at least one credible primary source: the original paper, an archival algorithm description, an official technical report, or an authoritative monograph treatment. Prefer both a paper and reference code when they exist.
• Prefer author-maintained code, an ACM TOMS implementation, or a well-maintained research library as the executable reference. Record its exact version or commit and its license.
• Lock down the named variant, equations, update ordering, defaults, convergence test, constraint model, and documented exceptional cases. Resolve material disagreements between paper, pseudocode, and code before implementation.
• Use reference code as an oracle only when it implements the requested variant completely and its outputs are legally and practically usable for comparison. Treat incomplete, materially different, or untrusted code as corroborating evidence, not an oracle. Do not copy or vendor code with an unclear or incompatible license.
• When no usable executable oracle exists, implement independently from the primary equations and state transitions. Replace trajectory parity with analytical or paper-backed invariants and, where applicable, exhaustive decision-table tests. Record why parity was omitted.
• Put downloaded papers and external source trees under the gitignored references/ directory. Commit only durable, license-compatible artifacts needed by tests, such as compact output fixtures and their regeneration driver or instructions.

If neither a credible algorithm source nor a trustworthy executable reference can be found, explain the evidence gap before presenting the implementation as research-based. Cite the sources that actually guided the code—do not borrow a nearby citation merely because it is conventional.

Before coding, settle these design facts: public type and constructor, required problem traits, constraint support, state shape, minimum math capabilities, claimed backends, scalar genericity, solver-specific controls, and the test oracle. Raise a breaking public-API requirement rather than quietly changing an existing signature or trait contract.

Design Tests First

Start with focused tests that fail for the missing solver. Exercise the public Executor path, not only private kernels. Choose tests in proportion to the algorithm, including:

• an analytic benchmark with a known solution or other paper-backed invariant;
• deterministic reference or trajectory parity when usable reference code exists—compare only invariants the two implementations should genuinely share;
• initialization and one-step invariants, including consistency among the current parameter, cost, derivative data, and evaluation counts;
• constraints, degeneracies, invalid configuration, and non-finite behavior relevant to the algorithm;
• deterministic seeds and reproducible trajectories for stochastic methods;
• all four dense backends (Vec, nalgebra, ndarray, and faer) for vector-based solvers, with both f32 and f64, plus every claimed sparse backend, using scale-appropriate approximate comparisons; and
• f32 round-trip coverage when the new public surface stores or exposes a scalar-valued state.

Scalar algorithms do not require a linear-algebra backend.

For a solver that wraps or orchestrates an existing solver, concentrate new tests on the outer algorithm: state transfer, restart or phase decisions, evaluation accounting, and end-to-end behavior. Do not duplicate unchanged inner-solver mechanics, but retain at least one public-path test proving that the composition works.

Keep parity fixtures small and document their provenance, locked inputs, comparison tolerances, and regeneration procedure in crates/basin/tests/fixtures/README.md. Do not demand floating-point-identical trajectories when algebraic ordering or a legitimate variant differs.