sofic 0.1.0__py3-none-any.whl

sofic/automata/vpa_simulation.py

@@ -0,0 +1,53 @@
+"""Stack simulation for visibly pushdown automata."""
+
+from __future__ import annotations
+
+from collections.abc import Hashable, Iterator, Sequence
+from typing import Any
+
+from sofic.automata._config_simulation import simulate_configs
+from sofic.automata.vpa import VisiblyPushdownAutomaton
+from sofic.graph import ATTR_KIND, ATTR_STACK_SYMBOL, ATTR_SYMBOL, KIND_CALL, KIND_INTERNAL, KIND_RETURN
+
+_BOTTOM = object()
+
+Config = tuple[Hashable, tuple[Any, ...]]
+
+
+def recognizes_vpa(vpa: VisiblyPushdownAutomaton, word: Sequence[Any]) -> bool:
+    """Return whether ``vpa`` accepts ``word``."""
+    if vpa.initial_state is None:
+        return False
+
+    bottom = _BOTTOM if vpa.bottom_stack_symbol is None else vpa.bottom_stack_symbol
+    initial: set[Config] = {(vpa.initial_state, (bottom,))}
+
+    def step(config: Config, symbol: Any) -> Iterator[Config]:
+        state, stack = config
+        for transition in vpa.graph.out_transitions(state):
+            data = transition.data
+            if data.get(ATTR_SYMBOL) != symbol:
+                continue
+            kind = data.get(ATTR_KIND)
+            if kind == KIND_CALL:
+                stack_sym = data.get(ATTR_STACK_SYMBOL)
+                if stack_sym is None:
+                    continue
+                yield (transition.target, stack + (stack_sym,))
+            elif kind == KIND_RETURN:
+                stack_sym = data.get(ATTR_STACK_SYMBOL)
+                if len(stack) <= 1:
+                    if vpa.bottom_stack_symbol is None:
+                        continue
+                    if stack_sym is not None and stack_sym != stack[-1]:
+                        continue
+                    yield (transition.target, stack)
+                    continue
+                if stack_sym is not None and stack_sym != stack[-1]:
+                    continue
+                yield (transition.target, stack[:-1])
+            elif kind == KIND_INTERNAL:
+                yield (transition.target, stack)
+
+    current = simulate_configs(initial, word, step)
+    return any(state in vpa.accepting_states for state, _ in current)

sofic/base.py

