sofic 0.1.0__py3-none-any.whl

sofic/shifts/textile.py

@@ -0,0 +1,104 @@
+"""Textile systems (Nasu 1995): the machine form of a sliding block code.
+
+A textile system encodes a factor map between subshifts as a pair of labelings
+over a shared edge graph -- one reading the domain (input) symbols, one the range
+(output) symbols. This is Nasu's formalization (*Textile Systems for Endomorphisms
+and Automorphisms of the Shift*, Memoirs AMS 546, 1995); operationally it is a
+topological transducer whose input labeling, when right-resolving, induces a
+:class:`~sofic.shifts.sliding_block_code.SlidingBlockCode` from the input shift to
+the output shift.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Hashable
+from typing import Any
+
+from sofic.graph import ATTR_OUTPUT, ATTR_SYMBOL, EPSILON
+from sofic.shifts.sliding_block_code import SlidingBlockCode
+from sofic.shifts.sofic import SoficShift
+
+
+class TextileSystem:
+    """A shared edge graph with paired input/output labels (a topological transducer)."""
+
+    def __init__(self, transducer: Any) -> None:
+        self._transducer = transducer
+
+    @classmethod
+    def from_transducer(cls, transducer: Any) -> TextileSystem:
+        """Wrap a (topological) Mealy machine as a textile system."""
+        return cls(transducer.copy())
+
+    def to_transducer(self) -> Any:
+        """Return the underlying Mealy machine."""
+        return self._transducer.copy()
+
+    def to_sofic_relation(self) -> Any:
+        """Return the product-alphabet subshift of paired labels."""
+        from sofic.shifts.sofic_relation import SoficRelation
+
+        return SoficRelation.from_transducer(self._transducer)
+
+    def input_shift(self) -> SoficShift:
+        """Return the input subshift (``p`` labeling)."""
+        return self.to_sofic_relation().input_shift()
+
+    def output_shift(self) -> SoficShift:
+        """Return the output subshift (``q`` labeling)."""
+        return self.to_sofic_relation().output_shift()
+
+    def induced_code(self, *, max_window: int = 4) -> SlidingBlockCode:
+        """Return the induced sliding block code (memory only), if it has finite window.
+
+        Searches windows of length ``1 .. max_window``; for each, the code is
+        well-defined when every readable input window determines a unique output
+        on its final position. Raises :class:`ValueError` if the input labeling is
+        not right-resolving with a finite window up to ``max_window``.
+        """
+        transducer = self._transducer
+        input_alphabet = frozenset(transducer.input_alphabet) or {
+            transition.data.get(ATTR_SYMBOL) for transition in transducer.transitions()
+        }
+        for window in range(1, max_window + 1):
+            block_map = self._window_block_map(transducer, window)
+            if block_map is not None:
+                return SlidingBlockCode(
+                    block_map,
+                    memory=window - 1,
+                    anticipation=0,
+                    input_alphabet=input_alphabet,
+                    output_alphabet={value for value in block_map.values()},
+                )
+        raise ValueError(f"no finite-memory induced code up to window {max_window}")
+
+    def _window_block_map(self, transducer: Any, window: int) -> dict[tuple[Any, ...], Any] | None:
+        # For each readable input word of `window` symbols, collect the set of
+        # possible outputs on the final edge across all paths reading that word.
+        outputs: dict[tuple[Any, ...], set[Any]] = {}
+        start_states = list(transducer.states())
+        for start in start_states:
+            queue: deque[tuple[Hashable, tuple[Any, ...], Any]] = deque([(start, (), None)])
+            while queue:
+                state, word, last_output = queue.popleft()
+                if len(word) == window:
+                    outputs.setdefault(word, set()).add(last_output)
+                    continue
+                for transition in transducer.graph.out_transitions(state):
+                    symbol = transition.data.get(ATTR_SYMBOL)
+                    if symbol is None or symbol is EPSILON:
+                        continue
+                    emitted = transition.data.get(ATTR_OUTPUT)
+                    queue.append((transition.target, (*word, symbol), emitted))
+        if not outputs:
+            return None
+        block_map: dict[tuple[Any, ...], Any] = {}
+        for word, possible in outputs.items():
+            if len(possible) != 1:
+                return None
+            value = next(iter(possible))
+            if value is None or value is EPSILON:
+                return None
+            block_map[word] = value
+        return block_map

sofic/shifts/tmc.py

@@ -0,0 +1,46 @@
+"""Topological Markov chains."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from sofic.generators.mealy import MealyHMM
+from sofic.graph import ATTR_MULTIPLICITY
+from sofic.shifts.base import SymbolicModel
+from sofic.shifts.sofic import SoficShift
+
+
+class TopologicalMarkovChain(SymbolicModel):
+    """Adjacency-matrix presentation with edge multiplicities."""
+
+    @classmethod
+    def from_adjacency(
+        cls, matrix: np.ndarray, symbol_alphabet: frozenset[Any] | None = None, **kwargs: Any
+    ) -> TopologicalMarkovChain:
+        from sofic.shifts.tmc_construction import from_adjacency
+
+        return from_adjacency(matrix, symbol_alphabet)
+
+    def to_sofic_shift(self) -> SoficShift:
+        from sofic.shifts.tmc_construction import to_sofic_shift
+
+        return to_sofic_shift(self)
+
+    def topological_entropy(self) -> float:
+        from sofic.shifts.tmc_construction import topological_entropy
+
+        return topological_entropy(self)
+
+    def validate(self) -> None:
+        super().validate()
+        for transition in self.transitions():
+            mult = transition.data.get(ATTR_MULTIPLICITY, 1)
+            self._require(isinstance(mult, (int, float)) and mult >= 1, "multiplicity must be >= 1")
+
+    def parry_measure(self) -> MealyHMM:
+        from sofic.shifts.parry_construction import parry_measure
+
+        return parry_measure(self)

