sofic 0.1.0__py3-none-any.whl

sofic/examples/shifts.py

@@ -0,0 +1,144 @@
+"""Constructors for canonical symbolic-shift examples."""
+
+from __future__ import annotations
+
+from collections.abc import Hashable, Sequence
+
+from sofic.shifts.sofic_dyck import SoficDyckShift
+
+
+def dyck_shift_order(
+    k: int = 2,
+    *,
+    call_symbols: Sequence[Hashable] | None = None,
+    return_symbols: Sequence[Hashable] | None = None,
+) -> SoficDyckShift:
+    """Dyck shift of order ``k`` from Beal, Blockelet & Dima, Example 1.
+
+    The default symbols follow the paper's notation:
+    ``A_c = {a1, ..., ak}`` and ``A_r = {b1, ..., bk}``.
+    """
+    if k < 1:
+        raise ValueError("k must be >= 1")
+    calls = tuple(call_symbols) if call_symbols is not None else tuple(f"a{i}" for i in range(1, k + 1))
+    returns = tuple(return_symbols) if return_symbols is not None else tuple(f"b{i}" for i in range(1, k + 1))
+    if len(calls) != k or len(returns) != k:
+        raise ValueError("call_symbols and return_symbols must have length k")
+
+    return _one_state_dyck_shift(calls, returns, ())
+
+
+def motzkin_shift(
+    call_symbols: Sequence[Hashable] = ("(", "["),
+    return_symbols: Sequence[Hashable] = (")", "]"),
+    internal_symbols: Sequence[Hashable] = ("i",),
+) -> SoficDyckShift:
+    """Motzkin shift shown on the left of Beal, Blockelet & Dima, Fig. 1."""
+    return _one_state_dyck_shift(tuple(call_symbols), tuple(return_symbols), tuple(internal_symbols))
+
+
+def sofic_dyck_fig1_shift() -> SoficDyckShift:
+    """Two-state sofic-Dyck shift shown on the right of Beal, Blockelet & Dima, Fig. 1."""
+    shift = SoficDyckShift(
+        call_alphabet=frozenset({"(", "["}),
+        return_alphabet=frozenset({")", "]"}),
+        internal_alphabet=frozenset({"i"}),
+    )
+    shift.graph.add_state("1")
+    shift.graph.add_state("2")
+
+    left_paren = shift.add_call_transition("1", "1", "(")
+    left_bracket = shift.add_call_transition("1", "1", "[")
+    right_paren = shift.add_return_transition("1", "1", ")")
+    right_bracket = shift.add_return_transition("1", "1", "]")
+    shift.add_internal_transition("1", "2", "i")
+    shift.add_internal_transition("2", "1", "i")
+
+    shift.add_matched_pair(left_paren, right_paren)
+    shift.add_matched_pair(left_bracket, right_bracket)
+    return shift
+
+
+def sofic_dyck_nondeterminizable_shift() -> SoficDyckShift:
+    """Sofic-Dyck shift with no deterministic presentation from Beal et al., Fig. 3."""
+    shift = SoficDyckShift(
+        call_alphabet=frozenset({"a"}),
+        return_alphabet=frozenset({"b"}),
+        internal_alphabet=frozenset({"i", "j", "k"}),
+    )
+    for state in ("1", "2", "3"):
+        shift.graph.add_state(state)
+
+    call = shift.add_call_transition("1", "1", "a")
+    return_2 = shift.add_return_transition("2", "2", "b")
+    shift.add_return_transition("3", "3", "b")
+    shift.add_internal_transition("1", "2", "i")
+    shift.add_internal_transition("2", "1", "j")
+    shift.add_internal_transition("1", "3", "i")
+    shift.add_internal_transition("3", "1", "k")
+
+    shift.add_matched_pair(call, return_2)
+    return shift
+
+
+def sofic_dyck_zeta_example_shift() -> SoficDyckShift:
+    """Sofic-Dyck shift used in Beal, Blockelet & Dima's zeta-function example."""
+    shift = SoficDyckShift(
+        call_alphabet=frozenset({"a", "a'"}),
+        return_alphabet=frozenset({"b", "b'"}),
+        internal_alphabet=frozenset({"i"}),
+    )
+    shift.graph.add_state("1")
+    shift.graph.add_state("2")
+
+    return_b = shift.add_return_transition("1", "1", "b")
+    call_a = shift.add_call_transition("1", "1", "a")
+    call_a_prime = shift.add_call_transition("1", "1", "a'")
+    return_b_prime = shift.add_return_transition("1", "1", "b'")
+    shift.add_internal_transition("1", "2", "i")
+    shift.add_internal_transition("2", "1", "i")
+
+    shift.add_matched_pair(call_a, return_b)
+    shift.add_matched_pair(call_a_prime, return_b_prime)
+    return shift
+
+
+def _one_state_dyck_shift(
+    call_symbols: tuple[Hashable, ...],
+    return_symbols: tuple[Hashable, ...],
+    internal_symbols: tuple[Hashable, ...],
+) -> SoficDyckShift:
+    if len(call_symbols) != len(return_symbols):
+        raise ValueError("call_symbols and return_symbols must have the same length")
+    _require_disjoint(call_symbols, return_symbols, internal_symbols)
+
+    shift = SoficDyckShift(
+        call_alphabet=frozenset(call_symbols),
+        return_alphabet=frozenset(return_symbols),
+        internal_alphabet=frozenset(internal_symbols),
+    )
+    state = "1"
+    shift.graph.add_state(state)
+
+    call_refs = {symbol: shift.add_call_transition(state, state, symbol) for symbol in call_symbols}
+    return_refs = {symbol: shift.add_return_transition(state, state, symbol) for symbol in return_symbols}
+    for symbol in internal_symbols:
+        shift.add_internal_transition(state, state, symbol)
+    for call_symbol, return_symbol in zip(call_symbols, return_symbols, strict=True):
+        shift.add_matched_pair(call_refs[call_symbol], return_refs[return_symbol])
+    return shift
+
+
+def _require_disjoint(*symbol_groups: tuple[Hashable, ...]) -> None:
+    symbols = tuple(symbol for group in symbol_groups for symbol in group)
+    if len(frozenset(symbols)) != len(symbols):
+        raise ValueError("call, return, and internal symbols must be distinct")
+
+
+__all__ = [
+    "dyck_shift_order",
+    "motzkin_shift",
+    "sofic_dyck_fig1_shift",
+    "sofic_dyck_nondeterminizable_shift",
+    "sofic_dyck_zeta_example_shift",
+]

