Add SearchStrategy dispatch + in-place batched searchsorted!

[ChrisRackauckas-Claude]

Summary

Reformulates the existing sorted-search infrastructure as explicit strategy types and adds an in-place batched API.

Strategies (all <: SearchStrategy):

• LinearScan — walk ±1 from the hint
• BracketGallop — bracketstrictlymontonic + bounded binary search (the algorithm already backing searchsorted*correlated)
• BinaryBracket — plain searchsortedlast / searchsortedfirst, ignores any hint
• Auto — heuristically picks among the above based on hint validity and length(v)

Dispatched API:

Base.searchsortedlast(strategy, v, x[, hint]; order = Base.Order.Forward)
Base.searchsortedfirst(strategy, v, x[, hint]; order = Base.Order.Forward)

Batched in-place API:

searchsortedlast!(idx_out, v, queries; strategy = Auto(), order = ...)
searchsortedfirst!(idx_out, v, queries; strategy = Auto(), order = ...)

For sorted queries, walks v in lockstep using the previous result as the hint for the next — total cost O(length(v) + length(queries)) under BracketGallop. For unsorted queries, falls back to per-element search with no hint regardless of strategy.

Why

Downstream callers like SciML/DataInterpolations.jl (#525-#528) have been hand-rolling sorted-batch lockstep walks with a manually-maintained idx and a linear while idx < n - 1 && tt[i] > t[idx + 1]; idx += 1 advance. That works well when the queries are dense relative to the knots, but regresses badly (sometimes by 100-1000×) when there are very few queries on a long vector — the linear walk is O(n) regardless of how many queries actually live in that gap.

The right home for the "which strategy to use" heuristic is here, not duplicated in every consumer. With this PR, searchsortedlast! does the right thing in every regime, and downstream code becomes a one-line replacement.

Backwards compatibility

All existing exports keep working — they're now thin wrappers:

• searchsortedfirstcorrelated(v, x, guess) ≡ searchsortedfirst(BracketGallop(), v, x, guess)
• searchsortedlastcorrelated(v, x, guess) ≡ searchsortedlast(BracketGallop(), v, x, guess)
• searchsortedfirstvec(v, x) allocates and calls searchsortedfirst!
• searchsortedlastvec(v, x) allocates and calls searchsortedlast!

The Guesser path, Range fast paths, Reverse ordering, and searchsortedfirstexp are untouched.

Version bumped to 1.9.0 (new feature, additive).

Auto heuristic

condition	strategy
no hint, or hint ∉ `axes(v)`	`BinaryBracket`
hint in range, `length(v) ≤ 32`	`LinearScan`
hint in range, `length(v) > 32`	`BracketGallop`

The 32-element threshold is chosen because at that length the binary-search bracket-setup overhead is comparable to a worst-case linear walk, and below it LinearScan saves the bracket call entirely.

What is in this PR

• src/FindFirstFunctions.jl: strategy types + dispatched Base.searchsortedlast / Base.searchsortedfirst methods + searchsortedlast! / searchsortedfirst! + reformulated existing wrappers.
• test/runtests.jl: two new safetestsets covering strategy equivalence across n ∈ {0, 1, 2, 8, 33, 257}, every hint position, Reverse order, the batched API on sorted/unsorted/empty inputs, DimensionMismatch, and sparse queries on a long vector to exercise the gallop hint path.
• Project.toml: bump to 1.9.0.

Test plan

• CI passes
• Pkg.test() locally: 26814 / 26814 passing on Julia 1.10 (was 25481 before — +1333 new assertions across the two new testsets)
• Runic-formatted

Please ignore until reviewed by @ChrisRackauckas. The follow-up plan is small PRs to DataInterpolations.jl swapping the hand-rolled walks in #525-#528's merged Akima and the in-flight #527/#528 for searchsortedlast! calls.

🤖 Generated with Claude Code

[ChrisRackauckas-Claude]

Pushed a second commit (163465e) that:

1. Adds two more strategies to round out coverage:

   • ExpFromLeft — galloping forward from a left-bound hint, equivalent to searchsortedfirstexp but as a dispatchable strategy. Suited to batched-sorted loops where hint = previous_result.
   • InterpolationSearch — linear-extrapolation guess then bounded binary search. O(1) per query on uniformly-spaced numeric data, O(log n) worst case, falls back to BinaryBracket for non-numeric v.

2. Reworks Auto based on a benchmark sweep (bench/strategies.jl, results checked in at bench/results.md). The matrix covers n × m × spacing × query-pattern × strategy — 5 spacings (uniform, log-spaced, jittered-near-uniform, random, two-scale-clustered) × 4 query patterns (sorted-uniform, sorted-dense-burst, sorted-near-start, unsorted) × 3 n × 4 m = 240 cells.

   Before/after Auto verdicts on the same 240-cell matrix:

   Auto state	within 20% of best	> 20% slower
   original length(v) ≤ 32 heuristic	89 / 240 (37%)	151 / 240
   bench-tuned (this commit)	214 / 240 (89%)	10 / 240

   Key changes that drove this:

   • Batched-Auto now picks based on the actual expected gap, using the span ratio (queries[end] - queries[1]) / (v[end] - v[1]) for numeric data. This correctly routes dense-burst queries (clustered in one segment of v) to LinearScan even when length(v) / length(queries) would suggest otherwise.
   • BracketGallop is no longer in Auto's batched choice — ExpFromLeft strictly beats it for forward-moving sorted queries (its bidirectional bracketing wastes effort).
   • m == 1 fast path skips the span/sortedness heuristic (saves ~20 ns/call).
   • Strategy dispatch in Auto's sorted loop is now via concrete if/else branches so each leg is type-stable and gets fully specialized.

3. Surfaced and fixed a real correctness bug in ExpFromLeft: when the hint was past the answer (x < v[hint]), the function returned ~hint - 1 instead of the correct (often-zero) index. Now falls back to a full searchsortedlast/searchsortedfirst in that case. Covered by the new tests.

4. Why InterpolationSearch is intentionally not in Auto's choice: on uniform/jittered data it wins big (~2× on n=65536, m=10), but on two_scale (clustered) data it's catastrophically slow (4-13× worse than ExpFromLeft at n=65536, m=4096). Detecting which regime applies cheaply enough to amortize over small m would require an O(n) looks_linear check that's net-negative on the cases where it'd help most. Users who know their data is roughly linear can opt in with strategy = InterpolationSearch(). The remaining 10 Auto-worse-than-20% cells in the bench are exactly these cases.

Test count: 26814 → 26929 (+115). Full bench output is in bench/results.md.

[ChrisRackauckas-Claude]

Pushed e26ac82 answering your three questions in turn:

1. Audit — does this maintain everything that was there before?

Yes. All these existing names keep working unchanged: bracketstrictlymontonic, searchsortedfirstexp, searchsortedfirstcorrelated(v, x, ::Integer), searchsortedlastcorrelated(v, x, ::Integer), the Guesser overloads of both, Range fast paths, searchsortedfirstvec/searchsortedlastvec, looks_linear, Guesser, findfirstequal, findfirstsortedequal. The new strategies wrap the existing algorithms rather than replacing them; legacy callers don't change.

2. More strategies to consider — added one

GuesserHint(::Guesser) — wraps the existing Guesser-based correlated search as a dispatchable strategy so it slots into the new batched/per-query API alongside LinearScan / BracketGallop / ExpFromLeft / InterpolationSearch / BinaryBracket / Auto. The Guesser already decides between linear-extrapolation lookup and using its cached previous index; GuesserHint simply re-exposes that under the strategy dispatch.

I also evaluated and rejected a couple of candidates:

• InterpolationGallop would essentially duplicate InterpolationSearch (which already uses gallop refinement internally).
• KAryBinarySearch / ParallelBinarySearch would be substantial implementations whose payoff vs. binary search is dominated by branch-prediction characteristics that vary across CPUs — out of scope.

3. Bench depth — vastly broadened

bench/strategies.jl now has five sub-sweep modes (MODE=fast default, full, spacing, ratio, pattern, extreme), with:

• 10 knot spacings (added power2, sqrt, plateau, bimodal, near_linear on top of uniform, log, jittered, random, two_scale)
• 8 query patterns (added sorted_arithmetic, sorted_geometric, sorted_bimodal, sorted_repeated on top of the original 4)
• n up to 262 144, m up to 16 384, and a dedicated super-sparse / super-dense sub-sweep that takes the ratio to its extremes

Final Auto verdict across 772 cells: 697 within 20% of best (90%), 50 worse (6%), 25 effectively tied.

Per-sub-sweep:

sub-sweep	within 20%
spacing variety (10 cells, all 10 spacings)	10/10 (100%)
query patterns (8 cells, all 8 patterns)	8/8 (100%)
super-dense (270 cells, m ≫ n)	270/270 (100%)
fast sweep (240 cells)	213/240 (89%)
super-sparse (180 cells, m ≪ n)	156/180 (87%)
n/m crossover (64 cells, all n × m combos on uniform)	40/64 (62%)

What the heuristic now does

The Auto choice for searchsortedlast!(out, v, queries; strategy = Auto()):

1. m == 0 → return immediately
2. m == 1 → bypass everything, dispatch straight to Base.searchsortedlast (saves ~20 ns of bookkeeping)
3. !issorted(queries) → per-element Base.searchsortedlast with no hint
4. Compute gap = floor(n × (queries-span / v-span) / m). The span ratio (for numeric data) detects dense_burst queries clustered inside a single segment of v, which would have n/m ≫ 0 but actual_gap ≈ 0.
5. gap ≤ 4 → LinearScan
6. gap ≥ 64, length(v) ≥ 1024, m ≥ 2, and the sampled linearity probe (5 reads of v at first, n/4, n/2, 3n/4, last — total ~12 ns — checks the interior points are within 5% of the straight line) accepts → InterpolationSearch. The probe is what prevents Auto from picking InterpolationSearch on non-linear data, where it loses badly (~4-13× on plateau and two_scale spacings at large m).
7. Otherwise → ExpFromLeft

Caught and fixed a real bug

ExpFromLeft previously assumed hint ≤ answer. When x < v[hint] (i.e., the hint was past the answer), it returned ~hint - 1 — wrong, sometimes wildly so. Now detects that case and falls back to a full Base.searchsortedlast / searchsortedfirst. Covered by the new tests.

Artifacts in the PR

• bench/strategies.jl — the bench harness, runnable via julia --project=bench bench/strategies.jl (or with one of the MODE=… env vars for the focused sweeps).
• bench/results.md — captured fast-sweep results (240 cells).
• bench/results_focused.md — captured spacing / pattern / ratio / extreme sub-sweep results (~500 cells).

Both are reproducible; they're the actual output from this commit run on Julia 1.10.

Tests: 26929 / 26929 passing locally. CI still waiting for the same first-time-contributor approval.

[ChrisRackauckas-Claude]

Pushed 65ea6c0. Much more thorough vetting + two algorithmic refinements:

Algorithmic changes

1. Skew detection. Tuning sweeps surfaced a previously-hidden regression: on sorted_near_start / sorted_geometric / sorted_bimodal patterns (most queries clustered in part of v's range), the span-based gap estimator underestimated the effective gap, and Auto routed to LinearScan when ExpFromLeft was best (1.8 – 3.1× slowdown).

_estimate_avg_gap now returns (gap, skewed), where skewed = true when the median query sits more than 20 % of the query span away from the linear midpoint. Gated on m ≥ 10 so small-batch statistical noise doesn't trip it.

2. InterpolationSearch gated on !skewed. Even on perfectly uniform v, when queries are clustered, ExpFromLeft from prev_idx beats InterpolationSearch because each consecutive query's true index is close to the previous one's. The skew flag now prevents Auto from gambling on InterpSearch in that regime.

3. Tightened linearity probe. From 5 probes / 5 % tolerance to 9 probes (k·n/10 for k = 1..9) / 0.1 % tolerance. Reliably rejects sorted-random data — which still looked linear-ish to the looser probe at large n — without rejecting any genuinely uniform or jittered grid. Probe cost is ~25 ns (was ~12 ns). This was the fix for Auto being 50 – 150 % slower than ExpFromLeft on random sorted data after InterpolationSearch was added.

4. AbstractRange short-circuit. _sampled_looks_linear(::AbstractRange) returns true without sampling; ranges are definitionally uniform.

Bench changes

• Five tuning sub-sweeps (MODE=tune) that empirically locate the strategy crossovers — LinearScan ↔ ExpFromLeft crosses at gap ≈ 5; ExpFromLeft ↔ InterpSearch crosses near gap 8 on uniform data; minimum useful n for InterpSearch is ~2048; minimum useful m is 2; InterpSearch's downside on non-linear data ranges from 1.5× (random) to 14× (plateau).
• A 3 920-cell validation sweep (MODE=validate) — every combination of 10 spacings × 8 query patterns × 7 n × 7 m.
• Two more knot spacings (near_linear, power2, sqrt) and pattern variety (sorted_arithmetic, sorted_geometric, sorted_bimodal, sorted_repeated).

Final verdicts

Across 4 692 cells in all sub-sweeps:

sub-sweep	within 20 %	worst case
spacing variety (10 cells)	10/10 (100 %)	none
pattern variety (8 cells)	7/8 (88 %)	1.51× at m=512
super-dense, m ≫ n (270 cells)	263/270 (97 %)	1.21× borderline
fast sweep (240 cells)	221/240 (92 %)	1.59× at m=10
super-sparse (180 cells)	147/180 (82 %)	2.00× at m=4
n/m crossover (64 cells)	51/64 (80 %)	1.62× at m=4096
validation (3 920 cells)	3 289/3 920 (84 %)	2.64× (1 cell)
aggregate (4 692 cells)	3 988 (85 %)	only 1 cell > 2×

The single cell exceeding 2× has a 180 ns absolute difference. The residual ~15 % outside-20 % cells are mostly m = 4 regimes where Auto's bookkeeping cost (issorted check, gap calc, linearity probe — totals ~30 – 50 ns) is non-negligible relative to the 100 – 300 ns total per-batch budget, and where direct InterpolationSearch would have saved another ~30 – 50 ns. Closing that gap would require type-specializing the dispatch further (e.g. via Val parameters), which I don't think is worth the added complexity.

I tried bumping _AUTO_INTERP_MIN_M from 2 to 10 to see if that helped (theory: skip InterpSearch's overhead on small batches). It was strictly worse (3 224 vs 3 289 cells within 20 %) — Auto's m = 2..9 wins on uniform sparse data are real and worth keeping.

Tests: 26 929 / 26 929 passing. CI awaiting maintainer approval as usual.