sofic/shifts/tmc_construction.py

@@ -0,0 +1,58 @@
+"""TMC construction and Sofic conversion."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from sofic.graph import ATTR_MULTIPLICITY, ATTR_SYMBOL, TransitionGraph
+from sofic.shifts.algorithms import adjacency_matrix, topological_entropy_from_matrix
+from sofic.shifts.sofic import SoficShift
+from sofic.shifts.tmc import TopologicalMarkovChain
+from sofic.states import sequential_labels
+
+
+def from_adjacency(
+    matrix: np.ndarray,
+    symbol_alphabet: frozenset[Any] | None = None,
+) -> TopologicalMarkovChain:
+    arr = np.asarray(matrix, dtype=float)
+    n = arr.shape[0]
+    states = sequential_labels(n)
+    graph = TransitionGraph()
+    for state in states:
+        graph.add_state(state)
+    symbols = tuple(symbol_alphabet) if symbol_alphabet else tuple(range(n))
+    for i in range(n):
+        for j in range(n):
+            count = int(arr[i, j])
+            if count <= 0:
+                continue
+            symbol = symbols[j % len(symbols)] if symbol_alphabet else j
+            graph.add_transition(states[i], states[j], **{ATTR_SYMBOL: symbol, ATTR_MULTIPLICITY: count})
+    return TopologicalMarkovChain(
+        graph=graph,
+        symbol_alphabet=symbol_alphabet if symbol_alphabet is not None else frozenset(symbols),
+    )
+
+
+def to_sofic_shift(tmc: TopologicalMarkovChain) -> SoficShift:
+    graph = TransitionGraph()
+    for state in tmc.states():
+        graph.add_state(state)
+    for transition in tmc.transitions():
+        multiplicity = int(transition.data.get(ATTR_MULTIPLICITY, 1))
+        symbol = transition.data.get(ATTR_SYMBOL)
+        for _ in range(max(multiplicity, 1)):
+            graph.add_transition(
+                transition.source,
+                transition.target,
+                **{ATTR_SYMBOL: symbol},
+            )
+    return SoficShift(graph=graph, symbol_alphabet=tmc.symbol_alphabet)
+
+
+def topological_entropy(model: TopologicalMarkovChain | SoficShift) -> float:
+    matrix, _ = adjacency_matrix(model)
+    return topological_entropy_from_matrix(matrix)

sofic/shifts/topological_anatomy.py

@@ -0,0 +1,150 @@
+"""Topological information anatomy of a sofic shift: the MME split of ``h_top``.
+
+Topological entropy ``h_top`` is the measure-independent counterpart of the metric
+entropy ``h_mu``: by the variational principle ``h_top = sup_nu h_nu``, attained by
+the **measure of maximal entropy** (MME) -- the Parry measure of the shift
+(Parry 1964). This module evaluates the *information anatomy* (James et al. 2013)
+of the observed symbol process at that MME, giving a topological analogue of the
+``h_mu = b_mu + r_mu`` split:
+
+    h_top = b_top + r_top,   b_top := b_{mu*},   r_top := r_{mu*},
+
+where ``mu*`` is the MME. Concretely:
+
+- ``h_top = h_{mu*} = log2(lambda)`` (Perron eigenvalue of the right-resolving
+  presentation's adjacency matrix),
+- ``b_top = I[X_0 : X_{1:} | X_{:0}]`` under ``mu*`` (bound information), and
+- ``r_top = H[X_0 | X_{:0}, X_{1:}]`` under ``mu*`` -- the **erasure entropy rate**
+  (Verdu & Weissman 2008) of the MME (ephemeral information).
+
+Because the MME and the observed symbol process are intrinsic to the sofic shift,
+``b_top`` and ``r_top`` are functions of the shift space (up to alphabet
+relabeling / 1-block conjugacy), refining ``h_top`` the way ``b_mu`` / ``r_mu``
+refine ``h_mu``. They are exact: the MME is a finite Markov chain on the
+presentation, so the bidirectional-epsilon-machine anatomy is closed-form (no
+Monte-Carlo, no finite-block truncation).
+
+Pipeline (see :func:`topological_anatomy`):
+
+1. Put the presentation in right-resolving (unifilar) form
+   (:func:`_right_resolving`) -- required so ``h_top`` is exact rather than the
+   path-overcount of a nondeterministic presentation.
+2. Build the Parry MME as a labeled :class:`~sofic.generators.mealy.MealyHMM`
+   (:func:`parry_measure_sofic`).
+3. Minimize to the causal presentation
+   (:meth:`~sofic.generators.epsilon_machine.EpsilonMachine.from_hmm`), pair it
+   with its time reverse
+   (:meth:`~sofic.generators.epsilon_machine.EpsilonMachine.to_bidirectional`),
+   and read the anatomy
+   (:meth:`~sofic.generators.bidirectional_epsilon_machine.BidirectionalEpsilonMachine.information_anatomy`).
+
+References: Parry (1964), *Intrinsic Markov chains*; James, Ellison & Crutchfield
+(2013), *Anatomy of a bit*; Verdu & Weissman (2008), *The information lost in
+erasures*.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sofic.exceptions import UnifilarityError
+from sofic.graph import ATTR_SYMBOL
+
+if TYPE_CHECKING:
+    from sofic.generators.mealy import MealyHMM
+    from sofic.shifts.sofic import SoficShift
+
+
+def _dedup_symbol_edges(shift: SoficShift) -> SoficShift:
+    """Return a copy of ``shift`` with duplicate ``(source, target, symbol)`` edges merged.
+
+    The Fischer-cover construction maps every original transition onto a
+    follower-class edge without deduplication, so merging classes can create
+    several identical ``(source, target, symbol)`` edges. Those are the *same*
+    labeled edge and must be counted once for the adjacency/Perron entropy to be
+    correct; genuine right-resolving parallelism (same ``(source, target)``,
+    *different* symbols) is preserved.
+    """
+    from sofic.shifts.sofic import SoficShift
+
+    result = SoficShift(symbol_alphabet=shift.symbol_alphabet)
+    for state in shift.states():
+        result.graph.add_state(state)
+    seen: set[tuple[object, object, object]] = set()
+    for transition in shift.transitions():
+        symbol = transition.data.get(ATTR_SYMBOL)
+        key = (transition.source, transition.target, symbol)
+        if key in seen:
+            continue
+        seen.add(key)
+        result.add_transition(transition.source, transition.target, symbol)
+    return result
+
+
+def _right_resolving(shift: SoficShift) -> SoficShift:
+    """Return a right-resolving (unifilar) presentation of ``shift``.
+
+    If ``shift`` is already unifilar it is returned unchanged. Otherwise the right
+    Fischer cover (:meth:`~sofic.shifts.covers.RightFischerCover.from_sofic`) is
+    built and its duplicate labeled edges merged (:func:`_dedup_symbol_edges`).
+    The cover construction uses a bounded follower language, so it is not
+    guaranteed to determinize every presentation; if the result is still not
+    unifilar a :class:`~sofic.exceptions.UnifilarityError` is raised asking for a
+    right-resolving input.
+    """
+    if shift.is_unifilar():
+        return shift
+    from sofic.shifts.covers import RightFischerCover
+
+    cover = _dedup_symbol_edges(RightFischerCover.from_sofic(shift))
+    if not cover.is_unifilar():
+        raise UnifilarityError(
+            "could not derive a right-resolving presentation of the sofic shift "
+            "automatically; supply a unifilar (right-resolving) SoficShift"
+        )
+    return cover
+
+
+def parry_measure_sofic(shift: SoficShift) -> MealyHMM:
+    """Return the measure of maximal entropy (Parry measure) as a labeled MealyHMM.
+
+    Puts ``shift`` in right-resolving form (:func:`_right_resolving`) and builds
+    the Parry chain ``P[i, j] = A[i, j] v_j / (lambda v_i)`` with stationary
+    ``pi ~ u * v`` from the Perron data of the adjacency matrix ``A`` (Parry 1964),
+    preserving each edge's emitted symbol. Its entropy rate is
+    ``log2(lambda) = h_top`` and its observed process is the shift's MME symbol
+    process.
+    """
+    from sofic.shifts.parry_construction import parry_measure
+
+    return parry_measure(_right_resolving(shift))
+
+
+def topological_anatomy(shift: SoficShift) -> dict[str, float]:
+    """Return the topological information anatomy ``{h_top, b_top, r_top, excess_entropy}``.
+
+    Evaluates the metric anatomy (James et al. 2013) of the observed symbol
+    process at the measure of maximal entropy (:func:`parry_measure_sofic`):
+
+    - ``h_top`` -- topological entropy ``= log2(lambda)`` (the MME entropy rate),
+    - ``b_top`` -- MME bound information ``I[X_0 : X_{1:} | X_{:0}]``,
+    - ``r_top`` -- MME ephemeral information ``H[X_0 | X_{:0}, X_{1:}]`` (the MME
+      erasure entropy rate, Verdu & Weissman 2008),
+    - ``excess_entropy`` -- MME excess entropy ``E = I[past : future]``,
+
+    with ``h_top = b_top + r_top`` exactly. Requires ``dit`` for the anatomy
+    entropies.
+    """
+    from sofic.generators.epsilon_machine import EpsilonMachine
+
+    parry = parry_measure_sofic(shift)
+    if not list(parry.states()):
+        return {"h_top": 0.0, "b_top": 0.0, "r_top": 0.0, "excess_entropy": 0.0}
+
+    anatomy = EpsilonMachine.from_hmm(parry).information_anatomy()
+    return {
+        "h_top": float(anatomy["entropy_rate"]),
+        "b_top": float(anatomy["bound_mu"]),
+        "r_top": float(anatomy["ephemeral_mu"]),
+        "excess_entropy": float(anatomy["excess_entropy"]),
+    }

sofic/states.py

@@ -0,0 +1,27 @@
+"""Sequential capital-letter state labels (A, B, C, ...)."""
+
+from __future__ import annotations
+
+from collections.abc import Hashable, Iterable
+
+
+def sequential_labels(count: int, *, start: int = 0) -> tuple[str, ...]:
+    """Return ``count`` state labels starting at ``chr(ord('A') + start)``."""
+    if count < 0:
+        raise ValueError("count must be non-negative")
+    if start < 0 or start + count > 26:
+        raise ValueError("sequential_labels supports at most 26 states A–Z")
+    return tuple(chr(ord("A") + start + index) for index in range(count))
+
+
+def letter_label_index(label: Hashable) -> int | None:
+    """Map a single capital letter ``A``–``Z`` to 0–25, else ``None``."""
+    if isinstance(label, str) and len(label) == 1 and "A" <= label <= "Z":
+        return ord(label) - ord("A")
+    return None
+
+
+def next_sequential_label_index(existing: Iterable[Hashable]) -> int:
+    """Index of the next unused capital letter after ``existing`` labels."""
+    indices = [index for item in existing if (index := letter_label_index(item)) is not None]
+    return max(indices, default=-1) + 1

sofic/testing/__init__.py

@@ -0,0 +1,8 @@
+"""Optional Hypothesis strategies for sofic models."""
+
+from sofic.testing.strategies import dfas, epsilon_machines
+
+__all__ = [
+    "dfas",
+    "epsilon_machines",
+]

sofic/testing/strategies.py

@@ -0,0 +1,154 @@
+"""Hypothesis strategies for sofic models.
+
+These helpers live outside the main package imports so Hypothesis remains a
+test-only dependency. Install ``sofic[test]`` to use them.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from functools import cache
+from typing import Any
+
+from sofic.automata.dfa import DFA
+from sofic.automata.icdfa import icdfa_string_to_dfa, iter_icdfa_empty_strings
+from sofic.generators.epsilon_machine import EpsilonMachine
+from sofic.generators.topological_epsilon_enumeration import (
+    idfa_string_to_epsilon_machine,
+    iter_topological_epsilon_strings,
+)
+
+DEFAULT_ALPHABET = ("0", "1")
+
+
+def dfas(
+    *,
+    alphabet: Sequence[Any] = DEFAULT_ALPHABET,
+    min_states: int = 1,
+    max_states: int = 3,
+) -> Any:
+    """Return a strategy for complete initially-connected DFAs.
+
+    The DFA transition structures are drawn from the canonical ICDFA
+    enumeration, and accepting states are drawn independently.
+    """
+    st = _hypothesis_strategies()
+    symbols = _validate_alphabet(alphabet)
+    _validate_state_bounds(min_states=min_states, max_states=max_states)
+    k = len(symbols)
+
+    @st.composite
+    def strategy(draw: Any) -> DFA:
+        n = draw(st.integers(min_value=min_states, max_value=max_states))
+        transitions = draw(st.sampled_from(_icdfa_transition_strings(k, n)))
+        final_states = draw(st.frozensets(st.integers(min_value=0, max_value=n - 1)))
+        return icdfa_string_to_dfa(
+            transitions,
+            symbols,
+            n=n,
+            k=k,
+            final_states=final_states,
+            symbol_order=symbols,
+        )
+
+    return strategy()
+
+
+def epsilon_machines(
+    *,
+    alphabet: Sequence[Any] = DEFAULT_ALPHABET,
+    min_states: int = 1,
+    max_states: int = 3,
+    max_pool: int | None = None,
+) -> Any:
+    """Return a strategy for topological epsilon-machines.
+
+    Machines are drawn from the canonical topological epsilon-machine
+    enumeration and use the enumeration module's uniform row probabilities.
+
+    When ``max_pool`` is set, only the first ``max_pool`` enumerated transition
+    strings per ``(k, n)`` are retained.  Use this for large alphabets (e.g.
+    ``k = 3``) where the full enumeration is infeasible.
+    """
+    st = _hypothesis_strategies()
+    symbols = _validate_alphabet(alphabet)
+    _validate_state_bounds(min_states=min_states, max_states=max_states)
+    if max_pool is not None and max_pool < 1:
+        raise ValueError("max_pool must be positive when provided")
+    k = len(symbols)
+    state_counts: tuple[int, ...] = ()
+    for n in range(min_states, max_states + 1):
+        if max_pool is not None:
+            pool = _bounded_topological_epsilon_transition_strings(k, n, max_pool)
+        else:
+            pool = _topological_epsilon_transition_strings(k, n)
+        if pool:
+            state_counts += (n,)
+    if not state_counts:
+        raise ValueError("no topological epsilon-machine strings exist for the requested bounds")
+
+    @st.composite
+    def strategy(draw: Any) -> EpsilonMachine:
+        n = draw(st.sampled_from(state_counts))
+        if max_pool is not None:
+            pool = _bounded_topological_epsilon_transition_strings(k, n, max_pool)
+        else:
+            pool = _topological_epsilon_transition_strings(k, n)
+        transitions = draw(st.sampled_from(pool))
+        return idfa_string_to_epsilon_machine(transitions, n=n, k=k, alphabet=symbols)
+
+    return strategy()
+
+
+def _hypothesis_strategies() -> Any:
+    try:
+        from hypothesis import strategies as st
+    except ImportError as exc:  # pragma: no cover - exercised only without test extra
+        raise ImportError("sofic.testing.strategies requires Hypothesis; install sofic[test].") from exc
+    return st
+
+
+def _validate_alphabet(alphabet: Sequence[Any]) -> tuple[Any, ...]:
+    symbols = tuple(alphabet)
+    if not symbols:
+        raise ValueError("alphabet must be non-empty")
+    try:
+        unique = frozenset(symbols)
+    except TypeError as exc:
+        raise ValueError("alphabet symbols must be hashable") from exc
+    if len(unique) != len(symbols):
+        raise ValueError("alphabet symbols must be unique")
+    return symbols
+
+
+def _validate_state_bounds(*, min_states: int, max_states: int) -> None:
+    if min_states < 1:
+        raise ValueError("min_states must be positive")
+    if max_states < 1:
+        raise ValueError("max_states must be positive")
+    if min_states > max_states:
+        raise ValueError("min_states must be less than or equal to max_states")
+
+
+@cache
+def _icdfa_transition_strings(k: int, n: int) -> tuple[tuple[int, ...], ...]:
+    return tuple(iter_icdfa_empty_strings(k, n))
+
+
+@cache
+def _topological_epsilon_transition_strings(k: int, n: int) -> tuple[tuple[int, ...], ...]:
+    return tuple(iter_topological_epsilon_strings(k, n))
+
+
+@cache
+def _bounded_topological_epsilon_transition_strings(
+    k: int,
+    n: int,
+    max_pool: int,
+) -> tuple[tuple[int, ...], ...]:
+    pool: list[tuple[int, ...]] = []
+    for transitions in iter_topological_epsilon_strings(k, n):
+        pool.append(tuple(transitions))
+        if len(pool) >= max_pool:
+            break
+    return tuple(pool)

sofic/viz/__init__.py

@@ -0,0 +1,16 @@
+"""Visualization for sofic models (Graphviz, TikZ, information diagrams)."""
+
+from sofic.viz.graphviz import draw, model_to_graphviz, model_to_svg
+from sofic.viz.idiagram import plot_information_diagram
+from sofic.viz.tikz import compile_tikz, draw_tikz, model_to_tikz, model_to_tikz_image
+
+__all__ = [
+    "compile_tikz",
+    "draw",
+    "draw_tikz",
+    "model_to_graphviz",
+    "model_to_svg",
+    "model_to_tikz",
+    "model_to_tikz_image",
+    "plot_information_diagram",
+]