sofic 0.1.0__py3-none-any.whl

sofic/generators/conversions.py

@@ -0,0 +1,182 @@
+"""Generator presentation conversions."""
+
+from __future__ import annotations
+
+from collections.abc import Hashable
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from sofic.generators.synchronization import TopologicalUnifilarGraph
+
+from sofic.automata.dfa import DFA
+from sofic.automata.nfa import NFA
+from sofic.generators.base import HiddenMarkovModel
+from sofic.generators.mealy import MealyHMM
+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.graph import (
+    ATTR_EMISSION,
+    ATTR_EMISSION_DIST,
+    ATTR_PROB,
+    ATTR_QUASIPROB,
+    ATTR_SYMBOL,
+    EPSILON,
+    TransitionGraph,
+)
+from sofic.shifts.sofic import SoficShift
+from sofic.states import sequential_labels
+
+
+def moore_to_mealy(moore: MooreHMM) -> MealyHMM:
+    """Convert Moore HMM to Mealy with joint P(q', o | q) on departure state."""
+    graph = TransitionGraph()
+    for state in moore.states():
+        graph.add_state(state)
+    for transition in moore.transitions():
+        source = transition.source
+        target = transition.target
+        trans_prob = float(transition.data.get(ATTR_PROB, 0.0))
+        emission_dist = moore.graph.state_attrs(source).get(ATTR_EMISSION_DIST, {})
+        for emission, emit_prob in emission_dist.items():
+            joint = trans_prob * float(emit_prob)
+            if joint > 0.0:
+                graph.add_transition(
+                    source,
+                    target,
+                    **{ATTR_PROB: joint, ATTR_EMISSION: emission},
+                )
+    return MealyHMM(
+        graph=graph,
+        initial_distribution=moore.initial_distribution,
+        observation_alphabet=moore.observation_alphabet,
+    )
+
+
+def pfa_to_mealy(pfa: ProbabilisticFiniteAutomaton) -> MealyHMM:
+    graph = pfa.graph.copy()
+    return MealyHMM(
+        graph=graph,
+        initial_distribution=pfa.initial_distribution,
+        observation_alphabet=frozenset(pfa.output_alphabet),
+    )
+
+
+def hmm_to_sofic_shift(hmm: HiddenMarkovModel) -> SoficShift:
+    """Strip probabilities from an HMM and keep its labeled support."""
+    support = _mealy_support(hmm)
+    graph = _support_graph(support, edge_attr=ATTR_SYMBOL)
+    return SoficShift(graph=graph, symbol_alphabet=support.observation_alphabet)
+
+
+def hmm_to_support_nfa(hmm: HiddenMarkovModel) -> NFA:
+    """Build an NFA whose language is the finite-word support of an HMM."""
+    support = _mealy_support(hmm)
+    graph = _support_graph(support, edge_attr=ATTR_SYMBOL)
+    states = frozenset(support.states())
+    start = _fresh_start_state(states)
+    graph.add_state(start)
+    for state in states:
+        graph.add_transition(start, state, **{ATTR_SYMBOL: EPSILON})
+    return NFA(
+        graph=graph,
+        input_alphabet=support.observation_alphabet,
+        initial_states=frozenset({start}),
+        accepting_states=states,
+    )
+
+
+def hmm_to_support_dfa(hmm: HiddenMarkovModel) -> DFA:
+    """Determinize the HMM support NFA from the all-states subset."""
+    support = _mealy_support(hmm)
+    states = frozenset(support.states())
+    nfa = hmm_to_support_nfa(support)
+    nfa.initial_states = states
+
+    dfa = nfa.determinize(alphabet=support.observation_alphabet)
+    empty_subset = frozenset()
+    if dfa.graph.has_state(empty_subset):
+        dfa.graph.nx.remove_node(empty_subset)
+    dfa.accepting_states = dfa.graph.terminal_recurrent_states()
+    return dfa
+
+
+def _mealy_support(hmm: HiddenMarkovModel) -> MealyHMM:
+    return hmm.to_mealy()
+
+
+def _support_graph(hmm: MealyHMM, *, edge_attr: str) -> TransitionGraph:
+    graph = TransitionGraph()
+    for state in hmm.states():
+        graph.add_state(state)
+    for transition in hmm.transitions():
+        prob = float(transition.data.get(ATTR_PROB, 0.0))
+        emission = transition.data.get(ATTR_EMISSION)
+        if prob <= 0.0 or emission is None:
+            continue
+        graph.add_transition(transition.source, transition.target, **{edge_attr: emission})
+    return graph
+
+
+def _fresh_start_state(states: frozenset[Hashable]) -> Hashable:
+    start: Hashable = ("__sofic_hmm_start__",)
+    suffix = 0
+    while start in states:
+        suffix += 1
+        start = ("__sofic_hmm_start__", suffix)
+    return start
+
+
+def quasi_realization_from_nmachine(nm: NMachine) -> QuasiRealization:
+    idx = nm.reindex()
+    pi = np.array([nm.initial_quasidistribution.get(s, 0.0) for s in idx.states], dtype=float)
+    tau = np.ones(len(idx), dtype=float)
+    symbol_maps: dict[Any, np.ndarray] = {}
+    for transition in nm.transitions():
+        emission = transition.data.get(ATTR_EMISSION)
+        if emission is None:
+            continue
+        matrix = symbol_maps.setdefault(emission, np.zeros((len(idx), len(idx)), dtype=float))
+        i = idx.index(transition.source)
+        j = idx.index(transition.target)
+        matrix[i, j] += float(transition.data.get(ATTR_QUASIPROB, 0.0))
+    return QuasiRealization(pi=pi, tau=tau, symbol_maps=symbol_maps)
+
+
+def nmachine_from_quasi_realization(
+    qr: QuasiRealization, observation_alphabet: frozenset[Any] | None = None
+) -> NMachine:
+    states = sequential_labels(len(qr.pi))
+    graph = TransitionGraph()
+    for state in states:
+        graph.add_state(state)
+    alphabet = observation_alphabet if observation_alphabet is not None else frozenset(qr.symbol_maps)
+    for symbol, matrix in qr.symbol_maps.items():
+        for i in range(matrix.shape[0]):
+            for j in range(matrix.shape[1]):
+                weight = float(matrix[i, j])
+                if weight != 0.0:
+                    graph.add_transition(states[i], states[j], **{ATTR_QUASIPROB: weight, ATTR_EMISSION: symbol})
+    initial = {states[i]: float(qr.pi[i]) for i in range(len(qr.pi))}
+    return NMachine(
+        graph=graph,
+        initial_quasidistribution=initial,
+        observation_alphabet=alphabet,
+    )
+
+
+def hmm_to_edge_machine(hmm: MealyHMM | MooreHMM, iterations: int = 1, style: int = 0) -> MealyHMM:
+    """Convert an HMM to its edge (generator) presentation."""
+    from sofic.generators.edge_machine import hmm_to_edge_machine as _build
+
+    return _build(hmm, iterations=iterations, style=style)
+
+
+def epsilon_machine_to_unifilar_graph(eps: MealyHMM) -> TopologicalUnifilarGraph:
+    """Strip emission-labeled transitions to a topological unifilar graph."""
+    from sofic.generators.synchronization import graph_from_epsilon_machine
+
+    return graph_from_epsilon_machine(eps)

