sofic 0.1.0__py3-none-any.whl

sofic/shifts/parry_construction.py

@@ -0,0 +1,82 @@
+"""Parry measure construction for topological Markov chains."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from sofic.generators.mealy import MealyHMM
+from sofic.graph import ATTR_EMISSION, ATTR_MULTIPLICITY, ATTR_PROB
+from sofic.shifts.algorithms import adjacency_matrix
+from sofic.shifts.tmc import TopologicalMarkovChain
+
+
+def _perron_pair(matrix: np.ndarray) -> tuple[float, np.ndarray, np.ndarray]:
+    """Return (λ, left, right) Perron eigenvectors with left^T right = 1."""
+    eigenvalues, right_vecs = np.linalg.eig(matrix)
+    index = int(np.argmax(np.real(eigenvalues)))
+    lam = float(np.real(eigenvalues[index]))
+    right = np.real(right_vecs[:, index])
+    if right[np.argmax(np.abs(right))] < 0.0:
+        right = -right
+    right = np.maximum(right, 1e-300)
+
+    left_eigenvalues, left_vecs = np.linalg.eig(matrix.T)
+    left_index = int(np.argmax(np.real(left_eigenvalues)))
+    left = np.real(left_vecs[:, left_index])
+    if left[np.argmax(np.abs(left))] < 0.0:
+        left = -left
+    left = np.maximum(left, 1e-300)
+
+    scale = float(left @ right)
+    if scale < 0.0:
+        left = -left
+        scale = -scale
+    if scale <= 0.0:
+        raise ValueError("failed to normalize Perron eigenvectors")
+    left /= scale
+    return lam, left, right
+
+
+def parry_measure(tmc: TopologicalMarkovChain) -> MealyHMM:
+    matrix, states = adjacency_matrix(tmc)
+    if matrix.size == 0:
+        return MealyHMM(initial_distribution={}, observation_alphabet=frozenset())
+
+    lam, left, right = _perron_pair(matrix)
+    n = len(states)
+    transition = np.zeros((n, n), dtype=float)
+    for i in range(n):
+        for j in range(n):
+            if matrix[i, j] > 0.0:
+                transition[i, j] = matrix[i, j] * right[j] / (lam * right[i])
+
+    stationary = left * right
+    stationary /= stationary.sum()
+
+    hmm = MealyHMM(
+        initial_distribution={states[i]: float(stationary[i]) for i in range(n)},
+        observation_alphabet=tmc.symbol_alphabet,
+    )
+    for state in states:
+        hmm.graph.add_state(state)
+
+    for transition_edge in tmc.transitions():
+        i = states.index(transition_edge.source)
+        j = states.index(transition_edge.target)
+        multiplicity = float(transition_edge.data.get(ATTR_MULTIPLICITY, 1))
+        total = matrix[i, j]
+        if total <= 0.0:
+            continue
+        symbol = transition_edge.data.get(ATTR_EMISSION)
+        if symbol is None:
+            from sofic.graph import ATTR_SYMBOL
+
+            symbol = transition_edge.data.get(ATTR_SYMBOL)
+        weight = transition[i, j] * (multiplicity / total)
+        hmm.graph.add_transition(
+            transition_edge.source,
+            transition_edge.target,
+            **{ATTR_PROB: float(weight), ATTR_EMISSION: symbol},
+        )
+    hmm.validate()
+    return hmm

sofic/shifts/sft.py

@@ -0,0 +1,104 @@
+"""Shifts of finite type."""
+
+from __future__ import annotations
+
+from itertools import product
+from typing import Any
+
+from sofic.graph import TransitionGraph
+from sofic.shifts.base import SymbolicModel
+
+
+class ShiftOfFiniteType(SymbolicModel):
+    """SFT specified by forbidden words or an explicit presentation."""
+
+    _forbidden_words: frozenset[tuple[Any, ...]]
+    _has_forbidden_word_spec: bool
+
+    def __init__(
+        self,
+        forbidden_words: set[tuple[Any, ...]] | frozenset[tuple[Any, ...]] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self._has_forbidden_word_spec = forbidden_words is not None
+        self._forbidden_words = frozenset(tuple(word) for word in (forbidden_words or set()))
+
+    @classmethod
+    def from_forbidden_words(
+        cls,
+        forbidden: set[tuple[Any, ...]],
+        symbol_alphabet: frozenset[Any],
+        **kwargs: Any,
+    ) -> ShiftOfFiniteType:
+        from sofic.shifts.sft_construction import from_forbidden_words
+
+        return from_forbidden_words(forbidden, symbol_alphabet, **kwargs)
+
+    @classmethod
+    def from_presentation(
+        cls,
+        graph: TransitionGraph,
+        symbol_alphabet: frozenset[Any],
+        **kwargs: Any,
+    ) -> ShiftOfFiniteType:
+        return cls(graph=graph, symbol_alphabet=symbol_alphabet, **kwargs)
+
+    def forbidden_words(
+        self,
+        *,
+        length: int | None = None,
+        max_length: int | None = None,
+        minimal: bool = False,
+    ) -> frozenset[tuple[Any, ...]]:
+        """Return forbidden words stored on or inferred from this presentation.
+
+        With no bounds, this returns the finite defining set supplied to
+        :meth:`from_forbidden_words`. For presentation-only SFTs, pass
+        ``length`` or ``max_length`` to enumerate forbidden blocks up to that
+        bound.
+        """
+        if length is None and max_length is None:
+            if minimal and self._has_forbidden_word_spec:
+                return _minimal_forbidden(self._forbidden_words)
+            if self._has_forbidden_word_spec:
+                return self._forbidden_words
+            raise ValueError("pass length or max_length to infer forbidden words from a presentation")
+        if length is not None and max_length is not None:
+            raise ValueError("pass either length or max_length, not both")
+        if length is not None and length < 0:
+            raise ValueError("length must be nonnegative")
+        if max_length is not None and max_length < 0:
+            raise ValueError("max_length must be nonnegative")
+        if length is not None:
+            lengths = range(length, length + 1)
+        else:
+            assert max_length is not None
+            lengths = range(1, max_length + 1)
+        forbidden = set().union(*(self._forbidden_words_by_length(n) for n in lengths))
+        return _minimal_forbidden(frozenset(forbidden)) if minimal else frozenset(forbidden)
+
+    def _forbidden_words_by_length(self, length: int) -> frozenset[tuple[Any, ...]]:
+        if length < 0:
+            raise ValueError("length must be nonnegative")
+        alphabet = sorted(self.symbol_alphabet, key=repr)
+        allowed = set(self.factor_language(length))
+        candidates = set(product(alphabet, repeat=length))
+        return frozenset(candidates - allowed)
+
+
+def _minimal_forbidden(words: frozenset[tuple[Any, ...]]) -> frozenset[tuple[Any, ...]]:
+    minimal: set[tuple[Any, ...]] = set()
+    for word in words:
+        has_forbidden_subword = False
+        for start in range(len(word)):
+            for stop in range(start + 1, len(word) + 1):
+                subword = word[start:stop]
+                if subword != word and subword in words:
+                    has_forbidden_subword = True
+                    break
+            if has_forbidden_subword:
+                break
+        if not has_forbidden_subword:
+            minimal.add(word)
+    return frozenset(minimal)

sofic/shifts/sft_construction.py

@@ -0,0 +1,52 @@
+"""SFT construction from forbidden words."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sofic.graph import ATTR_SYMBOL, TransitionGraph
+from sofic.shifts.sft import ShiftOfFiniteType
+
+
+def from_forbidden_words(
+    forbidden: set[tuple[Any, ...]],
+    symbol_alphabet: frozenset[Any],
+    *,
+    max_states: int = 256,
+) -> ShiftOfFiniteType:
+    """Build an SFT presentation via a follower automaton on allowed prefixes."""
+    alphabet = tuple(symbol_alphabet)
+    forbidden_set = set(forbidden)
+    max_len = max((len(word) for word in forbidden_set), default=0)
+
+    def is_allowed(prefix: tuple[Any, ...]) -> bool:
+        return all(not (len(word) <= len(prefix) and prefix[-len(word) :] == word) for word in forbidden_set)
+
+    graph = TransitionGraph()
+    start: tuple[Any, ...] = ()
+    graph.add_state(start)
+    queue = [start]
+    seen = {start}
+
+    while queue:
+        prefix = queue.pop(0)
+        if len(seen) >= max_states:
+            break
+        for symbol in alphabet:
+            extended = prefix + (symbol,)
+            if not is_allowed(extended):
+                continue
+            trimmed = extended
+            if max_len > 0:
+                trimmed = extended[-max_len:]
+            if trimmed not in seen:
+                seen.add(trimmed)
+                graph.add_state(trimmed)
+                queue.append(trimmed)
+            graph.add_transition(prefix, trimmed, **{ATTR_SYMBOL: symbol})
+
+    return ShiftOfFiniteType.from_presentation(
+        graph,
+        symbol_alphabet=symbol_alphabet,
+        forbidden_words=forbidden_set,
+    )

