sofic 0.1.0__py3-none-any.whl

sofic/generators/lumping.py

@@ -0,0 +1,447 @@
+"""Lumping (state aggregation) of Markov chains and hidden Markov models.
+
+Strong lumpability in the sense of Kemeny & Snell (:cite:`KemenySnell1976`,
+Ch. 6): a partition of the state space is *strongly lumpable* when, for every
+block, the total probability of moving into each target block is identical for
+every state in the source block. That common value defines the transition law of
+the coarser lumped chain, and -- because the condition constrains only the
+transition matrix -- it holds for every initial distribution.
+
+Hidden Markov models extend the condition to each emitted symbol so that the
+lumped model generates the same observed process:
+
+* :class:`~sofic.generators.mealy.MealyHMM` -- the joint block-and-symbol mass
+  ``sum_{t in B_j} P(t, o | s)`` must be constant across ``s`` in a block.
+* :class:`~sofic.generators.moore.MooreHMM` -- additionally the state emission
+  law ``P(o | s)`` must be identical across a block.
+
+The public entry points are :func:`is_lumpable` (predicate) and :func:`lump`
+(constructor). ``lump`` raises :class:`~sofic.exceptions.LumpabilityError` when
+the partition is not strongly lumpable unless ``check=False``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Hashable, Iterable, Mapping
+from typing import TYPE_CHECKING, Any, overload
+
+import numpy as np
+
+from sofic.exceptions import LumpabilityError
+from sofic.graph import ATTR_EMISSION, ATTR_EMISSION_DIST, ATTR_PROB, TransitionGraph
+
+if TYPE_CHECKING:
+    from sofic.base import StateMachine
+    from sofic.generators.markov import MarkovChain
+    from sofic.generators.mealy import MealyHMM
+    from sofic.generators.moore import MooreHMM
+
+PartitionLike = Iterable[Iterable[Hashable]] | Mapping[Hashable, Hashable]
+LabelsLike = Mapping[frozenset[Hashable], Hashable] | Callable[[frozenset[Hashable]], Hashable]
+
+
+def normalize_partition(model: StateMachine, partition: PartitionLike) -> list[frozenset[Hashable]]:
+    """Return ``partition`` as an ordered list of disjoint, covering blocks.
+
+    Parameters
+    ----------
+    model
+        The model whose states the partition must cover exactly.
+    partition
+        Either an iterable of blocks (each an iterable of states) or a mapping
+        from each state to a block key.
+
+    Returns
+    -------
+    list of frozenset
+        Blocks ordered by the position of their first member in ``model.states()``.
+
+    Raises
+    ------
+    ValueError
+        If the blocks overlap, reference unknown states, or fail to cover every
+        state of ``model``.
+    """
+    order = {state: index for index, state in enumerate(model.states())}
+    state_set = set(order)
+
+    if isinstance(partition, Mapping):
+        grouped: dict[Hashable, set[Hashable]] = {}
+        for state, key in partition.items():
+            grouped.setdefault(key, set()).add(state)
+        raw_blocks: Iterable[Iterable[Hashable]] = grouped.values()
+    else:
+        raw_blocks = partition
+
+    seen: set[Hashable] = set()
+    blocks: list[frozenset[Hashable]] = []
+    for raw in raw_blocks:
+        block = frozenset(raw)
+        if not block:
+            continue
+        unknown = block - state_set
+        if unknown:
+            raise ValueError(f"partition references unknown states {sorted(map(str, unknown))}")
+        overlap = block & seen
+        if overlap:
+            raise ValueError(f"partition blocks overlap on states {sorted(map(str, overlap))}")
+        seen |= block
+        blocks.append(block)
+
+    missing = state_set - seen
+    if missing:
+        raise ValueError(f"partition does not cover states {sorted(map(str, missing))}")
+
+    blocks.sort(key=lambda block: min(order[state] for state in block))
+    return blocks
+
+
+def _block_of(blocks: list[frozenset[Hashable]]) -> dict[Hashable, int]:
+    return {state: index for index, block in enumerate(blocks) for state in block}
+
+
+def _representatives(model: StateMachine, blocks: list[frozenset[Hashable]]) -> list[Hashable]:
+    order = {state: index for index, state in enumerate(model.states())}
+    return [min(block, key=lambda state: order[state]) for block in blocks]
+
+
+def _default_label(block: frozenset[Hashable]) -> Hashable:
+    if len(block) == 1:
+        return next(iter(block))
+    return "+".join(sorted(str(state) for state in block))
+
+
+def _resolve_labels(blocks: list[frozenset[Hashable]], labels: LabelsLike | None) -> list[Hashable]:
+    if labels is None:
+        resolved = [_default_label(block) for block in blocks]
+    elif isinstance(labels, Mapping):
+        resolved = [labels.get(block, _default_label(block)) for block in blocks]
+    else:
+        resolved = [labels(block) for block in blocks]
+    if len(set(resolved)) != len(resolved):
+        raise ValueError(f"block labels are not distinct: {resolved}")
+    return resolved
+
+
+def _markov_signature(
+    model: StateMachine, state: Hashable, block_of: dict[Hashable, int], num_blocks: int
+) -> np.ndarray:
+    signature = np.zeros(num_blocks, dtype=float)
+    for transition in model.graph.out_transitions(state):
+        target_block = block_of.get(transition.target)
+        if target_block is None:
+            continue
+        signature[target_block] += float(transition.data.get(ATTR_PROB, 0.0))
+    return signature
+
+
+def _mealy_signature(
+    model: StateMachine, state: Hashable, block_of: dict[Hashable, int]
+) -> dict[tuple[int, Any], float]:
+    signature: dict[tuple[int, Any], float] = {}
+    for transition in model.graph.out_transitions(state):
+        target_block = block_of.get(transition.target)
+        if target_block is None:
+            continue
+        key = (target_block, transition.data.get(ATTR_EMISSION))
+        signature[key] = signature.get(key, 0.0) + float(transition.data.get(ATTR_PROB, 0.0))
+    return signature
+
+
+def _emission_dist(model: StateMachine, state: Hashable) -> dict[Any, float]:
+    return dict(model.graph.state_attrs(state).get(ATTR_EMISSION_DIST) or {})
+
+
+def _dicts_close(left: Mapping[Any, float], right: Mapping[Any, float], *, rtol: float, atol: float) -> bool:
+    for key in set(left) | set(right):
+        if not np.isclose(left.get(key, 0.0), right.get(key, 0.0), rtol=rtol, atol=atol):
+            return False
+    return True
+
+
+def _is_lumpable_markov(model: MarkovChain, blocks: list[frozenset[Hashable]], *, rtol: float, atol: float) -> bool:
+    block_of = _block_of(blocks)
+    num_blocks = len(blocks)
+    for block in blocks:
+        members = iter(block)
+        reference = _markov_signature(model, next(members), block_of, num_blocks)
+        for state in members:
+            if not np.allclose(_markov_signature(model, state, block_of, num_blocks), reference, rtol=rtol, atol=atol):
+                return False
+    return True
+
+
+def _is_lumpable_mealy(model: MealyHMM, blocks: list[frozenset[Hashable]], *, rtol: float, atol: float) -> bool:
+    block_of = _block_of(blocks)
+    for block in blocks:
+        members = iter(block)
+        reference = _mealy_signature(model, next(members), block_of)
+        for state in members:
+            if not _dicts_close(_mealy_signature(model, state, block_of), reference, rtol=rtol, atol=atol):
+                return False
+    return True
+
+
+def _is_lumpable_moore(model: MooreHMM, blocks: list[frozenset[Hashable]], *, rtol: float, atol: float) -> bool:
+    block_of = _block_of(blocks)
+    num_blocks = len(blocks)
+    for block in blocks:
+        members = iter(block)
+        first = next(members)
+        reference_emit = _emission_dist(model, first)
+        reference_trans = _markov_signature(model, first, block_of, num_blocks)
+        for state in members:
+            if not _dicts_close(_emission_dist(model, state), reference_emit, rtol=rtol, atol=atol):
+                return False
+            if not np.allclose(
+                _markov_signature(model, state, block_of, num_blocks), reference_trans, rtol=rtol, atol=atol
+            ):
+                return False
+    return True
+
+
+def _lumped_initial(
+    model: StateMachine, block_of: dict[Hashable, int], labels: list[Hashable]
+) -> dict[Hashable, float]:
+    initial: dict[Hashable, float] = {}
+    for state, mass in getattr(model, "initial_distribution", {}).items():
+        label = labels[block_of[state]]
+        initial[label] = initial.get(label, 0.0) + float(mass)
+    return initial
+
+
+def _lump_markov(model: MarkovChain, blocks: list[frozenset[Hashable]], labels: LabelsLike | None) -> MarkovChain:
+    from sofic.generators.markov import MarkovChain
+
+    resolved = _resolve_labels(blocks, labels)
+    block_of = _block_of(blocks)
+    representatives = _representatives(model, blocks)
+
+    graph = TransitionGraph()
+    for label in resolved:
+        graph.add_state(label)
+    result = MarkovChain(graph=graph)
+
+    for index, representative in enumerate(representatives):
+        merged: dict[int, float] = {}
+        for transition in model.graph.out_transitions(representative):
+            target_block = block_of.get(transition.target)
+            if target_block is None:
+                continue
+            merged[target_block] = merged.get(target_block, 0.0) + float(transition.data.get(ATTR_PROB, 0.0))
+        for target_block, prob in merged.items():
+            result.add_transition(resolved[index], resolved[target_block], prob)
+
+    result.initial_distribution = _lumped_initial(model, block_of, resolved)
+    result.validate()
+    return result
+
+
+def _lump_mealy(model: MealyHMM, blocks: list[frozenset[Hashable]], labels: LabelsLike | None) -> MealyHMM:
+    from sofic.generators.mealy import MealyHMM
+
+    resolved = _resolve_labels(blocks, labels)
+    block_of = _block_of(blocks)
+    representatives = _representatives(model, blocks)
+
+    graph = TransitionGraph()
+    for label in resolved:
+        graph.add_state(label)
+    result = MealyHMM(graph=graph, observation_alphabet=model.observation_alphabet)
+
+    for index, representative in enumerate(representatives):
+        merged: dict[tuple[int, Any], float] = {}
+        for transition in model.graph.out_transitions(representative):
+            target_block = block_of.get(transition.target)
+            if target_block is None:
+                continue
+            key = (target_block, transition.data.get(ATTR_EMISSION))
+            merged[key] = merged.get(key, 0.0) + float(transition.data.get(ATTR_PROB, 0.0))
+        for (target_block, emission), prob in merged.items():
+            result.add_transition(resolved[index], resolved[target_block], emission, prob)
+
+    result.initial_distribution = _lumped_initial(model, block_of, resolved)
+    result.validate()
+    return result
+
+
+def _lump_moore(model: MooreHMM, blocks: list[frozenset[Hashable]], labels: LabelsLike | None) -> MooreHMM:
+    from sofic.generators.moore import MooreHMM
+
+    resolved = _resolve_labels(blocks, labels)
+    block_of = _block_of(blocks)
+    representatives = _representatives(model, blocks)
+
+    graph = TransitionGraph()
+    for label in resolved:
+        graph.add_state(label)
+    result = MooreHMM(graph=graph, observation_alphabet=model.observation_alphabet)
+
+    for index, representative in enumerate(representatives):
+        emission = _emission_dist(model, representative)
+        if emission:
+            result.set_emission_distribution(resolved[index], emission)
+        merged: dict[int, float] = {}
+        for transition in model.graph.out_transitions(representative):
+            target_block = block_of.get(transition.target)
+            if target_block is None:
+                continue
+            merged[target_block] = merged.get(target_block, 0.0) + float(transition.data.get(ATTR_PROB, 0.0))
+        for target_block, prob in merged.items():
+            result.add_transition(resolved[index], resolved[target_block], prob)
+
+    result.initial_distribution = _lumped_initial(model, block_of, resolved)
+    result.validate()
+    return result
+
+
+def _dispatch(model: StateMachine) -> tuple[Callable[..., bool], Callable[..., Any]]:
+    from sofic.generators.markov import MarkovChain
+    from sofic.generators.mealy import MealyHMM
+    from sofic.generators.moore import MooreHMM
+
+    if isinstance(model, MarkovChain):
+        return _is_lumpable_markov, _lump_markov
+    if isinstance(model, MooreHMM):
+        return _is_lumpable_moore, _lump_moore
+    if isinstance(model, MealyHMM):
+        return _is_lumpable_mealy, _lump_mealy
+    raise TypeError(f"lumping is not supported for {type(model).__name__}")
+
+
+def is_lumpable(model: StateMachine, partition: PartitionLike, *, rtol: float = 1e-8, atol: float = 1e-10) -> bool:
+    """Return whether ``partition`` is strongly lumpable for ``model``.
+
+    Strong lumpability follows Kemeny & Snell (:cite:`KemenySnell1976`): the
+    aggregated mass into each block must not depend on which state of a block the
+    chain occupies. For hidden Markov models the condition is imposed per emitted
+    symbol (and, for Moore presentations, additionally on the state emission law).
+
+    Parameters
+    ----------
+    model
+        A :class:`~sofic.generators.markov.MarkovChain`,
+        :class:`~sofic.generators.mealy.MealyHMM` (including
+        :class:`~sofic.generators.epsilon_machine.EpsilonMachine`), or
+        :class:`~sofic.generators.moore.MooreHMM`.
+    partition
+        Blocks (iterable of iterables) or a state-to-block mapping; must cover
+        every state exactly.
+    rtol, atol
+        Tolerances forwarded to :func:`numpy.isclose`.
+
+    Raises
+    ------
+    TypeError
+        If ``model`` is not a supported generator type.
+    ValueError
+        If ``partition`` is not a valid partition of ``model``'s states.
+    """
+    checker, _builder = _dispatch(model)
+    blocks = normalize_partition(model, partition)
+    return checker(model, blocks, rtol=rtol, atol=atol)
+
+
+@overload
+def lump(
+    model: MarkovChain,
+    partition: PartitionLike,
+    *,
+    check: bool = ...,
+    labels: LabelsLike | None = ...,
+    rtol: float = ...,
+    atol: float = ...,
+) -> MarkovChain: ...
+
+
+@overload
+def lump(
+    model: MooreHMM,
+    partition: PartitionLike,
+    *,
+    check: bool = ...,
+    labels: LabelsLike | None = ...,
+    rtol: float = ...,
+    atol: float = ...,
+) -> MooreHMM: ...
+
+
+@overload
+def lump(
+    model: MealyHMM,
+    partition: PartitionLike,
+    *,
+    check: bool = ...,
+    labels: LabelsLike | None = ...,
+    rtol: float = ...,
+    atol: float = ...,
+) -> MealyHMM: ...
+
+
+@overload
+def lump(
+    model: StateMachine,
+    partition: PartitionLike,
+    *,
+    check: bool = ...,
+    labels: LabelsLike | None = ...,
+    rtol: float = ...,
+    atol: float = ...,
+) -> StateMachine: ...
+
+
+def lump(
+    model: StateMachine,
+    partition: PartitionLike,
+    *,
+    check: bool = True,
+    labels: LabelsLike | None = None,
+    rtol: float = 1e-8,
+    atol: float = 1e-10,
+) -> StateMachine:
+    """Aggregate the states of ``model`` according to ``partition``.
+
+    Builds the coarser lumped model (Kemeny & Snell, :cite:`KemenySnell1976`):
+    block-to-block transition masses are read from a block representative, and
+    initial masses are summed within blocks. A
+    :class:`~sofic.generators.markov.MarkovChain` lumps to a ``MarkovChain``, a
+    :class:`~sofic.generators.moore.MooreHMM` to a ``MooreHMM``, and any
+    :class:`~sofic.generators.mealy.MealyHMM` (including an
+    :class:`~sofic.generators.epsilon_machine.EpsilonMachine`) to a plain
+    ``MealyHMM`` -- lumping may break unifilarity, so the stricter subtype is not
+    preserved.
+
+    Parameters
+    ----------
+    model
+        The generator to lump.
+    partition
+        Blocks (iterable of iterables) or a state-to-block mapping; must cover
+        every state exactly.
+    check
+        When ``True`` (default), raise :class:`~sofic.exceptions.LumpabilityError`
+        if ``partition`` is not strongly lumpable. When ``False``, build the model
+        anyway from each block's representative row (the result is exact only when
+        the partition is in fact lumpable).
+    labels
+        Optional mapping from a block (as a ``frozenset``) to its lumped-state
+        label, or a callable taking a block and returning a label. By default a
+        singleton block keeps its original state label and a merged block becomes
+        the ``"+"``-joined string of its members' labels.
+    rtol, atol
+        Tolerances forwarded to :func:`numpy.isclose` for the lumpability check.
+
+    Raises
+    ------
+    LumpabilityError
+        If ``check`` and ``partition`` is not strongly lumpable.
+    TypeError
+        If ``model`` is not a supported generator type.
+    ValueError
+        If ``partition`` is invalid or the resolved block labels collide.
+    """
+    checker, builder = _dispatch(model)
+    blocks = normalize_partition(model, partition)
+    if check and not checker(model, blocks, rtol=rtol, atol=atol):
+        raise LumpabilityError("partition is not strongly lumpable for this model")
+    return builder(model, blocks, labels)

sofic/generators/markov.py

@@ -0,0 +1,100 @@
+"""Markov chains (visible-state generators)."""
+
+from __future__ import annotations
+
+from collections.abc import Hashable
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from sofic.exceptions import StochasticValidationError
+from sofic.generators.base import StochasticModel
+from sofic.graph import ATTR_PROB
+
+if TYPE_CHECKING:
+    from sofic.generators.lumping import LabelsLike, PartitionLike
+
+
+class MarkovChain(StochasticModel):
+    """Visible-state Markov process without an observation layer."""
+
+    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_deterministic(self) -> bool:
+        """Return whether each state has a single successor with probability 1."""
+        from sofic.properties import is_deterministic_markov
+
+        return is_deterministic_markov(self)
+
+    def is_lumpable(self, partition: PartitionLike, *, rtol: float = 1e-8, atol: float = 1e-10) -> bool:
+        """Return whether ``partition`` is strongly lumpable for this chain."""
+        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,
+    ) -> MarkovChain:
+        """Aggregate states into blocks, returning the lumped chain."""
+        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():
+            outgoing = list(self.graph.out_transitions(state))
+            total = sum(t.data.get(ATTR_PROB, 0.0) for t in outgoing)
+            if outgoing and not np.isclose(total, 1.0):
+                raise StochasticValidationError(f"transition probabilities from {state!r} sum to {total}")
+            for transition in outgoing:
+                prob = transition.data.get(ATTR_PROB, 0.0)
+                if prob < 0:
+                    raise StochasticValidationError(f"negative transition probability on {transition}")
+
+    def stationary_distribution(self) -> np.ndarray:
+        from sofic.generators.stationary import stationary_distribution_from_transition
+        from sofic.properties import transition_matrix
+
+        idx = self.reindex()
+        if len(idx) == 0:
+            return np.array([], dtype=float)
+        transition, _states = transition_matrix(self, attr=ATTR_PROB, states=idx.states)
+        return stationary_distribution_from_transition(transition)
+
+    def entropy_rate(self) -> float:
+        from sofic.generators.measures import entropy_rate_markov
+
+        return entropy_rate_markov(self)
+
+    def words_of_length(self, length: int) -> dict[tuple[Hashable, ...], float]:
+        """Return visible state paths of ``length`` and their probabilities."""
+        from sofic.generators.words import markov_words_of_length
+
+        return markov_words_of_length(self, length)
+
+    def sample_path(self, n: int, rng: np.random.Generator | None = None) -> list[Hashable]:
+        generator = rng if rng is not None else np.random.default_rng()
+        idx = self.reindex()
+        pi = self.stationary_distribution()
+        state = int(generator.choice(len(idx), p=pi))
+
+        path: list[Hashable] = []
+        for _ in range(n):
+            path.append(idx.state(state))
+            outgoing = list(self.graph.out_transitions(idx.state(state)))
+            probs = np.array([float(t.data.get(ATTR_PROB, 0.0)) for t in outgoing], dtype=float)
+            if probs.sum() <= 0.0:
+                break
+            probs /= probs.sum()
+            choice = int(generator.choice(len(outgoing), p=probs))
+            state = idx.index(outgoing[choice].target)
+        return path

sofic/generators/mealy.py

@@ -0,0 +1,156 @@
+"""Mealy-type hidden Markov models."""
+
+from __future__ import annotations
+
+from collections.abc import Hashable, Mapping, Sequence
+from typing import TYPE_CHECKING, Any
+
+from sofic.exceptions import UnifilarityError
+from sofic.generators.base import HiddenMarkovModel
+from sofic.generators.edge_emissions import validate_stochastic_edge_emissions
+from sofic.graph import ATTR_EMISSION, ATTR_PROB
+
+if TYPE_CHECKING:
+    from sofic.generators.lumping import LabelsLike, PartitionLike
+    from sofic.generators.mixed_state import MixedState, MixedStatePresentation
+
+
+class MealyHMM(HiddenMarkovModel):
+    """HMM with joint transition-emission law P(q', o | q) on edges.
+
+    Each outgoing edge carries an emission symbol and a probability. Row sums at
+    every state must equal 1. Use :meth:`mixed_state_presentation` to obtain
+    belief-state dynamics, or :meth:`~sofic.generators.epsilon_machine.EpsilonMachine.from_hmm`
+    for the causal ε-machine presentation.
+
+    Examples
+    --------
+    >>> from sofic.examples import golden_mean
+    >>> eps = golden_mean(0.5)
+    >>> eps.entropy_rate() > 0
+    True
+    """
+
+    def add_transition(self, source: Hashable, target: Hashable, symbol: Any, prob: float, **attrs: Any) -> int:
+        """Add an edge carrying joint emission probability ``P(target, symbol | source)``.
+
+        ``prob`` may be a Python float or an exact sympy expression (see
+        :mod:`sofic.generators.prob`).
+        """
+        from sofic.generators.prob import as_prob
+
+        return self.graph.add_transition(
+            source,
+            target,
+            **{ATTR_EMISSION: symbol, ATTR_PROB: as_prob(prob), **attrs},
+        )
+
+    def validate_stochastic(self) -> None:
+        super().validate_stochastic()
+        validate_stochastic_edge_emissions(
+            self,
+            alphabet=self.observation_alphabet,
+            alphabet_name="observation",
+            row_mass_label="joint masses",
+            negative_probability_label="negative joint probability",
+        )
+
+    def to_mealy(self) -> MealyHMM:
+        """Return this already-Mealy presentation."""
+        return self
+
+    def _check_unifilar(self) -> None:
+        if self.is_unifilar():
+            return
+        seen: set[tuple[Hashable, Any]] = set()
+        for transition in self.transitions():
+            emission = transition.data.get(ATTR_EMISSION)
+            if emission is None:
+                continue
+            key = (transition.source, emission)
+            if key in seen:
+                raise UnifilarityError(f"duplicate emission {emission!r} from state {transition.source!r}")
+            seen.add(key)
+
+    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)
+
+    def is_counifilar(self) -> bool:
+        """Return whether each ``(target, emission)`` identifies a unique source."""
+        from sofic.properties import is_counifilar_emissions
+
+        return is_counifilar_emissions(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,
+    ) -> MealyHMM:
+        """Aggregate states into blocks, returning the lumped Mealy HMM."""
+        from sofic.generators.lumping import lump
+
+        return lump(self, partition, check=check, labels=labels, rtol=rtol, atol=atol)
+
+    def is_irreducible(self) -> bool:
+        """Return whether the internal state graph is strongly connected."""
+        from sofic.properties import is_irreducible
+
+        return is_irreducible(self)
+
+    def is_ergodic(self, *, weak: bool = True) -> bool:
+        """Return weak/strong ergodicity of the internal finite-state dynamics."""
+        from sofic.properties import is_ergodic
+
+        return is_ergodic(self, weak=weak)
+
+    def is_stationary(self, *, rtol: float = 1e-8, atol: float = 1e-10) -> bool:
+        """Return whether the initial distribution is internally stationary."""
+        from sofic.properties import is_stationary
+
+        return is_stationary(self, rtol=rtol, atol=atol)
+
+    def is_detailed_balance(self, *, rtol: float = 1e-8, atol: float = 1e-10) -> bool:
+        """Return whether stationary labeled flows satisfy detailed balance."""
+        from sofic.properties import is_detailed_balance
+
+        return is_detailed_balance(self, rtol=rtol, atol=atol)
+
+    def is_periodic(self) -> bool:
+        """Return whether terminal internal components have graph period greater than one."""
+        from sofic.properties import is_periodic
+
+        return is_periodic(self)
+
+    def is_strictly_sofic(self) -> bool:
+        """Return whether this generator's support is strictly sofic."""
+        from sofic.properties import is_strictly_sofic
+
+        return is_strictly_sofic(self)
+
+    def mixed_state_presentation(
+        self,
+        *,
+        initial_mixed_state: MixedState | Mapping[Hashable, float] | Sequence[float] | None = None,
+    ) -> MixedStatePresentation:
+        """Build the mixed-state presentation (observer belief dynamics)."""
+        from sofic.generators.mixed_state import MixedStatePresentation
+
+        return MixedStatePresentation.from_presentation(self, initial_mixed_state=initial_mixed_state)
+
+    def to_edge_machine(self, iterations: int = 1, style: int = 0) -> MealyHMM:
+        from sofic.generators.edge_machine import hmm_to_edge_machine
+
+        return hmm_to_edge_machine(self, iterations=iterations, style=style)