synkit 1.6.5__py3-none-win_amd64.whl

synkit/CRN/Petrinet/siphon_search.py

@@ -0,0 +1,402 @@
+"""Branch-and-bound enumeration of minimal siphons and traps.
+
+Enumerating siphons by testing all :math:`2^n` place subsets is only viable for
+toy networks: a 25-species network already takes about a minute, and the cost
+multiplies by roughly eight for every three further species.
+
+This module instead builds on the *closure* operator: for any set of places
+``A`` there is a unique **maximal siphon contained in** ``A``, and it can be
+computed in polynomial time by repeatedly discarding places that break the
+siphon condition (:func:`max_siphon_within`). Minimal siphons are then reached
+by starting from the maximal siphon of the whole net and repeatedly removing
+one place and re-closing.
+
+That descent is complete. If ``M`` is a minimal siphon and ``S`` is any siphon
+with ``M`` a strict subset of ``S``, then for a place ``p`` in ``S`` but not in
+``M`` the set ``S \\ {p}`` still contains ``M``; since ``M`` is itself a siphon,
+it survives the closure, so ``max_siphon_within(S \\ {p})`` still contains
+``M``. Every minimal siphon is therefore reachable from the top by successive
+delete-and-close steps.
+
+Traps are the exact dual (every transition consuming from the set also produces
+back into it) and are handled by the same machinery.
+
+.. rubric:: Example
+
+.. code-block:: python
+
+    from synkit.CRN.Structure import SynCRN
+    from synkit.CRN.Petrinet import PetriNet
+    from synkit.CRN.Petrinet.siphon_search import minimal_siphons
+
+    net = PetriNet.from_syncrn(SynCRN.from_reaction_strings(["A>>B", "B>>A"]))
+    print(minimal_siphons(net))
+"""
+
+from __future__ import annotations
+
+from typing import Dict, FrozenSet, List, Optional, Sequence, Set, Tuple
+
+from .net import PetriNet
+
+__all__ = [
+    "max_siphon_within",
+    "max_trap_within",
+    "minimal_siphons",
+    "minimal_traps",
+    "SiphonSearchLimit",
+]
+
+#: Default ceiling on explored search nodes, so a pathological network degrades
+#: into a truncated result rather than an apparent hang.
+DEFAULT_MAX_NODES = 200_000
+
+
+class SiphonSearchLimit(RuntimeError):
+    """Raised when a siphon or trap search exceeds its exploration budget."""
+
+
+def _incidence(
+    net: PetriNet,
+) -> Tuple[Dict[str, Set[str]], Dict[str, Set[str]]]:
+    """Index a Petri net as ``transition -> consumed`` / ``transition -> produced``.
+
+    :param net:
+        Petri net to index.
+    :type net: PetriNet
+
+    :return:
+        Pair ``(pre, post)`` mapping each transition id to the set of places it
+        consumes from and produces into, with zero-weight arcs dropped.
+    :rtype: Tuple[Dict[str, Set[str]], Dict[str, Set[str]]]
+    """
+    pre: Dict[str, Set[str]] = {}
+    post: Dict[str, Set[str]] = {}
+
+    for tid in net.transition_order:
+        t = net.transitions[tid]
+        pre[tid] = {p for p, w in t.pre.items() if w > 0}
+        post[tid] = {p for p, w in t.post.items() if w > 0}
+
+    return pre, post
+
+
+def _max_closed_within(
+    allowed: Set[str],
+    *,
+    trigger: Dict[str, Set[str]],
+    required: Dict[str, Set[str]],
+    transition_order: Sequence[str],
+) -> Set[str]:
+    """Compute the maximal subset of ``allowed`` closed under a incidence rule.
+
+    A set ``S`` is closed when, for every transition ``t``, ``trigger[t]``
+    meeting ``S`` implies ``required[t]`` also meets ``S``. Choosing
+    ``trigger=post`` and ``required=pre`` yields siphons; swapping them yields
+    traps.
+
+    Places are removed until a fixed point is reached, which is the unique
+    maximal closed subset.
+
+    :param allowed:
+        Candidate place set. Not mutated.
+    :type allowed: Set[str]
+
+    :param trigger:
+        Transition-to-places map that activates the condition.
+    :type trigger: Dict[str, Set[str]]
+
+    :param required:
+        Transition-to-places map that must then also be met.
+    :type required: Dict[str, Set[str]]
+
+    :param transition_order:
+        Deterministic transition iteration order.
+    :type transition_order: Sequence[str]
+
+    :return:
+        Maximal closed subset of ``allowed``, possibly empty.
+    :rtype: Set[str]
+    """
+    current = set(allowed)
+
+    changed = True
+    while changed and current:
+        changed = False
+        for tid in transition_order:
+            hit = trigger[tid] & current
+            if not hit:
+                continue
+            if required[tid] & current:
+                continue
+            # This transition breaks the condition: every place it triggers on
+            # must leave the set.
+            current -= hit
+            changed = True
+            if not current:
+                break
+
+    return current
+
+
+def max_siphon_within(net: PetriNet, allowed: Set[str]) -> Set[str]:
+    """Return the unique maximal siphon contained in ``allowed``.
+
+    :param net:
+        Petri net to analyse.
+    :type net: PetriNet
+
+    :param allowed:
+        Places the siphon may draw from.
+    :type allowed: Set[str]
+
+    :return:
+        Maximal siphon inside ``allowed``, empty if there is none.
+    :rtype: Set[str]
+
+    .. rubric:: Example
+
+    .. code-block:: python
+
+        max_siphon_within(net, set(net.place_order))
+    """
+    pre, post = _incidence(net)
+    return _max_closed_within(
+        allowed,
+        trigger=post,
+        required=pre,
+        transition_order=net.transition_order,
+    )
+
+
+def max_trap_within(net: PetriNet, allowed: Set[str]) -> Set[str]:
+    """Return the unique maximal trap contained in ``allowed``.
+
+    :param net:
+        Petri net to analyse.
+    :type net: PetriNet
+
+    :param allowed:
+        Places the trap may draw from.
+    :type allowed: Set[str]
+
+    :return:
+        Maximal trap inside ``allowed``, empty if there is none.
+    :rtype: Set[str]
+
+    .. rubric:: Example
+
+    .. code-block:: python
+
+        max_trap_within(net, set(net.place_order))
+    """
+    pre, post = _incidence(net)
+    return _max_closed_within(
+        allowed,
+        trigger=pre,
+        required=post,
+        transition_order=net.transition_order,
+    )
+
+
+def _enumerate_minimal(
+    net: PetriNet,
+    *,
+    trigger: Dict[str, Set[str]],
+    required: Dict[str, Set[str]],
+    max_size: Optional[int],
+    max_nodes: int,
+    strict_limit: bool,
+) -> List[Set[str]]:
+    """Enumerate inclusion-minimal closed sets by delete-and-close descent.
+
+    :param net:
+        Petri net to analyse.
+    :type net: PetriNet
+
+    :param trigger:
+        Transition-to-places map activating the closure condition.
+    :type trigger: Dict[str, Set[str]]
+
+    :param required:
+        Transition-to-places map that must also be met.
+    :type required: Dict[str, Set[str]]
+
+    :param max_size:
+        Optional ceiling on the size of returned sets.
+    :type max_size: Optional[int]
+
+    :param max_nodes:
+        Maximum number of closure evaluations before giving up.
+    :type max_nodes: int
+
+    :param strict_limit:
+        Whether exceeding ``max_nodes`` raises instead of truncating.
+    :type strict_limit: bool
+
+    :return:
+        Inclusion-minimal closed sets.
+    :rtype: List[Set[str]]
+
+    :raises SiphonSearchLimit:
+        If the budget is exhausted and ``strict_limit`` is set.
+    """
+    places = list(net.place_order)
+    order = net.transition_order
+
+    root = _max_closed_within(
+        set(places), trigger=trigger, required=required, transition_order=order
+    )
+    if not root:
+        return []
+
+    seen: Set[FrozenSet[str]] = set()
+    minimal: List[Set[str]] = []
+    stack: List[FrozenSet[str]] = [frozenset(root)]
+    seen.add(frozenset(root))
+    nodes = 0
+    truncated = False
+
+    while stack:
+        current = stack.pop()
+
+        is_minimal = True
+        for p in sorted(current):
+            if nodes >= max_nodes:
+                truncated = True
+                break
+            nodes += 1
+
+            child = _max_closed_within(
+                set(current) - {p},
+                trigger=trigger,
+                required=required,
+                transition_order=order,
+            )
+            if not child:
+                continue
+
+            # A non-empty proper closed subset exists, so `current` is not
+            # inclusion-minimal.
+            is_minimal = False
+            key = frozenset(child)
+            if key not in seen:
+                seen.add(key)
+                stack.append(key)
+
+        if truncated:
+            break
+        if is_minimal:
+            minimal.append(set(current))
+
+    if truncated and strict_limit:
+        raise SiphonSearchLimit(
+            f"Search exceeded {max_nodes} closure evaluations. Raise max_nodes, "
+            f"set max_size, or pass strict_limit=False to accept a partial result."
+        )
+
+    # The descent can surface a set that strictly contains another minimal one
+    # when the budget truncates a branch; filter defensively.
+    result = [
+        s
+        for s in minimal
+        if not any(t < s for t in minimal)
+        and (max_size is None or len(s) <= max_size)
+    ]
+    result.sort(key=lambda s: (len(s), sorted(s)))
+    return result
+
+
+def minimal_siphons(
+    net: PetriNet,
+    *,
+    max_size: Optional[int] = None,
+    max_nodes: int = DEFAULT_MAX_NODES,
+    strict_limit: bool = False,
+) -> List[Set[str]]:
+    """Enumerate the inclusion-minimal siphons of a Petri net.
+
+    :param net:
+        Petri net to analyse.
+    :type net: PetriNet
+
+    :param max_size:
+        Optional ceiling on siphon size. Filtering happens after enumeration,
+        so the result is exactly the minimal siphons no larger than the bound.
+    :type max_size: Optional[int]
+
+    :param max_nodes:
+        Maximum number of closure evaluations before the search stops.
+    :type max_nodes: int
+
+    :param strict_limit:
+        Raise :class:`SiphonSearchLimit` instead of returning a partial result
+        when the budget is exhausted.
+    :type strict_limit: bool
+
+    :return:
+        Minimal siphons, ordered by size then lexicographically.
+    :rtype: List[Set[str]]
+
+    .. rubric:: Example
+
+    .. code-block:: python
+
+        minimal_siphons(net, max_size=4)
+    """
+    pre, post = _incidence(net)
+    return _enumerate_minimal(
+        net,
+        trigger=post,
+        required=pre,
+        max_size=max_size,
+        max_nodes=max_nodes,
+        strict_limit=strict_limit,
+    )
+
+
+def minimal_traps(
+    net: PetriNet,
+    *,
+    max_size: Optional[int] = None,
+    max_nodes: int = DEFAULT_MAX_NODES,
+    strict_limit: bool = False,
+) -> List[Set[str]]:
+    """Enumerate the inclusion-minimal traps of a Petri net.
+
+    :param net:
+        Petri net to analyse.
+    :type net: PetriNet
+
+    :param max_size:
+        Optional ceiling on trap size.
+    :type max_size: Optional[int]
+
+    :param max_nodes:
+        Maximum number of closure evaluations before the search stops.
+    :type max_nodes: int
+
+    :param strict_limit:
+        Raise :class:`SiphonSearchLimit` instead of returning a partial result
+        when the budget is exhausted.
+    :type strict_limit: bool
+
+    :return:
+        Minimal traps, ordered by size then lexicographically.
+    :rtype: List[Set[str]]
+
+    .. rubric:: Example
+
+    .. code-block:: python
+
+        minimal_traps(net)
+    """
+    pre, post = _incidence(net)
+    return _enumerate_minimal(
+        net,
+        trigger=pre,
+        required=post,
+        max_size=max_size,
+        max_nodes=max_nodes,
+        strict_limit=strict_limit,
+    )