sofic/shifts/sliding_block_code.py

@@ -0,0 +1,156 @@
+"""Sliding block codes (factor maps) between subshifts.
+
+A sliding block code is the symbolic-dynamics form of a transducer: a map
+``Phi`` between shift spaces induced by a local rule on a window of ``memory + 1
++ anticipation`` consecutive symbols (the Curtis-Hedlund-Lyndon theorem
+characterizes exactly the shift-commuting continuous maps this way). See
+Lind & Marcus, *An Introduction to Symbolic Dynamics and Coding* (1995), ch. 1
+and 6.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, Sequence
+from itertools import product
+from typing import Any
+
+from sofic.graph import ATTR_OUTPUT, ATTR_SYMBOL, TransitionGraph
+from sofic.shifts.sofic import SoficShift
+
+
+class SlidingBlockCode:
+    """A block map ``Phi`` with given memory and anticipation.
+
+    ``block_map`` sends each length-``(memory + 1 + anticipation)`` input window to
+    a single output symbol. Applying ``Phi`` to a point slides this window,
+    emitting one output symbol per position.
+
+    Examples
+    --------
+    >>> from sofic.shifts.sliding_block_code import SlidingBlockCode
+    >>> nor = SlidingBlockCode(
+    ...     {("0", "0"): "1", ("0", "1"): "0", ("1", "0"): "0", ("1", "1"): "0"},
+    ...     memory=1,
+    ...     anticipation=0,
+    ... )
+    >>> nor.apply_word(["0", "0", "1", "0"])
+    ('1', '0', '0')
+    """
+
+    def __init__(
+        self,
+        block_map: Mapping[Sequence[Any], Any],
+        *,
+        memory: int = 0,
+        anticipation: int = 0,
+        input_alphabet: Iterable[Any] | None = None,
+        output_alphabet: Iterable[Any] | None = None,
+    ) -> None:
+        if memory < 0 or anticipation < 0:
+            raise ValueError("memory and anticipation must be non-negative")
+        self.memory = memory
+        self.anticipation = anticipation
+        self.window = memory + anticipation + 1
+        self.block_map: dict[tuple[Any, ...], Any] = {tuple(key): value for key, value in block_map.items()}
+        for key in self.block_map:
+            if len(key) != self.window:
+                raise ValueError(f"block_map key {key!r} has length {len(key)}, expected window {self.window}")
+        self.input_alphabet = frozenset(
+            input_alphabet if input_alphabet is not None else {symbol for key in self.block_map for symbol in key}
+        )
+        self.output_alphabet = frozenset(output_alphabet if output_alphabet is not None else self.block_map.values())
+
+    def __repr__(self) -> str:
+        return f"SlidingBlockCode(window={self.window}, memory={self.memory}, anticipation={self.anticipation})"
+
+    def apply_word(self, word: Sequence[Any]) -> tuple[Any, ...]:
+        """Return ``Phi`` applied to a finite word (shrinks by ``window - 1``)."""
+        word = tuple(word)
+        if len(word) < self.window:
+            return ()
+        return tuple(self.block_map[word[i : i + self.window]] for i in range(len(word) - self.window + 1))
+
+    def apply(self, shift: Any) -> SoficShift:
+        """Return the image subshift ``Phi(shift)`` as a sofic presentation.
+
+        Uses the higher-block construction: vertices are allowed
+        ``(window - 1)``-blocks of ``shift`` and each allowed ``window``-block
+        contributes an edge labeled by its image symbol.
+        """
+        image = SoficShift(symbol_alphabet=frozenset(self.output_alphabet))
+        blocks = list(shift.factor_language(self.window))
+        vertices = {block[:-1] for block in blocks} | {block[1:] for block in blocks}
+        for vertex in vertices:
+            image.graph.add_state(vertex)
+        used_outputs: set[Any] = set()
+        for block in blocks:
+            output = self.block_map.get(block)
+            if output is None:
+                continue
+            image.add_transition(block[:-1], block[1:], output)
+            used_outputs.add(output)
+        image.symbol_alphabet = frozenset(used_outputs)
+        return image.trim_transient()
+
+    def is_right_resolving(self, shift: Any | None = None) -> bool:
+        """Return whether the induced image presentation is right-resolving."""
+        source = shift if shift is not None else full_shift(self.input_alphabet)
+        return self.apply(source).is_unifilar()
+
+    def compose(self, other: SlidingBlockCode) -> SlidingBlockCode:
+        """Return ``other`` applied after ``self`` (function composition ``other ∘ self``)."""
+        window = self.window + other.window - 1
+        composed: dict[tuple[Any, ...], Any] = {}
+        for word in product(sorted(self.input_alphabet, key=repr), repeat=window):
+            middle = self.apply_word(word)
+            if len(middle) != other.window:
+                continue
+            output = other.block_map.get(tuple(middle))
+            if output is None:
+                continue
+            composed[word] = output
+        return SlidingBlockCode(
+            composed,
+            memory=self.memory + other.memory,
+            anticipation=self.anticipation + other.anticipation,
+            input_alphabet=self.input_alphabet,
+            output_alphabet=other.output_alphabet,
+        )
+
+    def to_transducer(self) -> Any:
+        """Return a Mealy machine realizing this code (output delayed by anticipation)."""
+        from sofic.automata.transducers import MealyMachine
+
+        graph = TransitionGraph()
+        context_length = self.window - 1
+        contexts = list(product(sorted(self.input_alphabet, key=repr), repeat=context_length))
+        for context in contexts:
+            graph.add_state(context)
+        used_outputs: set[Any] = set()
+        for context in contexts:
+            for symbol in sorted(self.input_alphabet, key=repr):
+                window = (*context, symbol)
+                output = self.block_map.get(window)
+                if output is None:
+                    continue
+                target = window[1:]
+                graph.add_transition(context, target, **{ATTR_SYMBOL: symbol, ATTR_OUTPUT: output})
+                used_outputs.add(output)
+        machine = MealyMachine(
+            input_alphabet=frozenset(self.input_alphabet),
+            output_alphabet=frozenset(used_outputs),
+            initial_states=frozenset(contexts),
+            graph=graph,
+        )
+        machine.validate()
+        return machine
+
+
+def full_shift(alphabet: Iterable[Any]) -> SoficShift:
+    """Return the full shift over ``alphabet`` as a one-state sofic presentation."""
+    symbols = frozenset(alphabet)
+    shift = SoficShift(symbol_alphabet=symbols)
+    shift.graph.add_state("*")
+    for symbol in symbols:
+        shift.add_transition("*", "*", symbol)
+    return shift

sofic/shifts/sofic.py

@@ -0,0 +1,111 @@
+"""Sofic shift presentations."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from sofic.shifts.base import SymbolicModel
+
+if TYPE_CHECKING:
+    from sofic.generators.mealy import MealyHMM
+
+
+class SoficShift(SymbolicModel):
+    """Sofic subshift given by a labeled directed graph presentation."""
+
+    def topological_entropy(self) -> float:
+        from sofic.shifts.tmc_construction import topological_entropy
+
+        return topological_entropy(self)
+
+    def parry_measure(self) -> MealyHMM:
+        """Measure of maximal entropy (Parry measure) as a labeled Mealy HMM.
+
+        The unique measure attaining ``h_top`` (Parry 1964): built from the Perron
+        data of a right-resolving presentation of this shift, with each edge's
+        emitted symbol preserved. See
+        :func:`~sofic.shifts.topological_anatomy.parry_measure_sofic`.
+        """
+        from sofic.shifts.topological_anatomy import parry_measure_sofic
+
+        return parry_measure_sofic(self)
+
+    def topological_anatomy(self) -> dict[str, float]:
+        """Topological information anatomy: the MME split ``h_top = b_top + r_top``.
+
+        Evaluates the metric information anatomy (James et al. 2013) of the
+        observed symbol process at the measure of maximal entropy, returning
+        ``{h_top, b_top, r_top, excess_entropy}``. Here ``r_top`` is the MME
+        erasure entropy rate (Verdu & Weissman 2008). See
+        :func:`~sofic.shifts.topological_anatomy.topological_anatomy`.
+        """
+        from sofic.shifts.topological_anatomy import topological_anatomy
+
+        return topological_anatomy(self)
+
+    def markov_order(self) -> int | float:
+        """Markov order ``R`` when the presentation is right-resolving (unifilar)."""
+        from sofic.generators.synchronization import graph_from_sofic_shift, markov_order_from_graph
+
+        return markov_order_from_graph(graph_from_sofic_shift(self))
+
+    def cryptic_order(self) -> int | float:
+        """Cryptic order ``k_chi`` when the presentation is right-resolving."""
+        from sofic.generators.synchronization import cryptic_order_from_graph, graph_from_sofic_shift
+
+        return cryptic_order_from_graph(graph_from_sofic_shift(self))
+
+    def reset_threshold(self) -> int | float:
+        """Reset threshold: shortest synchronizing (reset) word length.
+
+        The complement of :meth:`markov_order`; ``math.inf`` when not exactly
+        synchronizable. For the Cerny bound (complete automata only) see Volkov
+        (2008).
+        """
+        from sofic.generators.synchronization import graph_from_sofic_shift, reset_threshold_from_graph
+
+        return reset_threshold_from_graph(graph_from_sofic_shift(self))
+
+    def synchronizing_word(self) -> list[Any] | None:
+        """Return a shortest synchronizing word, or ``None`` if not exactly synchronizable.
+
+        The list of symbols has length :meth:`reset_threshold` (Travers &
+        Crutchfield, arXiv:1008.4182).
+        """
+        from sofic.generators.synchronization import graph_from_sofic_shift, shortest_synchronizing_word_from_graph
+
+        return shortest_synchronizing_word_from_graph(graph_from_sofic_shift(self))
+
+    def is_exactly_synchronizable(self) -> bool:
+        """Return whether this presentation is exactly synchronizable.
+
+        True iff a finite synchronizing word exists (the reset threshold is
+        finite; Travers & Crutchfield, arXiv:1008.4182). Strictly weaker than
+        finite Markov order: see :meth:`is_definite`.
+        """
+        from sofic.generators.synchronization import graph_from_sofic_shift, is_exactly_synchronizable
+
+        return is_exactly_synchronizable(graph_from_sofic_shift(self))
+
+    def is_asymptotically_synchronizable(self) -> bool:
+        """Return whether this presentation is asymptotically synchronizable.
+
+        True for every finite-state ε-machine (Travers & Crutchfield,
+        arXiv:1008.4182); theorem-backed rather than computed.
+        """
+        from sofic.generators.synchronization import (
+            graph_from_sofic_shift,
+            is_asymptotically_synchronizable_from_graph,
+        )
+
+        return is_asymptotically_synchronizable_from_graph(graph_from_sofic_shift(self))
+
+    def is_definite(self) -> bool:
+        """Return whether this presentation is a definite automaton (finite Markov order).
+
+        Definiteness (Perles-Rabin-Shamir) means the state is fixed by the last
+        ``R`` symbols. Implies :meth:`is_exactly_synchronizable`.
+        """
+        from sofic.generators.synchronization import graph_from_sofic_shift, is_definite_from_graph
+
+        return is_definite_from_graph(graph_from_sofic_shift(self))

