Add co-lexicographic (Wheeler) ordering

[Autoplectic]

Adds Wheeler (co-lexicographic) ordering to sofic as a structural layer: recognition and canonical sorting, a succinct BWT index, an interval fast path for the existing synchronization algorithms, and a stochastic layer for ε-machines.

A labeled graph is Wheeler when its states admit a total order in which each state's set of incoming words is a co-lex interval. Because co-lex compares strings from the last symbol backwards, it is the recency order on pasts — so an ε-machine is Wheeler exactly when its causal-state partition of history space is an interval partition under recency.

What's here

Topological core (sofic/automata/wheeler.py) — the three Gagie–Manzini–Sirén axioms, is_input_consistent as a cheap necessary condition, wheeler_order, minimum_wdfa, wnfa_to_wdfa, and colex_width. Since "is this presentation Wheeler?" is meaningful for any state machine, is_wheeler / wheeler_order / colex_width live on the StateMachine base class rather than only on UnifilarAutomaton, so sofic shifts and ε-machines get them too.

Interval fast path (sofic/generators/synchronization.py) — when a Wheeler order exists, reachable subsets of the power automaton are contiguous, so states become (lo, hi) pairs bounded by n(n+1)/2 instead of 2ⁿ. The four synchronization entry points inherit this with no behavioral change, and the tests assert both paths agree.

Succinct index (sofic/automata/wheeler_index.py) — the GMS representation with numpy-backed rank/select, forward_search, contains, and colex rank_word / unrank_word. No new dependencies.

Shifts (sofic/shifts/wheeler.py) — wheeler_cover, plus a WheelerCover class. The Krieger cover stubs in cover_construction.py are left alone; the Wheeler cover doesn't subsume enough of that machinery to fill them honestly.

Stochastic layer (sofic/generators/wheeler_epsilon.py) — original work. No literature exists on weighted or probabilistic Wheeler automata, so every public symbol carries a docstring saying no canonical source is known, per the repo's literature-references rule.

Presentations versus languages

These are kept as distinct APIs throughout. is_wheeler asks about this presentation. Whether the language is Wheeler is strictly weaker and much more expensive — O(mn) for a DFA, PSPACE-complete for an NFA — and that search over presentations is wheeler_cover / wheeler_presentation.

A result worth review

Beyond the expected C_W ≥ C_μ, there's a second independent bound: a Wheeler presentation is input consistent, so its state determines the symbol that entered it, giving C_W ≥ H[X₀] for a stationary process. Together, C_W ≥ max(C_μ, H[X₀]). The fair coin is the sharp case — nothing to predict, C_μ = 0, yet sortability costs a full bit.

This holds for irreducible machines using the stationary symbol entropy; it fails for UncoupledGMPs, which isn't strongly connected. The docstring and test both scope it accordingly.

Verification

996 tests pass, ruff clean, docs build with all citations resolving. Includes known-answer tests (golden mean Wheeler with order A < B; even, Nemo, and butterfly not), the enumeration counts 2/3/12/49/256 for k=2, n=1..5, hypothesis properties, index round-trips, and equivalence of the interval and subset power-automaton paths. The power-automaton comparison was mutation-tested to confirm it catches an introduced bug rather than passing vacuously.

Adds a 5-state Wheeler ε-machine with infinite Markov order as the discriminating example that Wheeler is not a restatement of finite memory, and nine references to docs/references.bib.

The final commit relocks uv.lock: pyproject.toml declares matplotlib>=3.5 under viz but the lock predated that, so every uv invocation was re-resolving before running. No package versions change.

Made with Cursor