synkit/CRN/Petrinet/structure.py

@@ -0,0 +1,286 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Set
+
+from .net import PetriNet
+from .siphon_search import DEFAULT_MAX_NODES, minimal_siphons, minimal_traps
+
+
+def _as_petri(crn: Any) -> PetriNet:
+    """Convert a SynCRN-like object into a :class:`PetriNet`.
+
+    If ``crn`` is already a :class:`PetriNet`, it is returned unchanged.
+    Otherwise, the object is converted using :meth:`PetriNet.from_syncrn`.
+
+    :param crn: SynCRN-like object or an existing :class:`PetriNet`.
+    :type crn: Any
+    :return: Petri-net representation of the input object.
+    :rtype: PetriNet
+    """
+    return crn if isinstance(crn, PetriNet) else PetriNet.from_syncrn(crn)
+
+
+def _is_siphon(net: PetriNet, places: Set[str]) -> bool:
+    """Test whether a set of places is a siphon.
+
+    A place set ``S`` is a siphon if every transition that produces tokens into
+    ``S`` also consumes at least one token from ``S``.
+
+    :param net: Petri net to inspect.
+    :type net: PetriNet
+    :param places: Candidate place set.
+    :type places: Set[str]
+    :return:
+        ``True`` if ``places`` is a non-empty siphon, otherwise ``False``.
+    :rtype: bool
+    """
+    if not places:
+        return False
+    for tid in net.transition_order:
+        t = net.transitions[tid]
+        produces_into_s = any(p in places and w > 0 for p, w in t.post.items())
+        if not produces_into_s:
+            continue
+        consumes_from_s = any(p in places and w > 0 for p, w in t.pre.items())
+        if not consumes_from_s:
+            return False
+    return True
+
+
+def _is_trap(net: PetriNet, places: Set[str]) -> bool:
+    """Test whether a set of places is a trap.
+
+    A place set ``S`` is a trap if every transition that consumes tokens from
+    ``S`` also produces at least one token back into ``S``.
+
+    :param net: Petri net to inspect.
+    :type net: PetriNet
+    :param places: Candidate place set.
+    :type places: Set[str]
+    :return:
+        ``True`` if ``places`` is a non-empty trap, otherwise ``False``.
+    :rtype: bool
+    """
+    if not places:
+        return False
+    for tid in net.transition_order:
+        t = net.transitions[tid]
+        consumes_from_s = any(p in places and w > 0 for p, w in t.pre.items())
+        if not consumes_from_s:
+            continue
+        produces_into_s = any(p in places and w > 0 for p, w in t.post.items())
+        if not produces_into_s:
+            return False
+    return True
+
+
+def _minimal_sets(candidates: List[Set[str]]) -> List[Set[str]]:
+    """Reduce a collection of candidate sets to inclusion-minimal sets.
+
+    The result contains only those sets for which no strict subset is also
+    present among the candidates.
+
+    :param candidates: Candidate place sets.
+    :type candidates: List[Set[str]]
+    :return: Inclusion-minimal subset of the input candidates.
+    :rtype: List[Set[str]]
+    """
+    candidates = sorted(candidates, key=lambda s: (len(s), sorted(s)))
+    out: List[Set[str]] = []
+    for s in candidates:
+        if any(t.issubset(s) for t in out):
+            continue
+        out = [t for t in out if not s.issubset(t)]
+        out.append(s)
+    return out
+
+
+def _render_place_sets(
+    net: PetriNet,
+    sets_: List[Set[str]],
+    *,
+    names: str,
+) -> List[Set[str]]:
+    """Render place sets either by internal ids or by place labels.
+
+    :param net: Petri net providing place-name lookup.
+    :type net: PetriNet
+    :param sets_: Place sets expressed in internal place ids.
+    :type sets_: List[Set[str]]
+    :param names:
+        Output naming mode. Supported values are ``"id"`` and ``"label"``.
+    :type names: str
+    :return:
+        Place sets rendered according to the requested naming convention.
+    :rtype: List[Set[str]]
+    :raises ValueError: If ``names`` is not ``"id"`` or ``"label"``.
+    """
+    if names == "id":
+        return [set(s) for s in sets_]
+    if names == "label":
+        return [{net.place_name(p) for p in s} for s in sets_]
+    raise ValueError("names must be 'id' or 'label'")
+
+
+def find_siphons(
+    crn: Any,
+    *,
+    max_size: Optional[int] = None,
+    names: str = "label",
+    max_nodes: int = DEFAULT_MAX_NODES,
+    strict_limit: bool = False,
+) -> List[Set[str]]:
+    """Enumerate inclusion-minimal siphons of a SynCRN Petri-net view.
+
+    The search uses the maximal-siphon closure operator with branch-and-bound
+    descent rather than brute-force subset enumeration; see
+    :mod:`synkit.CRN.Petrinet.siphon_search`.
+
+    :param crn: SynCRN-like object or :class:`PetriNet`.
+    :type crn: Any
+    :param max_size:
+        Maximum siphon size to consider. ``None`` means all sizes.
+    :type max_size: int | None
+    :param names:
+        Whether to return internal place ids or species labels.
+        Supported values are ``"id"`` and ``"label"``.
+    :type names: str
+    :param max_nodes:
+        Exploration budget for the branch-and-bound search.
+    :type max_nodes: int
+    :param strict_limit:
+        Raise :class:`~synkit.CRN.Petrinet.siphon_search.SiphonSearchLimit`
+        instead of returning a partial result when the budget is exhausted.
+    :type strict_limit: bool
+    :return: Inclusion-minimal siphons.
+    :rtype: List[Set[str]]
+    """
+    from ..backend import resolve_backend
+
+    backend, library = resolve_backend()
+    if backend == "cpp":
+        from ..native import enumerate_structural_sets
+        from .siphon_search import SiphonSearchLimit
+
+        net = _as_petri(crn)
+        result = enumerate_structural_sets(
+            net, kind="siphon", backend="cpp", library_path=library, max_nodes=max_nodes
+        )
+        if not result.complete:
+            error = SiphonSearchLimit(result.termination_reason)
+            error.result = result
+            raise error
+        sets_ = [
+            set(group)
+            for group in result.value["sets"]
+            if max_size is None or len(group) <= max_size
+        ]
+        return _render_place_sets(net, sets_, names=names)
+    net = _as_petri(crn)
+    sets_ = minimal_siphons(
+        net,
+        max_size=max_size,
+        max_nodes=max_nodes,
+        strict_limit=strict_limit,
+    )
+    return _render_place_sets(net, sets_, names=names)
+
+
+def find_traps(
+    crn: Any,
+    *,
+    max_size: Optional[int] = None,
+    names: str = "label",
+    max_nodes: int = DEFAULT_MAX_NODES,
+    strict_limit: bool = False,
+) -> List[Set[str]]:
+    """Enumerate inclusion-minimal traps of a SynCRN Petri-net view.
+
+    The search uses the maximal-siphon closure operator with branch-and-bound
+    descent rather than brute-force subset enumeration; see
+    :mod:`synkit.CRN.Petrinet.siphon_search`.
+
+    :param crn: SynCRN-like object or :class:`PetriNet`.
+    :type crn: Any
+    :param max_size:
+        Maximum trap size to consider. ``None`` means all sizes.
+    :type max_size: int | None
+    :param names:
+        Whether to return internal place ids or species labels.
+        Supported values are ``"id"`` and ``"label"``.
+    :type names: str
+    :param max_nodes:
+        Exploration budget for the branch-and-bound search.
+    :type max_nodes: int
+    :param strict_limit:
+        Raise :class:`~synkit.CRN.Petrinet.siphon_search.SiphonSearchLimit`
+        instead of returning a partial result when the budget is exhausted.
+    :type strict_limit: bool
+    :return: Inclusion-minimal traps.
+    :rtype: List[Set[str]]
+    """
+    from ..backend import resolve_backend
+
+    backend, library = resolve_backend()
+    if backend == "cpp":
+        from ..native import enumerate_structural_sets
+        from .siphon_search import SiphonSearchLimit
+
+        net = _as_petri(crn)
+        result = enumerate_structural_sets(
+            net, kind="trap", backend="cpp", library_path=library, max_nodes=max_nodes
+        )
+        if not result.complete:
+            error = SiphonSearchLimit(result.termination_reason)
+            error.result = result
+            raise error
+        sets_ = [
+            set(group)
+            for group in result.value["sets"]
+            if max_size is None or len(group) <= max_size
+        ]
+        return _render_place_sets(net, sets_, names=names)
+    net = _as_petri(crn)
+    sets_ = minimal_traps(
+        net,
+        max_size=max_size,
+        max_nodes=max_nodes,
+        strict_limit=strict_limit,
+    )
+    return _render_place_sets(net, sets_, names=names)
+
+
+def species_transition_neighborhoods(crn: Any) -> Dict[str, Dict[str, List[str]]]:
+    """Return per-species producer and consumer transition neighborhoods.
+
+    This is a small structural helper that is often useful when debugging
+    siphons, traps, and reachability issues.
+
+    The returned dictionary is keyed by internal place id. For each place, the
+    value contains the display label, the transitions that produce tokens into
+    the place, and the transitions that consume tokens from it.
+
+    :param crn: SynCRN-like object or :class:`PetriNet`.
+    :type crn: Any
+    :return:
+        Mapping from place id to a dictionary with keys ``"label"``,
+        ``"producer_transitions"``, and ``"consumer_transitions"``.
+    :rtype: Dict[str, Dict[str, List[str]]]
+    """
+    net = _as_petri(crn)
+    out: Dict[str, Dict[str, List[str]]] = {}
+    for p in net.place_order:
+        producers: List[str] = []
+        consumers: List[str] = []
+        for tid in net.transition_order:
+            t = net.transitions[tid]
+            if p in t.post:
+                producers.append(tid)
+            if p in t.pre:
+                consumers.append(tid)
+        out[p] = {
+            "label": net.place_name(p),
+            "producer_transitions": producers,
+            "consumer_transitions": consumers,
+        }
+    return out