sofic/exceptions.py

@@ -0,0 +1,33 @@
+"""Exceptions raised by sofic."""
+
+
+class SoficError(Exception):
+    """Base class for sofic errors."""
+
+
+class SoficValidationError(SoficError):
+    """Raised when a model fails structural or semantic validation."""
+
+
+class NonDeterministicError(SoficValidationError):
+    """Raised when a DFA determinism invariant is violated."""
+
+
+class StochasticValidationError(SoficValidationError):
+    """Raised when probability masses are invalid."""
+
+
+class UnifilarityError(SoficValidationError):
+    """Raised when a unifilarity invariant is violated."""
+
+
+class QuasiStochasticValidationError(SoficValidationError):
+    """Raised when quasi-stochastic invariants are violated."""
+
+
+class LumpabilityError(SoficValidationError):
+    """Raised when a partition is not strongly lumpable for a model."""
+
+
+class InfiniteTransductionError(SoficError):
+    """Raised when a finite input has infinitely many transducer outputs."""

sofic/generators/__init__.py

@@ -0,0 +1,115 @@
+"""Stochastic and quasiprobabilistic generators."""
+
+from sofic.generators.base import HiddenMarkovModel, QuasiStochasticModel, StochasticModel
+from sofic.generators.bidirectional_epsilon_machine import BidirectionalEpsilonMachine
+from sofic.generators.block_convergence import BlockConvergenceDiagram, BlockConvergenceEstimates
+from sofic.generators.block_entropy import BlockEntropyDiagram, BlockEntropyEstimates
+from sofic.generators.channel_measures import (
+    channel_statistical_complexity,
+    driven_entropy_rate,
+)
+from sofic.generators.directional_flow import (
+    directed_information,
+    independent_pair_generator,
+    intrinsic_information_flow,
+    shared_information_flow,
+    synergistic_information_flow,
+    transfer_entropy,
+)
+from sofic.generators.epsilon_inference import cssr, spectral, subtree_merge
+from sofic.generators.epsilon_machine import EpsilonMachine
+from sofic.generators.epsilon_transducer import EpsilonTransducer
+from sofic.generators.lumping import LumpabilityError, is_lumpable, lump, normalize_partition
+from sofic.generators.markov import MarkovChain
+from sofic.generators.mealy import MealyHMM
+from sofic.generators.minimal_generative_model import (
+    FunctionalGenerativeModel,
+    GacsKornerGenerativeModel,
+    MinimalGenerativeModel,
+    WynerGenerativeModel,
+    functional_generative_model,
+    gacs_korner_generative_model,
+    minimal_generative_model,
+    wyner_generative_model,
+)
+from sofic.generators.mixed_state import MixedState, MixedStatePresentation
+from sofic.generators.moore import MooreHMM
+from sofic.generators.nmachine import NMachine
+from sofic.generators.pfa import ProbabilisticFiniteAutomaton
+from sofic.generators.quasi_realization import QuasiRealization
+from sofic.generators.stack_hmm import HiddenMarkovStackModel
+from sofic.generators.stack_inference import (
+    fit_stack_hmm_mle,
+    learn_stack_hmm_papni,
+    stack_cssr,
+    stack_subtree_merge,
+)
+from sofic.generators.topological_epsilon_enumeration import (
+    count_topological_epsilon_machines,
+    epsilon_machine_to_idfa_string,
+    idfa_string_to_epsilon_machine,
+    is_canonical_topological_epsilon,
+    is_minimal_idfa,
+    is_strongly_connected_idfa,
+    is_topological_epsilon_string,
+    iter_topological_epsilon_machines,
+    iter_topological_epsilon_strings,
+)
+
+__all__ = [
+    "BidirectionalEpsilonMachine",
+    "BlockEntropyDiagram",
+    "BlockEntropyEstimates",
+    "BlockConvergenceDiagram",
+    "BlockConvergenceEstimates",
+    "EpsilonMachine",
+    "EpsilonTransducer",
+    "LumpabilityError",
+    "channel_statistical_complexity",
+    "driven_entropy_rate",
+    "cssr",
+    "is_lumpable",
+    "lump",
+    "normalize_partition",
+    "spectral",
+    "subtree_merge",
+    "fit_stack_hmm_mle",
+    "learn_stack_hmm_papni",
+    "stack_cssr",
+    "stack_subtree_merge",
+    "directed_information",
+    "independent_pair_generator",
+    "intrinsic_information_flow",
+    "shared_information_flow",
+    "synergistic_information_flow",
+    "transfer_entropy",
+    "FunctionalGenerativeModel",
+    "GacsKornerGenerativeModel",
+    "HiddenMarkovModel",
+    "HiddenMarkovStackModel",
+    "MarkovChain",
+    "MealyHMM",
+    "MinimalGenerativeModel",
+    "MixedState",
+    "MixedStatePresentation",
+    "MooreHMM",
+    "NMachine",
+    "ProbabilisticFiniteAutomaton",
+    "QuasiRealization",
+    "QuasiStochasticModel",
+    "StochasticModel",
+    "WynerGenerativeModel",
+    "count_topological_epsilon_machines",
+    "epsilon_machine_to_idfa_string",
+    "functional_generative_model",
+    "gacs_korner_generative_model",
+    "idfa_string_to_epsilon_machine",
+    "is_canonical_topological_epsilon",
+    "is_minimal_idfa",
+    "is_strongly_connected_idfa",
+    "is_topological_epsilon_string",
+    "iter_topological_epsilon_machines",
+    "iter_topological_epsilon_strings",
+    "minimal_generative_model",
+    "wyner_generative_model",
+]