sofic/shifts/sofic_dyck.py

@@ -0,0 +1,110 @@
+"""Sofic-Dyck shift presentations."""
+
+from __future__ import annotations
+
+from collections.abc import Hashable, Iterator, Sequence
+from typing import Any
+
+from sofic.graph import ATTR_KIND, ATTR_SYMBOL, KIND_CALL, KIND_INTERNAL, KIND_RETURN, Transition
+from sofic.shifts.base import SymbolicModel
+
+TransitionRef = tuple[Hashable, Hashable, int]
+MatchedEdge = tuple[TransitionRef, TransitionRef]
+
+_KINDS = frozenset({KIND_CALL, KIND_RETURN, KIND_INTERNAL})
+
+
+def transition_ref(transition: Transition) -> TransitionRef:
+    """Return the stable graph reference for ``transition``."""
+    return transition.source, transition.target, transition.key
+
+
+class SoficDyckShift(SymbolicModel):
+    """Sofic-Dyck shift presented by a finite Dyck automaton."""
+
+    call_alphabet: frozenset[Any]
+    return_alphabet: frozenset[Any]
+    internal_alphabet: frozenset[Any]
+    matched_edges: frozenset[MatchedEdge]
+
+    def __init__(
+        self,
+        call_alphabet: frozenset[Any] | None = None,
+        return_alphabet: frozenset[Any] | None = None,
+        internal_alphabet: frozenset[Any] | None = None,
+        matched_edges: set[MatchedEdge] | frozenset[MatchedEdge] | None = None,
+        symbol_alphabet: frozenset[Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self.call_alphabet = call_alphabet if call_alphabet is not None else frozenset()
+        self.return_alphabet = return_alphabet if return_alphabet is not None else frozenset()
+        self.internal_alphabet = internal_alphabet if internal_alphabet is not None else frozenset()
+        inferred_alphabet = self.call_alphabet | self.return_alphabet | self.internal_alphabet
+        super().__init__(
+            symbol_alphabet=symbol_alphabet if symbol_alphabet is not None else inferred_alphabet, **kwargs
+        )
+        self.matched_edges = frozenset(matched_edges or frozenset())
+
+    def validate(self) -> None:
+        super().validate()
+        role_alphabet = self.call_alphabet | self.return_alphabet | self.internal_alphabet
+        self._require(
+            len(self.call_alphabet) + len(self.return_alphabet) + len(self.internal_alphabet) == len(role_alphabet),
+            "call, return, and internal alphabets must be disjoint",
+        )
+        self._require(self.symbol_alphabet == role_alphabet, "symbol_alphabet must equal the visible role alphabets")
+
+        call_edges: set[TransitionRef] = set()
+        return_edges: set[TransitionRef] = set()
+        all_edges: set[TransitionRef] = set()
+        for transition in self.transitions():
+            ref = transition_ref(transition)
+            all_edges.add(ref)
+            kind = transition.data.get(ATTR_KIND)
+            symbol = transition.data.get(ATTR_SYMBOL)
+            self._require(kind in _KINDS, f"invalid Dyck edge kind {kind!r}")
+            self._require(symbol is not None, "Dyck shift transitions require a symbol")
+            if kind == KIND_CALL:
+                self._require(symbol in self.call_alphabet, f"{symbol!r} not in call alphabet")
+                call_edges.add(ref)
+            elif kind == KIND_RETURN:
+                self._require(symbol in self.return_alphabet, f"{symbol!r} not in return alphabet")
+                return_edges.add(ref)
+            else:
+                self._require(symbol in self.internal_alphabet, f"{symbol!r} not in internal alphabet")
+
+        for call_ref, return_ref in self.matched_edges:
+            self._require(call_ref in all_edges, f"matched call edge {call_ref!r} is missing")
+            self._require(return_ref in all_edges, f"matched return edge {return_ref!r} is missing")
+            self._require(call_ref in call_edges, f"matched edge {call_ref!r} is not a call transition")
+            self._require(return_ref in return_edges, f"matched edge {return_ref!r} is not a return transition")
+
+    def add_call_transition(self, source: Hashable, target: Hashable, symbol: Any, **attrs: Any) -> TransitionRef:
+        """Add a call transition and return its stable edge reference."""
+        key = self.graph.add_transition(source, target, **{**attrs, ATTR_KIND: KIND_CALL, ATTR_SYMBOL: symbol})
+        return source, target, key
+
+    def add_return_transition(self, source: Hashable, target: Hashable, symbol: Any, **attrs: Any) -> TransitionRef:
+        """Add a return transition and return its stable edge reference."""
+        key = self.graph.add_transition(source, target, **{**attrs, ATTR_KIND: KIND_RETURN, ATTR_SYMBOL: symbol})
+        return source, target, key
+
+    def add_internal_transition(self, source: Hashable, target: Hashable, symbol: Any, **attrs: Any) -> TransitionRef:
+        """Add an internal transition and return its stable edge reference."""
+        key = self.graph.add_transition(source, target, **{**attrs, ATTR_KIND: KIND_INTERNAL, ATTR_SYMBOL: symbol})
+        return source, target, key
+
+    def add_matched_pair(self, call_ref: TransitionRef, return_ref: TransitionRef) -> None:
+        """Mark ``call_ref`` and ``return_ref`` as a legal call-return pair."""
+        self.matched_edges = frozenset({*self.matched_edges, (call_ref, return_ref)})
+
+    def is_admissible_word(self, word: Sequence[Any]) -> bool:
+        """Return whether ``word`` is a finite factor of this Dyck presentation."""
+        from sofic.shifts.dyck_algorithms import is_admissible_word
+
+        return is_admissible_word(self, word)
+
+    def factor_language(self, length: int) -> Iterator[tuple[Any, ...]]:
+        from sofic.shifts.dyck_algorithms import admissible_words
+
+        yield from admissible_words(self, length)

sofic/shifts/sofic_relation.py

@@ -0,0 +1,64 @@
+"""Sofic relations: subshifts over a product alphabet ``X x Y``.
+
+The topological support of a transducer is a subshift of the product shift on
+``X x Y`` -- a "sofic relation" whose input and output projections are the
+transducer's domain and range subshifts. This is the symbolic-dynamics reading
+of a transducer, complementary to the sliding block code (Lind & Marcus, *An
+Introduction to Symbolic Dynamics and Coding* (1995), ch. 6).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sofic.graph import ATTR_OUTPUT, ATTR_SYMBOL, EPSILON
+from sofic.shifts.sofic import SoficShift
+
+
+class SoficRelation(SoficShift):
+    """A sofic subshift whose symbols are ``(input, output)`` pairs."""
+
+    @classmethod
+    def from_transducer(cls, transducer: Any) -> SoficRelation:
+        """Build the topological support of a transducer (probabilities dropped)."""
+        relation = cls()
+        pairs: set[tuple[Any, Any]] = set()
+        for state in transducer.states():
+            relation.graph.add_state(state)
+        for transition in transducer.transitions():
+            input_symbol = transition.data.get(ATTR_SYMBOL, EPSILON)
+            output_symbol = transition.data.get(ATTR_OUTPUT, EPSILON)
+            pair = (input_symbol, output_symbol)
+            relation.add_transition(transition.source, transition.target, pair)
+            pairs.add(pair)
+        relation.symbol_alphabet = frozenset(pairs)
+        return relation
+
+    def input_alphabet(self) -> frozenset[Any]:
+        """Return the set of input symbols appearing in the relation."""
+        return frozenset(pair[0] for pair in self.symbol_alphabet)
+
+    def output_alphabet(self) -> frozenset[Any]:
+        """Return the set of output symbols appearing in the relation."""
+        return frozenset(pair[1] for pair in self.symbol_alphabet)
+
+    def input_shift(self) -> SoficShift:
+        """Return the projection onto the input coordinate as a sofic shift."""
+        return self._project(0)
+
+    def output_shift(self) -> SoficShift:
+        """Return the projection onto the output coordinate as a sofic shift."""
+        return self._project(1)
+
+    def _project(self, index: int) -> SoficShift:
+        projected = SoficShift()
+        symbols: set[Any] = set()
+        for state in self.states():
+            projected.graph.add_state(state)
+        for transition in self.transitions():
+            pair = transition.data.get(ATTR_SYMBOL)
+            symbol = pair[index] if isinstance(pair, tuple) else pair
+            projected.add_transition(transition.source, transition.target, symbol)
+            symbols.add(symbol)
+        projected.symbol_alphabet = frozenset(symbols)
+        return projected