sofic/generators/directional_flow.py

@@ -0,0 +1,245 @@
+"""Directional information flow on known stochastic generators."""
+
+from __future__ import annotations
+
+from collections.abc import Hashable
+from typing import Any
+
+import numpy as np
+
+from sofic.generators.base import HiddenMarkovModel, StochasticModel
+from sofic.graph import ATTR_EMISSION, ATTR_PROB
+
+
+def _require_dit():
+    from sofic.generators.measures import require_dit
+
+    return require_dit("directional flow")
+
+
+def _pair_block_distribution(generator: HiddenMarkovModel, *, history: int) -> Any:
+    """Joint law over flattened ``(x0, y0, x1, y1, ...)`` windows."""
+    from sofic.generators.hmm_inference import _stationary_emission_tensors
+
+    dit = _require_dit()
+    # Directional-flow statistics describe the stationary joint process, so weight
+    # the initial state by the stationary law rather than ``initial_distribution``.
+    pi, joint = _stationary_emission_tensors(generator)
+
+    block_length = history + 1
+    ones = np.ones(len(pi), dtype=float)
+    outcomes: list[tuple[Any, ...]] = []
+    probs: list[float] = []
+
+    def walk(
+        mass: np.ndarray,
+        prefix: tuple[Any, ...],
+        steps_remaining: int,
+    ) -> None:
+        if steps_remaining == 0:
+            outcomes.append(prefix)
+            probs.append(float(mass @ ones))
+            return
+        for symbol, matrix in joint.items():
+            if not isinstance(symbol, tuple) or len(symbol) != 2:
+                raise TypeError("generator must emit length-2 tuple symbols")
+            next_mass = mass @ matrix
+            if next_mass.sum() <= 0.0:
+                continue
+            walk(next_mass, prefix + (symbol[0], symbol[1]), steps_remaining - 1)
+
+    walk(pi.copy(), (), block_length)
+    total = sum(probs)
+    if total > 0.0:
+        probs = [p / total for p in probs]
+    return dit.Distribution(outcomes, probs)
+
+
+def _window_distribution(
+    generator: HiddenMarkovModel,
+    *,
+    history: int,
+) -> Any:
+    if history < 0:
+        raise ValueError("history must be nonnegative")
+    return _pair_block_distribution(generator, history=history)
+
+
+def _rv_indices(history: int) -> dict[str, list[int]]:
+    """Map window variables to flattened distribution indices."""
+    names: dict[str, list[int]] = {}
+    for t in range(history + 1):
+        names[f"x_{t}"] = [2 * t]
+        names[f"y_{t}"] = [2 * t + 1]
+    names["x_past"] = [idx for t in range(history) for idx in names[f"x_{t}"]]
+    names["y_past"] = [idx for t in range(history) for idx in names[f"y_{t}"]]
+    names["x_pres"] = names[f"x_{history}"]
+    names["y_pres"] = names[f"y_{history}"]
+    return names
+
+
+def transfer_entropy(
+    generator: HiddenMarkovModel,
+    *,
+    source: str = "x",
+    target: str = "y",
+    history: int = 1,
+) -> float:
+    """One-step transfer entropy ``I(Y_t; X_{past} | Y_{past})`` on tuple emissions.
+
+    The generator must emit ``(x, y)`` pairs at each step. ``source`` and
+    ``target`` must be ``'x'`` or ``'y'``.
+    """
+    if source not in {"x", "y"} or target not in {"x", "y"}:
+        raise ValueError("source and target must be 'x' or 'y'")
+    _require_dit()
+    from dit.multivariate import total_correlation as I
+
+    dist = _window_distribution(generator, history=history)
+    idx = _rv_indices(history)
+    source_past = idx[f"{source}_past"]
+    target_past = idx[f"{target}_past"]
+    target_pres = idx[f"{target}_pres"]
+    return float(I(dist, [target_pres, source_past], target_past))
+
+
+def directed_information(
+    generator: HiddenMarkovModel,
+    *,
+    source: str = "x",
+    target: str = "y",
+    length: int = 1,
+) -> float:
+    """Finite-length directed information ``I(X^{n} -> Y^{n})`` on tuple emissions."""
+    if length < 1:
+        raise ValueError("length must be positive")
+    _require_dit()
+    from dit.multivariate import total_correlation as I
+
+    total = 0.0
+    for t in range(length):
+        dist = _window_distribution(generator, history=t)
+        idx = _rv_indices(t)
+        source_block = [index for k in range(t + 1) for index in idx[f"{source}_{k}"]]
+        target_pres = idx[f"{target}_{t}"]
+        target_past = idx[f"{target}_past"] if t > 0 else []
+        total += float(I(dist, [source_block, target_pres], target_past))
+    return total
+
+
+def intrinsic_information_flow(
+    generator: HiddenMarkovModel,
+    *,
+    source: str = "x",
+    target: str = "y",
+    history: int = 1,
+) -> float:
+    """Intrinsic information flow estimate at finite window length."""
+    _require_dit()
+    from dit.multivariate import intrinsic_total_correlation as IMI
+
+    dist = _window_distribution(generator, history=history)
+    idx = _rv_indices(history)
+    source_past = idx[f"{source}_past"]
+    target_past = idx[f"{target}_past"]
+    target_pres = idx[f"{target}_pres"]
+    return float(IMI(dist, [target_pres, source_past], target_past))
+
+
+def shared_information_flow(
+    generator: HiddenMarkovModel,
+    *,
+    source: str = "x",
+    target: str = "y",
+    history: int = 1,
+) -> float:
+    """Shared flow: time-delayed mutual information minus intrinsic flow."""
+    _require_dit()
+    from dit.multivariate import total_correlation as I
+
+    dist = _window_distribution(generator, history=history)
+    idx = _rv_indices(history)
+    source_past = idx[f"{source}_past"]
+    target_pres = idx[f"{target}_pres"]
+    tdmi = float(I(dist, [source_past, target_pres]))
+    intrinsic = intrinsic_information_flow(
+        generator,
+        source=source,
+        target=target,
+        history=history,
+    )
+    return tdmi - intrinsic
+
+
+def synergistic_information_flow(
+    generator: HiddenMarkovModel,
+    *,
+    source: str = "x",
+    target: str = "y",
+    history: int = 1,
+) -> float:
+    """Synergistic flow: transfer entropy minus intrinsic flow."""
+    te = transfer_entropy(generator, source=source, target=target, history=history)
+    intrinsic = intrinsic_information_flow(
+        generator,
+        source=source,
+        target=target,
+        history=history,
+    )
+    return te - intrinsic
+
+
+def independent_pair_generator(
+    left: StochasticModel,
+    right: StochasticModel,
+) -> HiddenMarkovModel:
+    """Build an independent pair generator emitting ``(x, y)`` tuple symbols."""
+    from sofic.generators.mealy import MealyHMM
+    from sofic.graph import TransitionGraph
+
+    left_states = tuple(left.states())
+    right_states = tuple(right.states())
+    if not left_states or not right_states:
+        raise ValueError("both generators must have at least one state")
+
+    graph = TransitionGraph()
+    for left_state in left_states:
+        for right_state in right_states:
+            graph.add_state((left_state, right_state))
+
+    left_idx = {state: i for i, state in enumerate(left_states)}
+    right_idx = {state: i for i, state in enumerate(right_states)}
+    left_pi = left.stationary_distribution()
+    right_pi = right.stationary_distribution()
+    initial: dict[tuple[Hashable, Hashable], float] = {}
+    for left_state in left_states:
+        for right_state in right_states:
+            mass = float(left_pi[left_idx[left_state]] * right_pi[right_idx[right_state]])
+            if mass > 0.0:
+                initial[(left_state, right_state)] = mass
+
+    alphabet: set[tuple[Any, Any]] = set()
+    for left_state in left_states:
+        for transition in left.graph.out_transitions(left_state):
+            x = transition.data.get(ATTR_EMISSION)
+            prob_left = float(transition.data.get(ATTR_PROB, 0.0))
+            if prob_left <= 0.0 or x is None:
+                continue
+            for right_state in right_states:
+                for transition_r in right.graph.out_transitions(right_state):
+                    y = transition_r.data.get(ATTR_EMISSION)
+                    prob_right = float(transition_r.data.get(ATTR_PROB, 0.0))
+                    if prob_right <= 0.0 or y is None:
+                        continue
+                    alphabet.add((x, y))
+                    graph.add_transition(
+                        (left_state, right_state),
+                        (transition.target, transition_r.target),
+                        **{ATTR_PROB: prob_left * prob_right, ATTR_EMISSION: (x, y)},
+                    )
+
+    return MealyHMM(
+        graph=graph,
+        initial_distribution=initial,
+        observation_alphabet=frozenset(alphabet),
+    )

