morphata 2.2.2__tar.gz → 2.2.3__tar.gz

{morphata-2.2.2 → morphata-2.2.3}/.envrc

@@ -12,15 +12,13 @@ if [[ -z "${DEVJAIL:-}" ]] && nvidia_smi="$(type -p "nvidia-smi")" && [[ -n "$nv
   if [[ -n "${cuda_major_version:-}" ]]; then
     info "Detected CUDA version: $cuda_major_version"
     export CUDA_VERSION="$cuda_major_version"
-    PIXI_ENV="cu$CUDA_VERSION"
+    export CONDA_OVERRIDE_CUDA="$CUDA_VERSION"
+
   fi
 else
   info "Did not detect nvidia-smi, using non-GPU environment"
-  PIXI_ENV="default"
 fi
-export PIXI_ENV
 
 dotenv_if_exists
 
-watch_file pixi.lock
-eval "$(pixi shell-hook -e "$PIXI_ENV")"
+eval "$(pixi shell-hook)"

{morphata-2.2.2 → morphata-2.2.3}/.gitignore

@@ -1,3 +1,5 @@
+/thoughts/
+/issues/
 # generated version file
 src/morphata/_version.py
 

{morphata-2.2.2 → morphata-2.2.3}/CHANGELOG.md

@@ -1,5 +1,159 @@
 # Changelog
 
+## 2.2.3 — 2026-09-22
+
+This is a hefty release, but all really cool things that I am super proud of
+because now `morphata` is developed by directly dogfooding my projects.
+I don't think there was any major change to the public API of this package,
+so I will just be making this a patch release
+(which is funny to imagine the huge patch on something physical).
+
+### Changed
+
+- Alphabet domains are now respected by transformations, persistent storage,
+  and canonical DFA signatures.
+  Valuations outside the alphabet are treated
+  as impossible instead of quietly inflating transition partitions, serialized guards,
+  or language hashes.
+  No more ghost alphabet sneaking into the bookkeeping.
+
+- This is a big change (in the context of the changeset),
+  but shouldn't be a big one for the public facing API for consumers:
+  `SymbolicAutomaton` now relies only on the `transition_relation` field
+  as a first class field, and the outgoing transitions in `transitions` are computed
+  on-the-fly (with a cache that is possibly precomputed and passed to the initializer).
+  Effectively, this flips what we were doing earlier,
+  where we computed the transition relation from the list of outgoing transitions.
+
+- One thing that changed in the shadows of the previous one is that the API
+  for `SymbolicAutomaton` is more consistent!
+  `SymbolicAutomaton.materialize_sinks` was the only method
+  that mutated the automaton in-place, which feels wrong and, hence, was rectified:
+  `materialize_sinks` returns a new automaton *always*.
+
+- The documentation now uses the Furo theme.
+  It is a small change to the library, and as much as I love Alabaster,
+  I feel like Furo does a better job with typography and minimizing clutter.
+
+### Added
+
+- Meet `SparseMatrixOperator`, the explicitly sparse sibling of `MatrixOperator`.
+  Both expose the same construction and evaluation API,
+  but the choice of execution strategy is now visible in the type:
+  `MatrixOperator` builds dense transition matrices,
+  while `SparseMatrixOperator.step` works directly over the automaton's edges.
+  The sparse operator still exposes `delta` for those moments
+  when a dense view really is what you want.
+
+- Matrix operators now support leading batch dimensions natively.
+  The state axis is always last, so `step` accepts arrays shaped `(..., q)`,
+  `delta` returns `(..., q, q)`, and `accepts` preserves the leading batch shape.
+  This works with JAX transformations too, including `jit`, `vmap`, and gradients.
+
+- `BDDManager.guard_prime_cover` can now compute a prime cover relative to a `domain`,
+  with an optional deterministic `predicate_order`.
+  `partition_by_state_residual` has the same domain-aware vocabulary.
+  Outside the domain is a genuine don't-care region,
+  which keeps finite-alphabet guards compact without changing their meaning.
+
+- Symbolic automaton transformations accept an optional initial state formula,
+  allowing a transformation to start from a formula other than the automaton's
+  stored initial condition without modifying the source automaton.
+
+- `prune_unreachable`, which removes the states unreachable from an automaton's initial
+  states and, with `remove_sink_states=True`, the materialized sink states too (an
+  accepting sink becomes `manager.true` and a rejecting one `manager.false` in every
+  formula referring to it).
+  The surviving states keep their indices, so the result may have gaps.
+
+- `reindex_reachable`, which walks the reachable states breadth-first
+  and reindexes them contiguously,
+  optionally recording the correspondence in a caller-supplied `StateVarManager`,
+  materializing constant successors as sink states,
+  and breaking BFS ties with `predicate_exploration_order`.
+
+  Both are also available as `SymbolicAutomaton` methods.
+
+- A `SymbolicAutomaton.sorted_transitions` method
+  that returns a state's `(guard, successors)` pairs
+  (or every state's, when no state is given) in a canonical order.
+  The AP valuations are enumerated lexicographically in `predicate_order`,
+  with `False` before `True`; without one,
+  the predicates are ordered by their string forms,
+  since the manager's variable levels are not stable under reordering.
+  The partition is recomputed on each call.
+
+- A `make_sink_states` keyword on `remove_alternation`, `determinize`, and
+  `minimize_dfa`, controlling whether constant `True` and `False` successors are
+  materialized as indexed sink states.
+
+- A `reverse_language` utility that produces an automaton
+  that accepts the reversed language.
+
+- An `is_cyclic` utility to check if an automaton's state graph has a cycle
+
+- An optional ``abort_on_max_size`` bound on macro-state exploration in
+  ``explore_and_transform``, determinization, dealternation, and DFA minimization.
+  Exceeding the bound raises ``MacroStateLimitError`` with the number of states reached.
+
+- An option for predictable ordering of visited/yielded states
+  when performing BFS-based exploration/partitioning of a `SymbolicAutomaton`.
+
+  The keyword argument `predicate_exploration_order` added to `explore_and_transform`
+  and `partition_by_state_residual`
+  (and, virally, to its dependents)
+  allows users to provide a lexicographic order in
+  which atomic predicate valuations will be visited, with `False` before `True`.
+  Doing so allows for the BFS ties to be broken through this lexicographic order, but,
+  since we do some processing of the ordering, it may lead to some tiny performance drop
+  (not been profiled, just a caveat).
+
+- Add a signed version of the Levenshtein distance between two nondeterministic finite
+  automata.
+
+- `SemiringAlphabet` now has two optional fields that allows one to enumerate all
+  symbols in the alphabet (not just predicates), and test if some symbol is contained in
+  the alphabet.
+
+  - In addition, `BooleanAlphabet` now have a mandatory `domain` keyword argument which
+    constrains the universe of allowed predicate valuations as a BDD.
+
+- `morphata.storage` has means to store canonical representations (morphata-specific) of
+  `SymbolicAutomaton` to disk.
+  Additionally it exposes `CanonicalDfaHasher` that helps generate hashes
+  for the equivalence languages (residual and global language) of a DFA.
+
+### Performance
+
+- Matrix operators evaluate each distinct transition guard once per symbol
+  and then gather the result for its edges.
+  Besides removing a splendid amount of repeated work,
+  this keeps JAX's compiled weight construction tied to the number of distinct guards.
+  Repeated edges are handled by a gather, with no extra `weight_fn` calls.
+
+- Sparse stepping now gathers source-state values, multiplies only the real edges,
+  and reduces them with `segment_sum`.
+  Dense stepping remains the happy path for genuinely dense automata;
+  sparse stepping stops a low-degree automaton from paying the full quadratic bill.
+  That is why these are separate classes rather than a clever-but-invisible flag.
+
+### Developer Experience
+
+- The Pixi environments now describe CPU, CUDA 12, and CUDA 13 targets with virtual
+  packages, so dependency resolution does not have to guess which machine it is
+  eventually going to meet. `sphinx-autobuild` also joins the development toolbox
+  for faster documentation tinkering.
+
+### Fixed
+
+- `reverse_language` now keeps an initial reversed state even when
+  that state has no outgoing transitions.
+  A perfectly valid dead end should still exist, after all.
+
+- `min_dfa_of_conjunction` formerly said that it can only take list of `LTLExpr`,
+  but that isn't true.
+  Now, we correctly type it as `logic.Expr`.
+
 ## 2.2.2 — 2026-08-23
 
 ### Fixed

{morphata-2.2.2 → morphata-2.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: morphata
-Version: 2.2.2
+Version: 2.2.3
 Summary: Representation theory for automata, made practical.
 Project-URL: Documentation, https://docs.anandb.dev/morphata
 Project-URL: Repository, https://git.anandb.dev/morphata.git
@@ -13,6 +13,7 @@ Classifier: Topic :: Scientific/Engineering :: Mathematics
 Requires-Python: >=3.12
 Requires-Dist: algebraic-arrays>=1.3.0
 Requires-Dist: attrs>=25.4.0
+Requires-Dist: bitarray>=3.10.0
 Requires-Dist: cattrs>=26.1.0
 Requires-Dist: jaxtyping>=0.3
 Requires-Dist: lark>=1.3.1

{morphata-2.2.2 → morphata-2.2.3}/bench/README.md

@@ -13,6 +13,13 @@ To get pytest-benchmark's tabular wall-time output:
 
 ## Suites
 
+- `test_matrix_operator_perf.py` -- dense `MatrixOperator.step` versus sparse
+  `SparseMatrixOperator.step`, across NumPy eager, JAX `jit`, and PyTorch
+  `compile`. It reports public operator timings, prepared-topology kernel timings
+  over a density sweep, and a representative component breakdown.
+  JAX-only scale cases are opt-in via
+  `MORPHATA_RUN_SCALE_BENCHMARKS=1`; run each scale case in a fresh process under
+  a hard memory limit.
 - `test_sere_nlm_perf.py` -- NLM-intersection state-space blowup.
   Cases: `NLMInter(a0..a_{n-1})` for n in 2..6, `NLMInter(a_i;b_i)`
   for n in 2..4, plus length-matching `Inter` baselines.
@@ -25,6 +32,10 @@ To get pytest-benchmark's tabular wall-time output:
   the same grammar to quantify the LALR switch. Run with
   ``--benchmark-group-by=param:case`` to put the two algorithms side by
   side per input.
+- `test_distance_perf.py` -- signed Levenshtein distance, split into
+  end-to-end budget growth, ADD edit-model construction, layered neighborhoods,
+  and nondeterministic threshold inclusion. Each case prints intermediate state,
+  transition, ADD-node, and CUDD-node counts to locate the practical cliff.
 
 ## Recording results
 

morphata-2.2.3/bench/test_distance_perf.py

@@ -0,0 +1,218 @@
+"""Benchmarks for signed symbolic Levenshtein distance.
+
+The suite separates the main sources of growth instead of treating the input
+state count as a sufficient predictor:
+
+* end-to-end distance as the finite edit budget grows;
+* ADD edit-model construction as the target NFA grows;
+* compilation of an ADD model into a budget-layered neighborhood;
+* language inclusion against a nondeterministic neighborhood.
+
+The printed diagnostics identify which intermediate representation reaches the
+practical limit first.  There are deliberately no timing assertions: this is an
+opt-in exploratory suite whose timeout or memory limit records the cliff.
+
+Run with::
+
+    pytest bench/test_distance_perf.py -v \
+        --benchmark-columns=mean,median,min,max,rounds
+
+For a one-pass structural sweep with every diagnostic visible::
+
+    pytest bench/test_distance_perf.py -q -s --benchmark-disable
+"""
+
+from __future__ import annotations
+
+from collections.abc import Set as AbstractSet
+
+import pytest
+from pytest_benchmark.fixture import BenchmarkFixture as Benchmark
+
+from morphata.acceptance import Finite
+from morphata.alphabet import BooleanAlphabet, powerset_alphabet
+from morphata.symbolic import (
+    BDDManager,
+    Function,
+    SymbolicAutomaton,
+    levenshtein_distance,
+)
+from morphata.symbolic.distance import (
+    _edit_model,  # pyright: ignore[reportPrivateUsage]
+    _is_subset,  # pyright: ignore[reportPrivateUsage]
+    _neighborhood,  # pyright: ignore[reportPrivateUsage]
+    _prepare,  # pyright: ignore[reportPrivateUsage]
+)
+
+type _Symbol = AbstractSet[str]
+type _Aut = SymbolicAutomaton[str, _Symbol]
+
+_BUDGETS = [1, 2, 4, 8, 12, 16]
+_TARGET_SIZES = [4, 8, 16, 32, 64]
+_LAYER_SIZES = [2, 4, 8, 12, 16, 24]
+_INCLUSION_SIZES = [2, 4, 6, 8, 10, 12]
+
+
+def _alphabet() -> BooleanAlphabet[str, _Symbol]:
+    """Return the two-symbol AP-valuation alphabet used by every family."""
+    return powerset_alphabet({"a"})
+
+
+def _epsilon(
+    manager: BDDManager[str, int], alphabet: BooleanAlphabet[str, _Symbol]
+) -> _Aut:
+    """Return the singleton language containing only the empty word."""
+    manager.declare_state_vars(0)
+    transitions: dict[int, list[tuple[Function[str, int], Function[str, int]]]] = {
+        0: []
+    }
+    return SymbolicAutomaton(
+        manager=manager,
+        initial=manager.q_var(0),
+        transition_relation={
+            q: manager.relation_from_rows(r) for q, r in transitions.items()
+        },
+        acceptance=Finite(frozenset({0})),
+        alphabet=alphabet,
+    )
+
+
+def _length_at_most(
+    manager: BDDManager[str, int],
+    alphabet: BooleanAlphabet[str, _Symbol],
+    length: int,
+) -> _Aut:
+    """Return an NFA for all AP words of length at most ``length``."""
+    manager.declare_state_vars(*range(length + 1))
+    transitions = {
+        state: [(manager.true, manager.q_var(state + 1))] for state in range(length)
+    }
+    transitions[length] = []
+    return SymbolicAutomaton(
+        manager=manager,
+        initial=manager.q_var(0),
+        transition_relation={
+            q: manager.relation_from_rows(r) for q, r in transitions.items()
+        },
+        acceptance=Finite(frozenset(range(length + 1))),
+        alphabet=alphabet,
+    )
+
+
+def _branching_nfa(
+    manager: BDDManager[str, int],
+    alphabet: BooleanAlphabet[str, _Symbol],
+    num_states: int,
+) -> _Aut:
+    """Return a reachable, coaccessible NFA with overlapping successors."""
+    manager.declare_ap_vars("a")
+    manager.declare_state_vars(*range(num_states))
+    a = manager.ap_var("a")
+    transitions = {
+        state: [
+            (a, manager.q_var(state) | manager.q_var(state + 1)),
+            (~a, manager.q_var(state + 1)),
+        ]
+        for state in range(num_states - 1)
+    }
+    transitions[num_states - 1] = [(manager.true, manager.q_var(num_states - 1))]
+    return SymbolicAutomaton(
+        manager=manager,
+        initial=manager.q_var(0),
+        transition_relation={
+            q: manager.relation_from_rows(r) for q, r in transitions.items()
+        },
+        acceptance=Finite(frozenset({num_states - 1})),
+        alphabet=alphabet,
+    )
+
+
+def _manager_stats(manager: BDDManager[str, int]) -> str:
+    """Return current and peak CUDD node counts for benchmark diagnostics."""
+    raw_manager = manager.true.fn.manager
+    return f"cudd_nodes={raw_manager.node_count}, peak_cudd_nodes={raw_manager.peak_node_count}"
+
+
+@pytest.mark.limit_memory("2 GB")
+@pytest.mark.timeout(10 * 60)
+@pytest.mark.parametrize("budget", _BUDGETS)
+def test_distance_budget_growth(
+    benchmark: Benchmark, bench_mgr: BDDManager[str, int], budget: int
+) -> None:
+    """Measure the complete finite-positive branch as its answer grows."""
+    alphabet = _alphabet()
+    source = _length_at_most(bench_mgr, alphabet, budget)
+    target = _epsilon(bench_mgr, alphabet)
+
+    result = benchmark(levenshtein_distance, source, target)
+
+    assert result == budget
+    bound = (1 + source.num_states) * target.num_states
+    message = f"\ndistance budget={budget}: |A|={source.num_states}, |B|={target.num_states}, "
+    message += f"K={bound}, {_manager_stats(bench_mgr)}"
+    print(message)
+
+
+@pytest.mark.limit_memory("2 GB")
+@pytest.mark.timeout(10 * 60)
+@pytest.mark.parametrize("num_states", _TARGET_SIZES)
+def test_edit_model_target_growth(
+    benchmark: Benchmark, bench_mgr: BDDManager[str, int], num_states: int
+) -> None:
+    """Measure deletion closure and ADD construction for growing targets."""
+    target = _prepare(_branching_nfa(bench_mgr, _alphabet(), num_states))
+
+    model = benchmark(_edit_model, target)
+
+    add_nodes = [weight.node_count() for weight in model.transition_cost.values()]
+    message = f"\nedit model |B|={num_states}: entries={len(add_nodes)}, "
+    message += (
+        f"add_nodes_total={sum(add_nodes)}, add_nodes_max={max(add_nodes, default=0)}, "
+    )
+    message += _manager_stats(bench_mgr)
+    print(message)
+
+
+@pytest.mark.limit_memory("2 GB")
+@pytest.mark.timeout(10 * 60)
+@pytest.mark.parametrize("num_states", _LAYER_SIZES)
+def test_neighborhood_layer_growth(
+    benchmark: Benchmark, bench_mgr: BDDManager[str, int], num_states: int
+) -> None:
+    """Measure reachable layered-state growth at ``k = |Q_B|``."""
+    target = _prepare(_branching_nfa(bench_mgr, _alphabet(), num_states))
+    model = _edit_model(target)
+    k = num_states
+
+    neighborhood = benchmark(_neighborhood, model, k)
+
+    num_transitions = sum(len(row) for row in neighborhood.transitions().values())
+    message = (
+        f"\nneighborhood |B|={num_states}, k={k}: states={neighborhood.num_states}, "
+    )
+    message += f"transitions={num_transitions}, {_manager_stats(bench_mgr)}"
+    print(message)
+
+
+@pytest.mark.limit_memory("2 GB")
+@pytest.mark.timeout(10 * 60)
+@pytest.mark.parametrize("num_states", _INCLUSION_SIZES)
+def test_threshold_inclusion_nondeterminism(
+    benchmark: Benchmark, bench_mgr: BDDManager[str, int], num_states: int
+) -> None:
+    """Measure the inclusion check after constructing a nondeterministic neighborhood."""
+    source = _prepare(_branching_nfa(bench_mgr, _alphabet(), num_states))
+    model = _edit_model(source)
+    k = max(1, num_states // 2)
+    neighborhood = _neighborhood(model, k)
+
+    result = benchmark(_is_subset, source, neighborhood)
+
+    assert result
+    num_transitions = sum(len(row) for row in neighborhood.transitions().values())
+    message = f"\ninclusion |A|=|B|={num_states}, k={k}: "
+    message += f"neighborhood_states={neighborhood.num_states}, "
+    message += (
+        f"neighborhood_transitions={num_transitions}, {_manager_stats(bench_mgr)}"
+    )
+    print(message)

{morphata-2.2.2 → morphata-2.2.3}/bench/test_equivalence_perf.py

@@ -21,7 +21,6 @@ from pytest_benchmark.fixture import BenchmarkFixture as Benchmark
 
 from morphata.alphabet import powerset_alphabet
 from morphata.symbolic.automaton import SymbolicAutomaton
-from morphata.symbolic.utils import is_language_equivalent
 
 
 def _sparse_big_alphabet_dfa() -> SymbolicAutomaton[str, AbstractSet[str]]:
@@ -44,6 +43,6 @@ def test_language_equivalent_sparse_big_alphabet(benchmark: Benchmark) -> None:
     dfa = _sparse_big_alphabet_dfa()
 
     def _run() -> bool:
-        return is_language_equivalent(dfa, dfa)
+        return dfa.is_language_equivalent(dfa)
 
     assert benchmark(_run)