sofic/generators/_word_measures.py

@@ -0,0 +1,94 @@
+"""Dit-backed word-distribution measures for block curves.
+
+Leaf module shared by :mod:`sofic.generators.block_entropy` and
+:mod:`sofic.generators.block_convergence`.  It depends only on ``dit`` (via
+:func:`sofic.generators.measures.require_dit`) and must not import either
+block module, so that both can depend on it without a circular import.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from sofic.generators.epsilon_machine import EpsilonMachine
+
+_TOL = 1e-15
+
+
+def _require_dit() -> Any:
+    from sofic.generators.measures import require_dit
+
+    return require_dit("block convergence measures")
+
+
+def _positional_rvs(length: int) -> list[list[int]]:
+    return [[index] for index in range(length)]
+
+
+def _word_distribution(distribution: dict[tuple[Any, ...], float]) -> Any:
+    dit = _require_dit()
+    if not distribution:
+        return dit.Distribution([()], [1.0])
+    total = sum(float(prob) for prob in distribution.values())
+    if total <= _TOL:
+        return dit.Distribution([()], [1.0])
+    outcomes = list(distribution.keys())
+    probs = [float(distribution[outcome]) / total for outcome in outcomes]
+    dist = dit.Distribution(outcomes, probs)
+    dist.set_rv_names([f"X_{index}" for index in range(len(outcomes[0]))])
+    return dist
+
+
+def _block_word_distribution(machine: EpsilonMachine, length: int) -> Any:
+    if length == 0:
+        dit = _require_dit()
+        return dit.Distribution([()], [1.0])
+    return _word_distribution(machine.word_probabilities(length))
+
+
+def _block_total_correlation(dist: Any, length: int, block_entropy: float, h1: float) -> float:
+    if length <= 1:
+        return 0.0
+    _require_dit()
+    from dit.multivariate import total_correlation
+
+    return float(total_correlation(dist, rvs=_positional_rvs(length)))
+
+
+def _block_residual_entropy(dist: Any, length: int) -> float:
+    if length == 0:
+        return 0.0
+    _require_dit()
+    from dit.multivariate import residual_entropy
+
+    return float(residual_entropy(dist, rvs=_positional_rvs(length)))
+
+
+def _block_coinformation(dist: Any, length: int, block_entropy: float) -> float:
+    if length <= 1:
+        return 0.0
+    _require_dit()
+    from dit.multivariate import coinformation
+
+    return float(coinformation(dist, rvs=_positional_rvs(length)))
+
+
+def _block_caekl(dist: Any, length: int) -> float:
+    if length <= 1:
+        return 0.0
+    _require_dit()
+    from dit.multivariate import caekl_mutual_information
+
+    return float(caekl_mutual_information(dist, rvs=_positional_rvs(length)))
+
+
+def residual_entropy_from_distribution(distribution: dict[tuple[Any, ...], float]) -> float:
+    """Dit-backed residual entropy for a word distribution."""
+    if not distribution:
+        return 0.0
+    length = len(next(iter(distribution)))
+    if length == 0:
+        return 0.0
+    dist = _word_distribution(distribution)
+    return _block_residual_entropy(dist, length)

sofic/generators/alternative_complexity.py

@@ -0,0 +1,104 @@
+"""Alternative complexity measures for epsilon-machines."""
+
+from __future__ import annotations
+
+import math
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from sofic.generators.stochastic import shannon_entropy
+from sofic.graph import ATTR_PROB
+from sofic.properties import transition_matrix
+
+if TYPE_CHECKING:
+    from sofic.generators.epsilon_machine import EpsilonMachine
+
+
+def structural_information(machine: EpsilonMachine) -> float:
+    """Asymptotic structural information (equals excess entropy for finite-state sources).
+
+    For a canonical epsilon-machine, :math:`I_{\\mathrm{struct}} = \\lim_{L\\to\\infty}
+    H[S_L \\mid X_{0:L}] = E` (Feldman & Crutchfield, 1998; Ellison et al., 2009).
+    """
+    return machine.excess_entropy()
+
+
+def thermodynamic_depth(machine: EpsilonMachine) -> float:
+    """Thermodynamic depth: stationary average mean first-passage time to causal states.
+
+    Uses the hidden-state transition matrix (summing over emissions) and the
+    stationary causal-state distribution (Shalizi & Crutchfield, 1999).
+    """
+    pi = machine.stationary_distribution()
+    states = list(machine.states())
+    if not states:
+        return 0.0
+    index = {state: i for i, state in enumerate(states)}
+    n = len(states)
+    transition, _ = transition_matrix(machine, attr=ATTR_PROB, states=states)
+
+    pi_vec = np.asarray([pi[index[state]] for state in states], dtype=float)
+    pi_vec = pi_vec / pi_vec.sum()
+
+    depths = np.zeros(n, dtype=float)
+    for target in range(n):
+        depths[target] = _mean_first_passage_time(transition, pi_vec, target)
+
+    return float(np.dot(pi_vec, depths))
+
+
+def spectral_complexity(machine: EpsilonMachine) -> float:
+    """Spectral entropy of nontrivial mixed-state transition eigenvalues.
+
+    Builds the recurrent mixed-state presentation and summarizes the modulus
+    spectrum of its transition operator (Riechers & Crutchfield, 2017).
+    """
+    from sofic.generators.mixed_state_construction import build_mixed_state_presentation
+
+    msp = build_mixed_state_presentation(machine)
+    states = tuple(msp.recurrent_states)
+    if len(states) <= 1:
+        return 0.0
+
+    matrix, _ = transition_matrix(msp, attr=ATTR_PROB, states=states)
+
+    eigenvalues = np.linalg.eigvals(matrix)
+    moduli = np.sort(np.abs(eigenvalues))[::-1]
+    nontrivial = moduli[moduli < 1.0 - 1e-9]
+    if nontrivial.size == 0:
+        return 0.0
+    weights = nontrivial / nontrivial.sum()
+    return shannon_entropy(weights)
+
+
+def _mean_first_passage_time(transition: np.ndarray, start: np.ndarray, target: int) -> float:
+    n = transition.shape[0]
+    if n == 0:
+        return 0.0
+    if n == 1:
+        return 0.0
+
+    # Fundamental-matrix formula for MFPT from i to j.
+    pi = _stationary_vector(transition)
+    if pi is None:
+        pi = np.ones(n) / n
+    fundamental = np.linalg.inv(np.eye(n) - transition + np.outer(np.ones(n), pi))
+    mfpt = np.zeros(n, dtype=float)
+    for i in range(n):
+        if i == target:
+            mfpt[i] = 0.0
+        elif pi[target] <= 0.0:
+            mfpt[i] = math.inf
+        else:
+            mfpt[i] = (fundamental[target, target] - fundamental[i, target]) / pi[target]
+    return float(start @ mfpt)
+
+
+def _stationary_vector(transition: np.ndarray) -> np.ndarray | None:
+    from sofic.generators.stationary import stationary_distribution_from_transition
+
+    try:
+        return stationary_distribution_from_transition(transition)
+    except Exception:
+        return None