sofic/generators/edge_emissions.py

@@ -0,0 +1,36 @@
+"""Shared helpers for edge-labeled stochastic generators."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sofic.exceptions import StochasticValidationError
+from sofic.generators.prob import is_symbolic, row_sums_to_one
+from sofic.graph import ATTR_EMISSION, ATTR_PROB
+
+
+def validate_stochastic_edge_emissions(
+    model: Any,
+    *,
+    alphabet: frozenset[Any],
+    alphabet_name: str,
+    row_mass_label: str,
+    negative_probability_label: str,
+) -> None:
+    """Validate row-stochastic edge probabilities and emission alphabet membership."""
+    for state in model.states():
+        outgoing = list(model.graph.out_transitions(state))
+        probs = [t.data.get(ATTR_PROB, 0.0) for t in outgoing]
+        if outgoing and not row_sums_to_one(probs):
+            total = sum(probs)
+            raise StochasticValidationError(f"{row_mass_label} from {state!r} sum to {total}")
+        for transition in outgoing:
+            prob = transition.data.get(ATTR_PROB, 0.0)
+            if is_symbolic(prob):
+                if getattr(prob, "is_negative", None) is True:
+                    raise StochasticValidationError(f"{negative_probability_label} on {transition}")
+            elif prob < 0:
+                raise StochasticValidationError(f"{negative_probability_label} on {transition}")
+            emission = transition.data.get(ATTR_EMISSION)
+            if emission is not None:
+                model._require(emission in alphabet, f"emission {emission!r} not in {alphabet_name} alphabet")

sofic/generators/edge_machine.py

@@ -0,0 +1,178 @@
+"""Edge-machine (generator) presentation of an HMM.
+
+States index labeled transition paths of the source HMM. By default, the
+emitted symbol on a step is pulled from the destination edge state, matching
+cmpy's edge-machine construction.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Any
+
+from sofic.generators.base import HiddenMarkovModel
+from sofic.generators.mealy import MealyHMM
+from sofic.graph import ATTR_EMISSION, ATTR_PROB, TransitionGraph
+
+EdgeState = tuple[Any, ...]
+
+ATTR_EDGE_SOURCE = "edge_source"
+ATTR_EDGE_TARGET = "edge_target"
+_ATTR_EDGE_SOURCE = ATTR_EDGE_SOURCE
+_ATTR_EDGE_TARGET = ATTR_EDGE_TARGET
+
+
+def edge_state_label(edge: EdgeState) -> str:
+    """Stable string label for an edge-state tuple (dit-friendly state name)."""
+    return "\x1e".join(repr(part) for part in edge)
+
+
+def parse_edge_state_label(label: str) -> EdgeState:
+    """Recover an edge-state tuple from :func:`edge_state_label`."""
+    parts = label.split("\x1e")
+    if not label or not parts:
+        raise ValueError(f"not an edge state label: {label!r}")
+    return tuple(eval(part) for part in parts)
+
+
+def hmm_to_edge_machine(hmm: HiddenMarkovModel, iterations: int = 1, style: int = 0) -> MealyHMM:
+    """Build the edge machine whose states are source-HMM transition paths.
+
+    With ``iterations=1``, each state is ``(source, emission, target)``. More
+    iterations extend states by sliding-path suffixes, as in cmpy. ``style=0``
+    uses the default PULL labels from destination states; ``style=1`` rewrites
+    final transition emissions to PUSH labels from source states.
+    """
+    hmm = hmm.to_mealy()
+    iterations = int(iterations)
+    if iterations == 0:
+        return hmm
+    if iterations < 0:
+        raise ValueError("iterations must be nonnegative")
+
+    edge_machine = _edge_machine_iteration(hmm, edge_machine=False)
+    for _iteration in range(iterations - 1):
+        edge_machine = _edge_machine_iteration(edge_machine, edge_machine=True)
+
+    if style == 1:
+        _push_transition_labels(edge_machine)
+    return edge_machine
+
+
+def _edge_machine_iteration(machine: MealyHMM, *, edge_machine: bool) -> MealyHMM:
+    edge_states, edge_probs, states_by_source = _edge_states(machine, edge_machine=edge_machine)
+    if not edge_states:
+        raise ValueError("HMM has no labeled transitions")
+
+    graph = _edge_transition_graph(edge_states, edge_probs, states_by_source, edge_machine=edge_machine)
+    initial = _edge_initial_distribution(machine, edge_states, edge_probs, edge_machine=edge_machine)
+    return MealyHMM(
+        graph=graph,
+        initial_distribution=initial,
+        observation_alphabet=machine.observation_alphabet,
+    )
+
+
+def _edge_states(
+    machine: MealyHMM,
+    *,
+    edge_machine: bool,
+) -> tuple[list[EdgeState], dict[EdgeState, float], dict[Any, list[EdgeState]]]:
+    edge_states: list[EdgeState] = []
+    edge_probs: dict[EdgeState, float] = defaultdict(float)
+    states_by_source: dict[Any, list[EdgeState]] = defaultdict(list)
+    seen: set[EdgeState] = set()
+
+    for transition in machine.transitions():
+        emission = transition.data.get(ATTR_EMISSION)
+        if emission is None:
+            continue
+        state = _state_for_transition(
+            transition.source,
+            transition.target,
+            emission,
+            edge_machine=edge_machine,
+        )
+        if state not in seen:
+            seen.add(state)
+            edge_states.append(state)
+            states_by_source[_state_source(state, edge_machine=edge_machine)].append(state)
+        edge_probs[state] += float(transition.data.get(ATTR_PROB, 0.0))
+
+    return edge_states, dict(edge_probs), dict(states_by_source)
+
+
+def _state_for_transition(source: Any, target: Any, emission: Any, *, edge_machine: bool) -> EdgeState:
+    if edge_machine:
+        if not isinstance(source, tuple) or not isinstance(target, tuple):
+            raise TypeError("iterated edge-machine states must be tuples")
+        return source + target[-2:]
+    return (source, emission, target)
+
+
+def _state_source(state: EdgeState, *, edge_machine: bool) -> Any:
+    return state[:-2] if edge_machine else state[0]
+
+
+def _state_target(state: EdgeState, *, edge_machine: bool) -> Any:
+    return state[2:] if edge_machine else state[2]
+
+
+def _edge_transition_graph(
+    edge_states: list[EdgeState],
+    edge_probs: dict[EdgeState, float],
+    states_by_source: dict[Any, list[EdgeState]],
+    *,
+    edge_machine: bool,
+) -> TransitionGraph:
+    graph = TransitionGraph()
+    for edge in edge_states:
+        graph.add_state(
+            edge,
+            **_edge_state_attrs(edge),
+        )
+
+    for edge_from in edge_states:
+        target_state = _state_target(edge_from, edge_machine=edge_machine)
+        for edge_to in states_by_source.get(target_state, []):
+            graph.add_transition(
+                edge_from,
+                edge_to,
+                **{
+                    ATTR_PROB: edge_probs[edge_to],
+                    ATTR_EMISSION: edge_to[-2],
+                },
+            )
+    return graph
+
+
+def _edge_state_attrs(edge: EdgeState) -> dict[str, Any]:
+    if len(edge) != 3:
+        return {}
+    return {_ATTR_EDGE_SOURCE: edge[0], ATTR_EMISSION: edge[1], _ATTR_EDGE_TARGET: edge[2]}
+
+
+def _edge_initial_distribution(
+    machine: MealyHMM,
+    edge_states: list[EdgeState],
+    edge_probs: dict[EdgeState, float],
+    *,
+    edge_machine: bool,
+) -> dict[EdgeState, float]:
+    idx = machine.reindex()
+    pi = machine.stationary_distribution()
+    initial: dict[EdgeState, float] = defaultdict(float)
+    for edge in edge_states:
+        source = _state_source(edge, edge_machine=edge_machine)
+        if source not in idx:
+            continue
+        initial[edge] += float(pi[idx.index(source)] * edge_probs[edge])
+    total = sum(initial.values())
+    if total <= 0.0:
+        raise ValueError("edge machine initial distribution is empty")
+    return {edge: mass / total for edge, mass in initial.items() if mass > 0.0}
+
+
+def _push_transition_labels(machine: MealyHMM) -> None:
+    for source, _target, _key, data in machine.graph.nx.edges(keys=True, data=True):
+        data[ATTR_EMISSION] = source[-2]