sofic 0.1.0__py3-none-any.whl

sofic/generators/mixed_state.py

@@ -0,0 +1,250 @@
+"""Mixed-state presentations of hidden Markov models."""
+
+from __future__ import annotations
+
+from collections.abc import Hashable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+
+from sofic.exceptions import StochasticValidationError
+from sofic.generators.mealy import MealyHMM
+from sofic.generators.prob import (
+    as_prob,
+    has_symbolic,
+    is_positive_mass,
+    is_symbolic,
+    is_zero,
+    simplify_prob,
+    sum_probs,
+)
+from sofic.graph import TransitionGraph
+
+
+@dataclass(frozen=True, slots=True)
+class MixedState:
+    """A normalized belief distribution over presentation basis states."""
+
+    belief: tuple[Any, ...]
+
+    @classmethod
+    def from_vector(
+        cls,
+        vector: Sequence[Any] | np.ndarray,
+        *,
+        decimals: int = 12,
+        atol: float = 1e-12,
+    ) -> MixedState | None:
+        """Return a canonical mixed state, or ``None`` if the vector has no mass."""
+        flat = list(np.asarray(vector, dtype=object).ravel())
+        if has_symbolic(flat):
+            total = sum_probs(flat)
+            if is_zero(total, atol=atol):
+                return None
+            normalized = tuple(simplify_prob(as_prob(value) / total) for value in flat)
+            return cls(normalized)
+
+        array = np.asarray([float(value) for value in flat], dtype=float)
+        total = float(array.sum())
+        if total <= atol:
+            return None
+        normalized = array / total
+        rounded = tuple(round(float(value), decimals) for value in normalized)
+        total_rounded = sum(rounded)
+        if total_rounded <= atol:
+            return None
+        if not np.isclose(total_rounded, 1.0, atol=10 ** (-decimals + 2)):
+            rounded = tuple(round(value / total_rounded, decimals) for value in rounded)
+        return cls(rounded)
+
+    def as_array(self) -> np.ndarray:
+        if has_symbolic(self.belief):
+            array = np.empty(len(self.belief), dtype=object)
+            for i, value in enumerate(self.belief):
+                array[i] = value
+            return array
+        return np.asarray(self.belief, dtype=float)
+
+    def is_symbolic(self) -> bool:
+        return has_symbolic(self.belief)
+
+
+def is_pure_mixed_state(
+    state: MixedState | Sequence[Any],
+    *,
+    atol: float = 1e-9,
+) -> bool:
+    """Return whether ``state`` is a vertex of the belief simplex."""
+    belief = state.belief if isinstance(state, MixedState) else tuple(state)
+    if has_symbolic(belief):
+        positives = [value for value in belief if is_positive_mass(value, atol=atol)]
+        from sofic.generators.prob import probs_equal
+
+        return len(positives) == 1 and probs_equal(sum_probs(belief), 1)
+    positives = [value for value in belief if value > atol]
+    return len(positives) == 1 and np.isclose(sum(belief), 1.0, atol=atol)
+
+
+def pure_state_index(state: MixedState, *, atol: float = 1e-9) -> int | None:
+    """Return the basis index for a pure mixed state, else ``None``."""
+    if not is_pure_mixed_state(state, atol=atol):
+        return None
+    for index, value in enumerate(state.belief):
+        if is_positive_mass(value, atol=atol):
+            return index
+    return None
+
+
+def mixed_state_entropy(state: MixedState, *, atol: float = 1e-12) -> float:
+    """Shannon entropy of a mixed state in bits."""
+    from sofic.generators.stochastic import shannon_entropy
+
+    if state.is_symbolic():
+        raise NotImplementedError("mixed_state_entropy is numeric-only; evaluate beliefs first")
+    return shannon_entropy(state.as_array(), atol=atol)
+
+
+class MixedStatePresentation(MealyHMM):
+    """Unifilar presentation whose states are beliefs over a source HMM."""
+
+    basis_states: tuple[Hashable, ...]
+    initial_mixed_state: MixedState
+    pure_states: frozenset[MixedState]
+    recurrent_states: frozenset[MixedState]
+    transient_states: frozenset[MixedState]
+
+    def __init__(
+        self,
+        *,
+        basis_states: Sequence[Hashable],
+        initial_mixed_state: MixedState,
+        pure_states: frozenset[MixedState],
+        recurrent_states: frozenset[MixedState],
+        transient_states: frozenset[MixedState],
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self.basis_states = tuple(basis_states)
+        self.initial_mixed_state = initial_mixed_state
+        self.pure_states = pure_states
+        self.recurrent_states = recurrent_states
+        self.transient_states = transient_states
+
+    @classmethod
+    def from_presentation(
+        cls,
+        hmm: MealyHMM,
+        *,
+        initial_mixed_state: MixedState | Mapping[Hashable, float] | Sequence[float] | None = None,
+    ) -> MixedStatePresentation:
+        from sofic.generators.mixed_state_construction import build_mixed_state_presentation
+
+        return build_mixed_state_presentation(hmm, initial_mixed_state=initial_mixed_state)
+
+    def to_recurrent(self) -> MealyHMM:
+        """Return the recurrent component with stationary initial weights.
+
+        Pure recurrent mixed states are relabeled by their basis states and returned
+        as an :class:`~sofic.generators.epsilon_machine.EpsilonMachine`.  Otherwise
+        the recurrent component remains a unifilar :class:`~sofic.generators.mealy.MealyHMM`
+        over mixed states.
+        """
+        keep = frozenset(self.recurrent_states)
+        if not keep:
+            raise StochasticValidationError("mixed-state presentation has no recurrent states")
+
+        state_map, is_epsilon_machine = self._recurrent_state_map(keep)
+        graph = TransitionGraph()
+        for state in keep:
+            graph.add_state(state_map[state], **self.graph.state_attrs(state))
+        for state in keep:
+            for transition in self.graph.out_transitions(state):
+                if transition.target in keep:
+                    graph.add_transition(
+                        state_map[state],
+                        state_map[transition.target],
+                        **transition.data,
+                    )
+
+        initial_distribution = self._recurrent_initial_distribution(keep, state_map)
+        constraints = getattr(self, "symbol_constraints", None)
+        if is_epsilon_machine:
+            from sofic.generators.epsilon_machine import EpsilonMachine
+
+            recurrent = EpsilonMachine(
+                graph=graph,
+                initial_distribution=initial_distribution,
+                observation_alphabet=self.observation_alphabet,
+                symbol_constraints=constraints,
+            )
+            recurrent.validate()
+            return recurrent
+
+        recurrent = MealyHMM(
+            graph=graph,
+            initial_distribution=initial_distribution,
+            observation_alphabet=self.observation_alphabet,
+            symbol_constraints=constraints,
+        )
+        recurrent.validate_stochastic()
+        recurrent._check_unifilar()
+        return recurrent
+
+    def _recurrent_state_map(
+        self,
+        keep: frozenset[MixedState],
+    ) -> tuple[dict[MixedState, Hashable], bool]:
+        labels: dict[MixedState, Hashable] = {}
+        for state in keep:
+            label = self.causal_state(state)
+            if label is None:
+                return {mixed_state: mixed_state for mixed_state in keep}, False
+            labels[state] = label
+        return labels, True
+
+    def _recurrent_initial_distribution(
+        self,
+        keep: frozenset[MixedState],
+        state_map: Mapping[MixedState, Hashable],
+    ) -> dict[Hashable, Any]:
+        from sofic.generators.prob import simplify_prob
+
+        idx = self.reindex()
+        stationary = self.stationary_distribution()
+        initial: dict[Hashable, Any] = {}
+        symbolic = stationary.dtype == object or has_symbolic(stationary.ravel())
+        for state in keep:
+            mass = stationary[idx.index(state)]
+            if not is_positive_mass(mass):
+                continue
+            label = state_map[state]
+            if label in initial:
+                initial[label] = simplify_prob(as_prob(initial[label]) + as_prob(mass))
+            else:
+                initial[label] = as_prob(mass)
+        if not initial:
+            raise StochasticValidationError("recurrent component has no positive stationary mass")
+        total = sum_probs(initial.values())
+        if symbolic or is_symbolic(total):
+            return {state: simplify_prob(as_prob(mass) / total) for state, mass in initial.items()}
+        total_f = float(total)
+        return {state: float(mass) / total_f for state, mass in initial.items()}
+
+    def belief(self, state: MixedState) -> tuple[Any, ...]:
+        return state.belief
+
+    def causal_state(self, state: MixedState) -> Hashable | None:
+        index = pure_state_index(state)
+        if index is None:
+            return None
+        return self.basis_states[index]
+
+    def is_pure(self, state: MixedState) -> bool:
+        return state in self.pure_states
+
+    def is_recurrent(self, state: MixedState) -> bool:
+        return state in self.recurrent_states
+
+    def is_transient(self, state: MixedState) -> bool:
+        return state in self.transient_states

sofic/generators/mixed_state_construction.py

@@ -0,0 +1,163 @@
+"""Build mixed-state presentations via belief-state enumeration."""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Hashable, Mapping, Sequence
+from typing import Any
+
+import numpy as np
+
+from sofic.exceptions import StochasticValidationError
+from sofic.generators.base import HiddenMarkovModel
+from sofic.generators.mealy import MealyHMM
+from sofic.generators.mixed_state import (
+    MixedState,
+    MixedStatePresentation,
+    is_pure_mixed_state,
+)
+from sofic.generators.prob import (
+    as_prob,
+    has_symbolic,
+    is_positive_mass,
+    matvec,
+    simplify_prob,
+    sum_probs,
+    zeros,
+)
+from sofic.graph import ATTR_EMISSION, ATTR_PROB, TransitionGraph
+
+
+def _terminal_recurrent_states(graph: TransitionGraph) -> frozenset[Any]:
+    return graph.terminal_recurrent_states()
+
+
+def _resolve_initial_belief(
+    hmm: HiddenMarkovModel,
+    basis: tuple[Hashable, ...],
+    initial_mixed_state: MixedState | Mapping[Hashable, Any] | Sequence[Any] | None,
+) -> MixedState:
+    if initial_mixed_state is None:
+        vector = hmm.stationary_distribution()
+    elif isinstance(initial_mixed_state, MixedState):
+        vector = initial_mixed_state.as_array()
+    elif isinstance(initial_mixed_state, Mapping):
+        index = {state: i for i, state in enumerate(basis)}
+        symbolic = has_symbolic(initial_mixed_state.values())
+        vector = zeros((len(basis),), symbolic=symbolic)
+        for state, mass in initial_mixed_state.items():
+            vector[index[state]] = as_prob(mass)
+    else:
+        vector = np.asarray(initial_mixed_state, dtype=object if has_symbolic(initial_mixed_state) else float)
+
+    if len(np.asarray(vector).ravel()) != len(basis):
+        raise ValueError(f"initial belief has length {len(np.asarray(vector).ravel())}, expected {len(basis)}")
+    mixed = MixedState.from_vector(vector)
+    if mixed is None:
+        raise ValueError("initial mixed state has zero total mass")
+    return mixed
+
+
+def build_mixed_state_presentation(
+    hmm: HiddenMarkovModel,
+    *,
+    initial_mixed_state: MixedState | Mapping[Hashable, Any] | Sequence[Any] | None = None,
+    max_states: int = 10_000,
+) -> MixedStatePresentation:
+    """Enumerate the mixed-state presentation of ``hmm``.
+
+    States are reachable belief distributions over the source presentation's hidden
+    states, updated by Bayes' rule on emitted symbols.  The construction follows
+    Ellison, Mahoney & Crutchfield (J. Stat. Phys. 2009), Sec. VIII.2.
+
+    Any Mealy-style HMM (joint edge emissions) is accepted; unifilarity is not required.
+    Probabilities may be floats or exact sympy expressions.
+
+    Parameters
+    ----------
+    max_states
+        Safety cap on enumerated beliefs (symbolic machines can otherwise grow
+        without bound when successor beliefs fail to identify).
+    """
+    if isinstance(hmm, MixedStatePresentation):
+        raise TypeError("cannot build a mixed-state presentation from another mixed-state presentation")
+    if not isinstance(hmm, MealyHMM):
+        raise TypeError(f"mixed-state presentation requires a MealyHMM, not {type(hmm)!r}")
+
+    from sofic.generators.hmm_inference import _emission_transition_tensors
+
+    constraints = getattr(hmm, "symbol_constraints", None)
+
+    idx = hmm.reindex()
+    basis = idx.states
+    _, joint = _emission_transition_tensors(hmm)
+    symbols = tuple(sorted(joint, key=str))
+    eta0 = _resolve_initial_belief(hmm, basis, initial_mixed_state)
+
+    graph = TransitionGraph()
+    discovered: dict[MixedState, MixedState] = {}
+    queue: deque[MixedState] = deque()
+
+    def register(state: MixedState) -> MixedState:
+        existing = discovered.get(state)
+        if existing is not None:
+            return existing
+        for known in discovered:
+            if _beliefs_equal(known, state, constraints=constraints):
+                discovered[state] = known
+                return known
+        if len(discovered) >= max_states:
+            raise StochasticValidationError(f"mixed-state presentation exceeded max_states={max_states}")
+        discovered[state] = state
+        graph.add_state(state)
+        queue.append(state)
+        return state
+
+    register(eta0)
+
+    while queue:
+        eta = queue.popleft()
+        row = eta.as_array()
+        for symbol in symbols:
+            matrix = joint[symbol]
+            mass = matvec(row, matrix)
+            probability = simplify_prob(sum_probs(mass.tolist()))
+            if not is_positive_mass(probability):
+                continue
+            successor = MixedState.from_vector(mass)
+            if successor is None:
+                continue
+            successor = register(successor)
+            graph.add_transition(
+                eta,
+                successor,
+                **{ATTR_PROB: as_prob(probability), ATTR_EMISSION: symbol},
+            )
+
+    pure_states = frozenset(state for state in discovered.values() if is_pure_mixed_state(state))
+    unique_states = frozenset(discovered.values())
+    recurrent_states = _terminal_recurrent_states(graph) & unique_states
+    if not recurrent_states:
+        recurrent_states = _terminal_recurrent_states(graph)
+    reachable = frozenset(discovered.values())
+    transient_states = reachable - recurrent_states
+
+    return MixedStatePresentation(
+        graph=graph,
+        basis_states=basis,
+        initial_mixed_state=eta0,
+        pure_states=pure_states,
+        recurrent_states=frozenset(recurrent_states),
+        transient_states=frozenset(transient_states),
+        initial_distribution={eta0: as_prob(1)},
+        observation_alphabet=hmm.observation_alphabet,
+        symbol_constraints=constraints,
+    )
+
+
+def _beliefs_equal(left: MixedState, right: MixedState, *, constraints: Any = None) -> bool:
+    from sofic.generators.prob import probs_equal
+
+    if len(left.belief) != len(right.belief):
+        return False
+    return all(probs_equal(a, b, constraints=constraints) for a, b in zip(left.belief, right.belief, strict=True))

sofic/generators/moore.py

@@ -0,0 +1,75 @@
+"""Moore-type hidden Markov models."""
+
+from __future__ import annotations
+
+from collections.abc import Hashable, Mapping
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from sofic.exceptions import StochasticValidationError
+from sofic.generators.base import HiddenMarkovModel
+from sofic.generators.mealy import MealyHMM
+from sofic.graph import ATTR_EMISSION_DIST, ATTR_PROB
+
+if TYPE_CHECKING:
+    from sofic.generators.lumping import LabelsLike, PartitionLike
+
+
+class MooreHMM(HiddenMarkovModel):
+    """HMM with P(o | q) on states and P(q' | q) on edges."""
+
+    def set_emission_distribution(self, state: Hashable, distribution: Mapping[Any, float]) -> None:
+        """Set the state emission law ``P(observation | state)``."""
+        self.graph.nx.nodes[state][ATTR_EMISSION_DIST] = dict(distribution)
+
+    def add_transition(self, source: Hashable, target: Hashable, prob: float, **attrs: Any) -> int:
+        """Add an edge carrying transition probability ``P(target | source)``."""
+        return self.graph.add_transition(source, target, **{ATTR_PROB: float(prob), **attrs})
+
+    def is_unifilar(self) -> bool:
+        """Return whether the Mealy conversion is row-unifilar."""
+        return self.to_mealy().is_unifilar()
+
+    def to_mealy(self) -> MealyHMM:
+        from sofic.generators.conversions import moore_to_mealy
+
+        return moore_to_mealy(self)
+
+    def is_lumpable(self, partition: PartitionLike, *, rtol: float = 1e-8, atol: float = 1e-10) -> bool:
+        """Return whether ``partition`` is strongly lumpable for this HMM."""
+        from sofic.generators.lumping import is_lumpable
+
+        return is_lumpable(self, partition, rtol=rtol, atol=atol)
+
+    def lump(
+        self,
+        partition: PartitionLike,
+        *,
+        check: bool = True,
+        labels: LabelsLike | None = None,
+        rtol: float = 1e-8,
+        atol: float = 1e-10,
+    ) -> MooreHMM:
+        """Aggregate states into blocks, returning the lumped Moore HMM."""
+        from sofic.generators.lumping import lump
+
+        return lump(self, partition, check=check, labels=labels, rtol=rtol, atol=atol)
+
+    def validate_stochastic(self) -> None:
+        super().validate_stochastic()
+        for state in self.states():
+            attrs = self.graph.state_attrs(state)
+            emission_dist = attrs.get(ATTR_EMISSION_DIST)
+            if emission_dist is not None:
+                total = sum(emission_dist.values())
+                if not np.isclose(total, 1.0):
+                    raise StochasticValidationError(f"emission distribution at {state!r} sums to {total}")
+                for symbol, prob in emission_dist.items():
+                    if prob < 0:
+                        raise StochasticValidationError(f"negative emission probability at {state!r}")
+                    self._require(symbol in self.observation_alphabet, f"unknown emission {symbol!r}")
+            outgoing = list(self.graph.out_transitions(state))
+            trans_total = sum(t.data.get(ATTR_PROB, 0.0) for t in outgoing)
+            if outgoing and not np.isclose(trans_total, 1.0):
+                raise StochasticValidationError(f"transition probabilities from {state!r} sum to {trans_total}")

sofic/generators/nmachine.py

@@ -0,0 +1,78 @@
+"""Negative machines (n-machines) with quasiprobabilities."""
+
+from __future__ import annotations
+
+from collections.abc import Hashable, Mapping
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from sofic.exceptions import QuasiStochasticValidationError
+from sofic.generators.base import QuasiStochasticModel
+from sofic.generators.epsilon_machine import EpsilonMachine
+from sofic.graph import ATTR_EMISSION, ATTR_QUASIPROB
+
+if TYPE_CHECKING:
+    from sofic.generators.quasi_realization import QuasiRealization
+
+
+class NMachine(QuasiStochasticModel):
+    """Mealy-type generator with signed joint quasiprobabilities on edges."""
+
+    observation_alphabet: frozenset[Any]
+
+    def __init__(self, observation_alphabet: frozenset[Any] | None = None, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self.observation_alphabet = observation_alphabet if observation_alphabet is not None else frozenset()
+
+    def validate_quasistochastic(self) -> None:
+        super().validate_quasistochastic()
+        for state in self.states():
+            outgoing = list(self.graph.out_transitions(state))
+            total = sum(t.data.get(ATTR_QUASIPROB, 0.0) for t in outgoing)
+            if outgoing and not np.isclose(total, 1.0):
+                raise QuasiStochasticValidationError(f"quasi masses from {state!r} sum to {total}")
+            marginals: dict[Any, float] = {}
+            for transition in outgoing:
+                emission = transition.data.get(ATTR_EMISSION)
+                if emission is None:
+                    continue
+                marginals[emission] = marginals.get(emission, 0.0) + transition.data.get(ATTR_QUASIPROB, 0.0)
+            for emission, mass in marginals.items():
+                if mass < -1e-12:
+                    raise QuasiStochasticValidationError(
+                        f"negative marginal output probability P({emission!r}|{state!r})"
+                    )
+                self._require(emission in self.observation_alphabet, f"unknown emission {emission!r}")
+
+    def is_unifilar(self) -> bool:
+        """Return whether each state emits at most one edge per symbol."""
+        from sofic.properties import is_unifilar_emissions
+
+        return is_unifilar_emissions(self)
+
+    @classmethod
+    def from_epsilon_machine(
+        cls,
+        eps: EpsilonMachine,
+        splits: Mapping[Hashable, int] | None = None,
+        **kwargs: Any,
+    ) -> NMachine:
+        from sofic.generators.nmachine_construction import build_nmachine
+
+        return build_nmachine(eps, splits)
+
+    def coarse_grained_distribution(self) -> dict[Hashable, float]:
+        from sofic.generators.nmachine_construction import coarse_grained_distribution
+
+        eps_states = tuple(
+            substate[0] for substate in self.states() if isinstance(substate, tuple) and len(substate) == 2
+        )
+        if not eps_states:
+            eps_states = tuple(self.states())
+        return coarse_grained_distribution(self, eps_states)
+
+    def to_quasi_realization(self) -> QuasiRealization:
+        from sofic.generators.quasi_realization import QuasiRealization
+
+        return QuasiRealization.from_nmachine(self)

sofic/generators/nmachine_construction.py

@@ -0,0 +1,70 @@
+"""N-machine state-splitting construction."""
+
+from __future__ import annotations
+
+from collections.abc import Hashable, Mapping
+
+from sofic.generators.epsilon_machine import EpsilonMachine
+from sofic.generators.nmachine import NMachine
+from sofic.graph import ATTR_EMISSION, ATTR_PROB, ATTR_QUASIPROB, TransitionGraph
+
+
+def build_nmachine(
+    eps: EpsilonMachine,
+    splits: Mapping[Hashable, int] | None = None,
+) -> NMachine:
+    split_counts = dict(splits or {})
+    for state in eps.states():
+        split_counts.setdefault(state, 1)
+
+    graph = TransitionGraph()
+    coarse_map: dict[tuple[Hashable, int], Hashable] = {}
+    for state in eps.states():
+        count = split_counts[state]
+        for branch in range(count):
+            substate = (state, branch)
+            graph.add_state(substate)
+            coarse_map[substate] = state
+
+    pi = eps.stationary_distribution()
+    idx = eps.reindex()
+    initial: dict[tuple[Hashable, int], float] = {}
+    for state in eps.states():
+        count = split_counts[state]
+        mass = float(pi[idx.index(state)]) / count
+        for branch in range(count):
+            initial[(state, branch)] = mass
+
+    for state in eps.states():
+        count = split_counts[state]
+        outgoing = list(eps.graph.out_transitions(state))
+        for branch in range(count):
+            source = (state, branch)
+            for transition in outgoing:
+                emission = transition.data.get(ATTR_EMISSION)
+                target_state = transition.target
+                target_branch = branch % split_counts[target_state]
+                prob = float(transition.data.get(ATTR_PROB, 0.0))
+                graph.add_transition(
+                    source,
+                    (target_state, target_branch),
+                    **{ATTR_QUASIPROB: prob, ATTR_EMISSION: emission},
+                )
+
+    return NMachine(
+        graph=graph,
+        initial_quasidistribution=initial,
+        observation_alphabet=eps.observation_alphabet,
+    )
+
+
+def coarse_grained_distribution(nm: NMachine, eps_states: tuple[Hashable, ...]) -> dict[Hashable, float]:
+    pi = nm.stationary_quasidistribution()
+    idx = nm.reindex()
+    coarse: dict[Hashable, float] = dict.fromkeys(eps_states, 0.0)
+    for substate, mass in zip(idx.states, pi, strict=False):
+        if isinstance(substate, tuple) and len(substate) == 2:
+            coarse[substate[0]] = coarse.get(substate[0], 0.0) + float(mass)
+        else:
+            coarse[substate] = coarse.get(substate, 0.0) + float(mass)
+    return coarse