@@ -0,0 +1,153 @@
+"""Abstract base for all sofic state-machine models."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Hashable, Iterator
+from copy import deepcopy
+from pathlib import Path
+from typing import Any, Self
+
+import networkx as nx
+
+from sofic.exceptions import SoficValidationError
+from sofic.graph import Transition, TransitionGraph
+from sofic.indexing import StateIndex
+
+
+class StateMachine(ABC):
+    """Common interface for graph-backed models in sofic."""
+
+    graph: TransitionGraph
+
+    def __init__(self, graph: TransitionGraph | None = None) -> None:
+        self.graph = graph if graph is not None else TransitionGraph()
+
+    @abstractmethod
+    def validate(self) -> None:
+        """Raise :class:`~sofic.exceptions.SoficValidationError` on failure."""
+
+    def states(self) -> Iterator[Hashable]:
+        yield from self.graph.states()
+
+    def transitions(self) -> Iterator[Transition]:
+        yield from self.graph.transitions()
+
+    def reindex(self) -> StateIndex:
+        return StateIndex(self.states())
+
+    def copy(self) -> Self:
+        cloned = object.__new__(self.__class__)
+        cloned.graph = self.graph.copy()
+        for name, value in self.__dict__.items():
+            if name == "graph":
+                continue
+            cloned.__dict__[name] = deepcopy(value)
+        return cloned
+
+    def to_networkx(self) -> nx.MultiDiGraph:
+        return self.graph.nx.copy()
+
+    @classmethod
+    def from_networkx(cls, g: nx.MultiDiGraph, **kwargs: Any) -> Self:
+        return cls(graph=TransitionGraph(g.copy()), **kwargs)
+
+    def to_yaml(self) -> str:
+        """Return a YAML representation of this model."""
+        from sofic.serialization import model_to_yaml
+
+        return model_to_yaml(self)
+
+    def write_yaml(self, path: str | Path) -> None:
+        """Write this model as YAML."""
+        Path(path).write_text(self.to_yaml(), encoding="utf-8")
+
+    @classmethod
+    def from_yaml(cls, text: str, *, validate: bool = True) -> Self:
+        """Reconstruct a model from YAML text."""
+        from sofic.serialization import model_from_yaml
+
+        model = model_from_yaml(text, validate=validate)
+        if not isinstance(model, cls):
+            raise TypeError(f"YAML contains {type(model).__qualname__}, not a {cls.__qualname__}")
+        return model
+
+    @classmethod
+    def read_yaml(cls, path: str | Path, *, validate: bool = True) -> Self:
+        """Read a model from a YAML file."""
+        return cls.from_yaml(Path(path).read_text(encoding="utf-8"), validate=validate)
+
+    def reverse(self) -> Self:
+        """Return a model with the transition graph transposed."""
+        result = self.copy()
+        result.graph = self.graph.reverse()
+        return result
+
+    def __repr__(self) -> str:
+        states = list(self.states())
+        transitions = list(self.transitions())
+        return f"{self.__class__.__name__}({len(states)} states, {len(transitions)} transitions)"
+
+    def _repr_png_(self) -> bytes | None:
+        """Notebook image: Graphviz PNG, or ``None`` if rendering is unavailable."""
+        try:
+            from sofic.viz.graphviz import model_to_png
+
+            return model_to_png(self)
+        except Exception:
+            return None
+
+    def _graphviz_svg(self) -> str | None:
+        """Graphviz SVG for notebook vector display."""
+        try:
+            from sofic.viz.graphviz import model_to_svg
+
+            return model_to_svg(self)
+        except Exception:
+            return None
+
+    def _repr_mimebundle_(
+        self,
+        include: set[str] | None = None,
+        exclude: set[str] | None = None,
+    ) -> dict[str, Any] | None:
+        bundle: dict[str, Any] = {"text/plain": repr(self)}
+
+        svg = self._graphviz_svg()
+        if svg is not None:
+            bundle["image/svg+xml"] = svg
+
+        if include is not None:
+            bundle = {key: value for key, value in bundle.items() if key in include}
+        if exclude is not None:
+            bundle = {key: value for key, value in bundle.items() if key not in exclude}
+
+        return bundle if len(bundle) > 1 else None
+
+    def to_graphviz(self, **kwargs: Any) -> Any:
+        """Build a Graphviz diagram for this model."""
+        from sofic.viz.graphviz import model_to_graphviz
+
+        return model_to_graphviz(self, **kwargs)
+
+    def draw(self, filename: str | None = None, **kwargs: Any) -> str | None:
+        """Render this model with Graphviz."""
+        from sofic.viz.graphviz import draw
+
+        return draw(self, filename=filename, **kwargs)
+
+    def to_tikz(self, **kwargs: Any) -> str:
+        """Return a Vaucanson-style TikZ picture for this model."""
+        from sofic.viz.tikz import model_to_tikz
+
+        return model_to_tikz(self, **kwargs)
+
+    def draw_tikz(self, filename: str | None = None, **kwargs: Any) -> str | None:
+        """Write a TikZ fragment for this model."""
+        from sofic.viz.tikz import draw_tikz
+
+        return draw_tikz(self, filename=filename, **kwargs)
+
+    def _require(self, condition: bool, message: str) -> None:
+        if not condition:
+            raise SoficValidationError(message)

sofic/core.py

@@ -0,0 +1,47 @@
+"""Core graph-backed model primitives."""
+
+from sofic.base import StateMachine
+from sofic.graph import (
+    ATTR_EMISSION,
+    ATTR_EMISSION_DIST,
+    ATTR_EMISSION_EDGE,
+    ATTR_FUTURE_SYMBOL,
+    ATTR_HIER_STATE,
+    ATTR_KIND,
+    ATTR_MULTIPLICITY,
+    ATTR_OUTPUT,
+    ATTR_PROB,
+    ATTR_QUASIPROB,
+    ATTR_STACK_SYMBOL,
+    ATTR_SYMBOL,
+    EPSILON,
+    KIND_CALL,
+    KIND_INTERNAL,
+    KIND_RETURN,
+    Transition,
+    TransitionGraph,
+)
+from sofic.indexing import StateIndex
+
+__all__ = [
+    "ATTR_EMISSION",
+    "ATTR_EMISSION_DIST",
+    "ATTR_EMISSION_EDGE",
+    "ATTR_FUTURE_SYMBOL",
+    "ATTR_HIER_STATE",
+    "ATTR_KIND",
+    "ATTR_MULTIPLICITY",
+    "ATTR_OUTPUT",
+    "ATTR_PROB",
+    "ATTR_QUASIPROB",
+    "ATTR_STACK_SYMBOL",
+    "ATTR_SYMBOL",
+    "EPSILON",
+    "KIND_CALL",
+    "KIND_INTERNAL",
+    "KIND_RETURN",
+    "StateIndex",
+    "StateMachine",
+    "Transition",
+    "TransitionGraph",
+]

sofic/examples/__init__.py

@@ -0,0 +1,86 @@
+"""Canonical examples from the computational mechanics literature."""
+
+from importlib import import_module as _import_module
+
+from sofic.examples.epsilon_machines import (
+    TENT_MAP_MISIUREWICZ_PARTITIONS,
+    alternating_biased_coins,
+    bernoulli,
+    butterfly_process,
+    ellison_fig9_forward,
+    ellison_fig9_reverse,
+    ellison_fig15_bidirectional,
+    even_process,
+    fair_coin,
+    golden_mean,
+    golden_mean_bidirectional,
+    golden_mean_forward,
+    golden_mean_markov,
+    golden_mean_reverse,
+    golden_mean_shift_parry,
+    nemo_process,
+    noisy_random_phase_slip,
+    restricted_golden_mean,
+    tent_map_misiurewicz_a,
+    tent_map_misiurewicz_bidirectional,
+    tent_map_misiurewicz_forward,
+    tent_map_misiurewicz_hmm,
+    tent_map_misiurewicz_information_expected,
+    tent_map_misiurewicz_partition_cuts,
+    tent_map_misiurewicz_partition_forward,
+    tent_map_misiurewicz_partition_information_expected,
+    tent_map_misiurewicz_partition_symbol_matrices,
+    tent_map_misiurewicz_reverse,
+)
+from sofic.examples.processes import *
+from sofic.examples.processes import __all__ as _process_all
+from sofic.examples.shifts import (
+    dyck_shift_order,
+    motzkin_shift,
+    sofic_dyck_fig1_shift,
+    sofic_dyck_nondeterminizable_shift,
+    sofic_dyck_zeta_example_shift,
+)
+
+processes = _import_module("sofic.examples.processes")
+shifts = _import_module("sofic.examples.shifts")
+
+__all__ = [
+    "alternating_biased_coins",
+    "bernoulli",
+    "butterfly_process",
+    "dyck_shift_order",
+    "ellison_fig9_forward",
+    "ellison_fig9_reverse",
+    "ellison_fig15_bidirectional",
+    "even_process",
+    "fair_coin",
+    "golden_mean",
+    "golden_mean_forward",
+    "golden_mean_markov",
+    "golden_mean_reverse",
+    "golden_mean_bidirectional",
+    "golden_mean_shift_parry",
+    "motzkin_shift",
+    "nemo_process",
+    "noisy_random_phase_slip",
+    "restricted_golden_mean",
+    "sofic_dyck_fig1_shift",
+    "sofic_dyck_nondeterminizable_shift",
+    "sofic_dyck_zeta_example_shift",
+    "TENT_MAP_MISIUREWICZ_PARTITIONS",
+    "tent_map_misiurewicz_a",
+    "tent_map_misiurewicz_bidirectional",
+    "tent_map_misiurewicz_forward",
+    "tent_map_misiurewicz_hmm",
+    "tent_map_misiurewicz_information_expected",
+    "tent_map_misiurewicz_partition_cuts",
+    "tent_map_misiurewicz_partition_forward",
+    "tent_map_misiurewicz_partition_information_expected",
+    "tent_map_misiurewicz_partition_symbol_matrices",
+    "tent_map_misiurewicz_reverse",
+]
+__all__ += _process_all
+__all__ = [name for name in __all__ if name not in {"processes", "shifts"}]
+__all__.append("processes")
+__all__.append("shifts")