morphata 2.0.4__tar.gz → 2.0.5__tar.gz

{morphata-2.0.4 → morphata-2.0.5}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 2.0.5 — 2026-06-01
+
+### Added
+
+`SymbolicAutomaton` and `Automaton` now support a streaming writer
+for HOA export via `morphata.hoa.symbolic_automaton_to_hoa`
+and `morphata.hoa.automaton_to_hoa`, and is also present in `SymbolicAutomaton.to_hoa`.
+
+This is mostly a performance thing:
+providing a buffered writer to the exporter allows one to stream the HOA format into a
+file, without having to manifest the entire string representation of the automaton,
+which can be cumbersome.
+
 ## 2.0.4 — 2026-05-28
 
 ### Added

{morphata-2.0.4 → morphata-2.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: morphata
-Version: 2.0.4
+Version: 2.0.5
 Summary: Representation theory for automata, made practical.
 Project-URL: Documentation, https://docs.anandb.dev/morphata
 Project-URL: Repository, https://git.anandb.dev/morphata.git
@@ -20,7 +20,7 @@ Requires-Dist: logic-asts>=1.6.2
 Requires-Dist: networkx
 Requires-Dist: numpy
 Requires-Dist: types-networkx
-Requires-Dist: typing-extensions
+Requires-Dist: typing-extensions>=4.14
 Provides-Extra: dot
 Requires-Dist: pydot>=4.0.1; extra == 'dot'
 Provides-Extra: jax

{morphata-2.0.4 → morphata-2.0.5}/ci/make-release

@@ -88,7 +88,7 @@ echo "==> Promoting CHANGELOG Unreleased -> ${NEW_VERSION} (${RELEASE_DATE})"
 sed -i "s/^## Unreleased$/## ${NEW_VERSION} \xe2\x80\x94 ${RELEASE_DATE}/" CHANGELOG.md
 
 # Commit
-COMMIT_MSG="chore(release): ${NEW_VERSION}"
+COMMIT_MSG="chore(release): $(uv version)"
 echo "==> Committing: $COMMIT_MSG"
 
 if is_jj; then
@@ -120,8 +120,8 @@ echo "==> Tagging $TAG"
 if is_jj; then
   jj git import 2>/dev/null || true
 fi
-printf '%s\n\n%s\n' "$TAG_TITLE" "$TAG_BODY" \
-  | git tag -a "$TAG" --cleanup=verbatim -F -
+printf '%s\n\n%s\n' "$TAG_TITLE" "$TAG_BODY" |
+  git tag -a "$TAG" --cleanup=verbatim -F -
 if is_jj; then
   jj git import 2>/dev/null || true
 fi

{morphata-2.0.4 → morphata-2.0.5}/pixi.lock

@@ -5474,7 +5474,7 @@ packages:
   - networkx
   - numpy
   - types-networkx
-  - typing-extensions
+  - typing-extensions>=4.14
   - jax>=0.8 ; extra == 'jax'
   - torch>=2.0 ; extra == 'torch'
   - pydot>=4.0.1 ; extra == 'dot'

{morphata-2.0.4 → morphata-2.0.5}/pixi.toml

@@ -17,7 +17,7 @@ lark = ">=1.3.1"
 networkx = "*"
 numpy = "*"
 types-networkx = "*"
-typing-extensions = "*"
+typing-extensions = ">=4.14"
 
 [pypi-dependencies]
 morphata = { path = ".", editable = true }

{morphata-2.0.4 → morphata-2.0.5}/pyproject.toml

@@ -2,7 +2,7 @@
 name = "morphata"
 authors = [{ name = "Anand Balakrishnan", email = "anandbala1597@gmail.com" }]
 description = "Representation theory for automata, made practical."
-version = "2.0.4"
+version = "2.0.5"
 requires-python = ">=3.12"
 classifiers = [
   "Intended Audience :: Science/Research",
@@ -21,7 +21,7 @@ dependencies = [
   "networkx",
   "numpy",
   "types-networkx",
-  "typing-extensions",
+  "typing-extensions>=4.14",
 ]
 
 [project.optional-dependencies]

{morphata-2.0.4 → morphata-2.0.5}/src/morphata/hoa/__init__.py

@@ -37,7 +37,8 @@ Example extended HOA with finite acceptance::
 
 import morphata.hoa.parser as parser
 from morphata.hoa.exporter import automaton_to_hoa as automaton_to_hoa
+from morphata.hoa.exporter import symbolic_automaton_to_hoa as symbolic_automaton_to_hoa
 from morphata.hoa.parser import ParsedAutomaton as ParsedAutomaton
 from morphata.hoa.parser import parse as parse
 
-__all__ = ["parse", "parser", "ParsedAutomaton", "automaton_to_hoa"]
+__all__ = ["parse", "parser", "ParsedAutomaton", "automaton_to_hoa", "symbolic_automaton_to_hoa"]

{morphata-2.0.4 → morphata-2.0.5}/src/morphata/hoa/exporter.py

@@ -12,23 +12,53 @@ import io
 import typing as ty
 from collections.abc import Iterable, Mapping, Sequence
 from collections.abc import Set as AbstractSet
+from typing import TYPE_CHECKING
 
 import logic_asts.base as logic
+from typing_extensions import Writer, overload
 
 import morphata.hoa.acc_expr as acc_expr
 
-if ty.TYPE_CHECKING:
+if TYPE_CHECKING:
     from morphata.acceptance import AcceptanceCondition
     from morphata.automaton import Automaton
+    from morphata.symbolic.automaton import SymbolicAutomaton
+    from morphata.symbolic.bdd import Function, Manager
 
 
+@overload
 def automaton_to_hoa(
-    aut: Automaton[int, ty.Any, ty.Any],
+    aut: "Automaton[int, ty.Any, ty.Any]",
+    *,
+    name: str | None = ...,
+    properties: "Sequence[str] | None" = ...,
+    out: None = ...,
+) -> str: ...
+
+
+@overload
+def automaton_to_hoa(
+    aut: "Automaton[int, ty.Any, ty.Any]",
+    *,
+    name: str | None = ...,
+    properties: "Sequence[str] | None" = ...,
+    out: "Writer[str]",
+) -> None: ...
+
+
+def automaton_to_hoa(
+    aut: "Automaton[int, ty.Any, ty.Any]",
     *,
     name: str | None = None,
-    properties: Sequence[str] | None = None,
-) -> str:
-    """Serialize *aut* to an HOA v1 string.
+    properties: "Sequence[str] | None" = None,
+    out: "Writer[str] | None" = None,
+) -> "str | None":
+    """Serialize *aut* to HOA v1.
+
+    If ``out`` is ``None`` (the default), build the HOA in an internal
+    ``io.StringIO`` and return the resulting string. If ``out`` is
+    provided, stream the HOA directly into it and return ``None``; the
+    caller owns flushing / closing.
 
     Requirements on *aut*:
 
@@ -50,7 +80,8 @@ def automaton_to_hoa(
     ap_to_index = {ap: i for i, ap in enumerate(ap_order)}
     acc_name, acc_expr_text, num_sets, acc_state_sets = _acceptance_to_hoa(aut.acceptance)
 
-    buf = io.StringIO()
+    owns_buffer = out is None
+    buf: Writer[str] = io.StringIO() if out is None else out
     _write_header(
         buf,
         aut=aut,
@@ -69,7 +100,173 @@ def automaton_to_hoa(
         ap_to_index=ap_to_index,
         acc_state_sets=acc_state_sets,
     )
-    return buf.getvalue()
+    if owns_buffer:
+        assert isinstance(buf, io.StringIO)
+        return buf.getvalue()
+    return None
+
+
+@overload
+def symbolic_automaton_to_hoa(
+    sym: "SymbolicAutomaton[ty.Any]",
+    *,
+    name: str | None = ...,
+    properties: Sequence[str] | None = ...,
+    out: None = ...,
+) -> str: ...
+
+
+@overload
+def symbolic_automaton_to_hoa(
+    sym: "SymbolicAutomaton[ty.Any]",
+    *,
+    name: str | None = ...,
+    properties: Sequence[str] | None = ...,
+    out: Writer[str],
+) -> None: ...
+
+
+def symbolic_automaton_to_hoa(
+    sym: "SymbolicAutomaton[ty.Any]",
+    *,
+    name: str | None = None,
+    properties: Sequence[str] | None = None,
+    out: Writer[str] | None = None,
+) -> str | None:
+    """Serialize a :class:`SymbolicAutomaton` to HOA v1 directly from its BDDs.
+
+    Walks ``sym.transitions`` row-by-row. For each cached
+    ``(guard_bdd, succ_bdd)`` pair, enumerates AP-cubes of ``guard_bdd``
+    via ``BDD.pick_iter`` (over the BDD's support, no ``care_vars``) and
+    successor-state cubes of ``succ_bdd`` the same way, and emits one
+    HOA ``[label] dst`` edge per (guard cube x successor cube). No
+    ``logic_asts.BoolExpr`` tree is constructed.
+
+    ``out`` semantics match :func:`automaton_to_hoa`: when ``None``, an
+    internal ``StringIO`` accumulates the output and is returned;
+    otherwise the output streams into ``out`` and the function returns
+    ``None``.
+
+    Literal-true / literal-false successor BDDs (``mgr.true`` /
+    ``mgr.false``) are handled by emitting synthetic sink states with
+    self-loops, mirroring :func:`_materialize_sinks` on the IR side. The
+    BDD manager is not mutated. As on the IR side, sink materialisation
+    is only implemented for :class:`~morphata.acceptance.Finite`
+    acceptance; omega-regular conditions with literal successors raise
+    ``NotImplementedError``.
+
+    Raises
+    ------
+    ValueError
+        If the cached transition table is empty but ``sym.num_states > 0``.
+    NotImplementedError
+        If literal-true / literal-false successors are present and the
+        acceptance condition is not :class:`~morphata.acceptance.Finite`.
+    """
+    from morphata.acceptance import Finite
+
+    if sym.num_states > 0 and not sym.transitions:
+        raise ValueError(
+            "symbolic_automaton_to_hoa requires a populated transition cache; "
+            "reconstruct SymbolicAutomaton with cache_transitions=True."
+        )
+
+    mgr = sym.manager
+
+    needs_true = sym.initial == mgr.true
+    needs_false = sym.initial == mgr.false
+    for s in range(sym.num_states):
+        for _, succ_bdd in sym.transitions.get(s, ()):
+            if succ_bdd == mgr.true:
+                needs_true = True
+            elif succ_bdd == mgr.false:
+                needs_false = True
+
+    if (needs_true or needs_false) and not isinstance(sym.acceptance, Finite):
+        raise NotImplementedError(
+            "HOA export: literal-true / literal-false successor BDDs require "
+            "sink-state materialisation, which is only implemented for "
+            f"Finite acceptance; got {type(sym.acceptance).__name__}."
+        )
+
+    next_idx = sym.num_states
+    true_sink: int | None = None
+    false_sink: int | None = None
+    if needs_true:
+        true_sink = next_idx
+        next_idx += 1
+    if needs_false:
+        false_sink = next_idx
+        next_idx += 1
+    total_states = next_idx
+
+    ap_order = sorted(sym.ap_registry, key=repr)
+    bdd_var_to_ap_index: dict[str, int] = {sym.ap_registry[ap]: i for i, ap in enumerate(ap_order)}
+    acc_name, acc_expr_text, num_sets, acc_state_sets = _acceptance_to_hoa(sym.acceptance)
+    if true_sink is not None:
+        # Finite acceptance: extend set 0 (the accepting set) with the
+        # true-sink. ``_acceptance_to_hoa(Finite)`` always returns
+        # ``{0: ...}``.
+        augmented_sets: dict[int, AbstractSet[int]] = dict(acc_state_sets)
+        augmented_sets[0] = frozenset(augmented_sets.get(0, frozenset())) | {true_sink}
+        acc_state_sets = augmented_sets
+    states = list(range(sym.num_states))
+
+    owns_buffer = out is None
+    buf: Writer[str] = io.StringIO() if owns_buffer else out  # type: ignore[assignment]
+
+    buf.write("HOA: v1\n")
+    if name is not None:
+        buf.write(f'name: "{name}"\n')
+    buf.write(f"States: {total_states}\n")
+    if sym.initial == mgr.true:
+        assert true_sink is not None
+        buf.write(f"Start: {true_sink}\n")
+    elif sym.initial == mgr.false:
+        assert false_sink is not None
+        buf.write(f"Start: {false_sink}\n")
+    else:
+        for start_line in _bdd_state_cubes(sym.initial, mgr=mgr):
+            buf.write(f"Start: {start_line}\n")
+    ap_words = " ".join(f'"{ap}"' for ap in ap_order)
+    buf.write(f"AP: {len(ap_order)}{(' ' + ap_words) if ap_order else ''}\n")
+    if acc_name is not None:
+        buf.write(f"acc-name: {acc_name}\n")
+    buf.write(f"Acceptance: {num_sets} {acc_expr_text}\n")
+    if properties:
+        buf.write("properties: " + " ".join(properties) + "\n")
+
+    buf.write("--BODY--\n")
+    for s in states:
+        sets_for_s = sorted(idx for idx, members in acc_state_sets.items() if s in members)
+        marker = (" {" + " ".join(str(i) for i in sets_for_s) + "}") if sets_for_s else ""
+        buf.write(f"State: {s}{marker}\n")
+        for guard_bdd, succ_bdd in sym.transitions.get(s, ()):
+            if succ_bdd == mgr.true:
+                assert true_sink is not None
+                dsts = [str(true_sink)]
+            elif succ_bdd == mgr.false:
+                assert false_sink is not None
+                dsts = [str(false_sink)]
+            else:
+                dsts = _bdd_state_cubes(succ_bdd, mgr=mgr)
+            for cube in mgr.pick_iter(guard_bdd):
+                label = _cube_to_hoa_label(cube, bdd_var_to_ap_index)
+                for dst in dsts:
+                    buf.write(f"[{label}] {dst}\n")
+    for sink in (true_sink, false_sink):
+        if sink is None:
+            continue
+        sets_for_sink = sorted(idx for idx, members in acc_state_sets.items() if sink in members)
+        marker = (" {" + " ".join(str(i) for i in sets_for_sink) + "}") if sets_for_sink else ""
+        buf.write(f"State: {sink}{marker}\n")
+        buf.write(f"[t] {sink}\n")
+    buf.write("--END--\n")
+
+    if owns_buffer:
+        assert isinstance(buf, io.StringIO)
+        return buf.getvalue()
+    return None
 
 
 # ---------------------------------------------------------------------------
@@ -181,7 +378,7 @@ def _materialize_sinks(
 
 
 def _write_header(
-    buf: io.StringIO,
+    buf: Writer[str],
     *,
     aut: Automaton[int, ty.Any, ty.Any],
     states: list[int],
@@ -255,7 +452,7 @@ def _flatten_or(expr: logic.BoolExpr[ty.Any]) -> list[logic.BoolExpr[ty.Any]]:
 
 
 def _write_body(
-    buf: io.StringIO,
+    buf: Writer[str],
     *,
     aut: Automaton[int, ty.Any, ty.Any],
     states: list[int],
@@ -351,6 +548,69 @@ def _conj_to_dst(expr: logic.BoolExpr[int], *, context: str) -> str:
     raise ValueError(f"HOA {context} expression must be a disjunction of conjunctions of state variables; got {expr!r}.")
 
 
+# ---------------------------------------------------------------------------
+# BDD-direct helpers (symbolic_automaton_to_hoa)
+# ---------------------------------------------------------------------------
+
+
+def _cube_to_hoa_label(
+    cube: Mapping[str, bool],
+    bdd_var_to_ap_index: Mapping[str, int],
+) -> str:
+    """Render a single BDD cube over AP variables as an HOA label.
+
+    *cube* is a ``{bdd_var_name: bool}`` dict from ``dd``'s
+    ``BDD.pick_iter``; variables absent from the BDD's support are
+    don't-cares and do not appear in the output.
+    *bdd_var_to_ap_index* maps the BDD variable name back to the AP's
+    HOA index. Literals in the output are sorted by AP index for
+    deterministic output.
+    """
+    if not cube:
+        return "t"
+    literals: list[tuple[int, bool]] = []
+    for var_name, polarity in cube.items():
+        try:
+            idx = bdd_var_to_ap_index[var_name]
+        except KeyError as exc:
+            raise ValueError(f"BDD cube references variable {var_name!r} not in the AP registry.") from exc
+        literals.append((idx, polarity))
+    literals.sort(key=lambda iv: iv[0])
+    parts = [(str(idx) if polarity else f"!{idx}") for idx, polarity in literals]
+    if len(parts) == 1:
+        return parts[0]
+    return "(" + " & ".join(parts) + ")"
+
+
+def _bdd_state_cubes(node: "Function", *, mgr: "Manager") -> list[str]:
+    """Enumerate satisfying cubes of *node* over state variables as HOA dst strings.
+
+    *node* is a ``dd.Function`` over the state variables ``q0..q{n-1}``;
+    *mgr* is the owning ``dd.BDD`` manager (``pick_iter`` lives on it,
+    not on Function objects). We enumerate minterms over the BDD's
+    *support* (i.e. no ``care_vars`` argument), so a point-successor
+    function naturally yields one cube.
+
+    For each cube:
+
+    - Positive state variables -> the cube's HOA destination
+      ``"d1&d2&..."`` (a single integer when there is one positive).
+    - Negative state variables in the cube are dropped from the output
+      (HOA `dst` expressions list only the chosen states).
+
+    A cube with zero positive state variables is treated as a bug and
+    raises ``ValueError``; the caller is responsible for rejecting
+    literal-false successor BDDs before reaching here.
+    """
+    cubes: list[str] = []
+    for cube in mgr.pick_iter(node):
+        positives = sorted(int(name[1:]) for name, val in cube.items() if val)
+        if not positives:
+            raise ValueError("Successor BDD cube has no positive state variable; cannot render an HOA destination.")
+        cubes.append("&".join(str(i) for i in positives))
+    return cubes
+
+
 # ---------------------------------------------------------------------------
 # Acceptance
 # ---------------------------------------------------------------------------

{morphata-2.0.4 → morphata-2.0.5}/src/morphata/symbolic/automaton.py

@@ -44,6 +44,8 @@ from morphata.automaton import Automaton, BoolExpr
 from morphata.hoa import ParsedAutomaton
 
 if TYPE_CHECKING:
+    from typing_extensions import Writer
+
     from morphata.alphabet import BooleanAlphabet
 from morphata.symbolic.bdd import (
     APRegistry,
@@ -230,11 +232,18 @@ class SymbolicAutomaton(Generic[AP]):
         *,
         name: str | None = None,
         properties: Sequence[str] | None = None,
-    ) -> str:
-        """Serialize ``self`` to an HOA v1 string via :func:`automaton_to_hoa`."""
-        from morphata.hoa import automaton_to_hoa
+        out: "Writer[str] | None" = None,
+    ) -> str | None:
+        """Serialize ``self`` to HOA v1 via :func:`symbolic_automaton_to_hoa`.
+
+        Walks the cached transition BDDs directly -- no
+        ``logic_asts.BoolExpr`` intermediates. When ``out`` is given,
+        streams output into it and returns ``None``; otherwise returns
+        the full HOA string.
+        """
+        from morphata.hoa import symbolic_automaton_to_hoa
 
-        return automaton_to_hoa(self.to_automaton(), name=name, properties=properties)
+        return symbolic_automaton_to_hoa(self, name=name, properties=properties, out=out)
 
     def to_min_dfa(self) -> "SymbolicAutomaton[AP]":
         """Determinize and minimize ``self`` into a minimal DFA.