openprocess 0.7.0__py3-none-any.whl

openprocess/mining/petrinet.py

@@ -0,0 +1,354 @@
+"""Place/Transition nets, the model class that discovery produces.
+
+Definitions (van der Aalst, *Workflow Verification*, §2)
+-------------------------------------------------------
+A Petri net is a triple ``(P, T, F)``:
+
+* ``P`` -- a finite set of **places** (drawn as circles),
+* ``T`` -- a finite set of **transitions** (drawn as squares), disjoint from P,
+* ``F ⊆ (P × T) ∪ (T × P)`` -- the **flow relation** (the arcs).
+
+We also allow an arc *weight* (default 1), which the textbook's basic nets do
+not need but PNML files sometimes contain.
+
+The **pre-set** ``•x`` of a node is the set of nodes with an arc *into* x,
+the **post-set** ``x•`` those with an arc *out of* x.
+
+A **marking** assigns a number of tokens to every place; formally a multiset
+over P, e.g. ``[i]`` or ``[p1, p2^2]``.
+
+**Firing rule.**  Transition ``t`` is *enabled* in marking M iff every input
+place holds at least as many tokens as the arc weight requires.  Firing t
+removes those tokens and adds tokens to every output place::
+
+    M' = M - •t + t•
+
+Labelled nets
+-------------
+In process mining every transition carries an **activity label** (e.g.
+``"register request"``) -- or no label at all.  An unlabelled transition is a
+**silent** (τ, "tau") transition: it moves tokens but leaves no trace in the
+log.  Discovery algorithms such as the Inductive Miner use τ transitions to
+express skips and loop-backs.  Two transitions may share a label
+(*duplicate* labels); the α-algorithm never produces those, but hand-made
+models can have them.
+
+Accepting Petri nets
+--------------------
+For conformance checking a net also needs an **initial** and a **final**
+marking: a log trace "fits" if the model can start in the initial marking,
+replay the trace, and end in the final marking.  :class:`PetriNet` therefore
+stores both.
+"""
+
+from __future__ import annotations
+
+import itertools
+from collections import Counter
+from dataclasses import dataclass, field
+from typing import Iterable, Iterator, Mapping
+
+
+# ---------------------------------------------------------------------------
+# Markings
+# ---------------------------------------------------------------------------
+class Marking(Mapping[str, int]):
+    """An immutable multiset of place ids.
+
+    Immutability matters: markings are stored in sets and used as dictionary
+    keys during state-space exploration, which requires a hash that never
+    changes.  Every operation therefore returns a *new* marking.
+
+    Zero counts are never stored, so ``Marking({"p": 0}) == Marking()``.
+    """
+
+    __slots__ = ("_counts", "_hash")
+
+    def __init__(self, counts: Mapping[str, int] | Iterable[str] | None = None) -> None:
+        if counts is None:
+            data: dict[str, int] = {}
+        elif isinstance(counts, Mapping):
+            # Counts are ints, or math.inf (ω) in coverability graphs.
+            data = {place: n for place, n in counts.items() if n}
+        else:
+            data = dict(Counter(counts))
+        self._counts = data
+        self._hash: int | None = None
+
+    # Mapping protocol -------------------------------------------------------
+    def __getitem__(self, place: str) -> int:
+        return self._counts.get(place, 0)
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._counts)
+
+    def __len__(self) -> int:
+        return len(self._counts)
+
+    def __contains__(self, place: object) -> bool:
+        return place in self._counts
+
+    def __hash__(self) -> int:
+        if self._hash is None:
+            self._hash = hash(frozenset(self._counts.items()))
+        return self._hash
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Marking):
+            return self._counts == other._counts
+        if isinstance(other, Mapping):
+            return self._counts == {k: v for k, v in other.items() if v}
+        return NotImplemented
+
+    # Multiset algebra -------------------------------------------------------
+    def __add__(self, other: Mapping[str, int]) -> "Marking":
+        result = dict(self._counts)
+        for place, n in other.items():
+            result[place] = result.get(place, 0) + n
+        return Marking(result)
+
+    def __sub__(self, other: Mapping[str, int]) -> "Marking":
+        """Multiset difference; the caller guarantees ``other ≤ self``."""
+        result = dict(self._counts)
+        for place, n in other.items():
+            result[place] = result.get(place, 0) - n
+        return Marking(result)
+
+    def __ge__(self, other: Mapping[str, int]) -> bool:  # type: ignore[override]
+        """``self ≥ other`` pointwise: every place has at least as many tokens."""
+        return all(self._counts.get(place, 0) >= n for place, n in other.items())
+
+    def __le__(self, other: Mapping[str, int]) -> bool:  # type: ignore[override]
+        return all(other.get(place, 0) >= n for place, n in self._counts.items())
+
+    @property
+    def total(self) -> int:
+        return sum(self._counts.values())
+
+    def items(self):  # type: ignore[override]
+        return self._counts.items()
+
+    def describe(self, net: "PetriNet | None" = None) -> str:
+        """Textbook notation, e.g. ``[p1, p2^2]``; ``[]`` for the empty marking."""
+        def name(place_id: str) -> str:
+            if net is not None and place_id in net.places:
+                return net.places[place_id].name
+            return place_id
+        parts = []
+        for place_id in sorted(self._counts, key=name):
+            n = self._counts[place_id]
+            count = "ω" if n == float("inf") else str(n)
+            parts.append(name(place_id) + (f"^{count}" if n != 1 else ""))
+        return "[" + ", ".join(parts) + "]"
+
+    def __repr__(self) -> str:
+        return f"Marking({self._counts!r})"
+
+
+# ---------------------------------------------------------------------------
+# Nodes and arcs
+# ---------------------------------------------------------------------------
+@dataclass(eq=False)
+class Place:
+    id: str
+    name: str
+    position: tuple[float, float] | None = None
+    #: Where the name label sits, relative to the node (drawing only).
+    name_offset: tuple[float, float] | None = None
+
+
+@dataclass(eq=False)
+class Transition:
+    id: str
+    name: str
+    label: str | None = None     # None means silent (τ)
+    position: tuple[float, float] | None = None
+    #: Where the name label sits, relative to the node (drawing only).
+    name_offset: tuple[float, float] | None = None
+
+    @property
+    def silent(self) -> bool:
+        return self.label is None
+
+
+@dataclass(eq=False)
+class Arc:
+    source: str      # a place id or transition id
+    target: str
+    weight: int = 1
+    #: Bend points from source to target (drawing only; PNML ``<position>``s).
+    points: list[tuple[float, float]] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# The net
+# ---------------------------------------------------------------------------
+@dataclass(eq=False)
+class PetriNet:
+    """A labelled P/T net with an initial and a final marking."""
+
+    name: str = "Petri net"
+    places: dict[str, Place] = field(default_factory=dict)
+    transitions: dict[str, Transition] = field(default_factory=dict)
+    arcs: list[Arc] = field(default_factory=list)
+    initial_marking: Marking = field(default_factory=Marking)
+    final_marking: Marking = field(default_factory=Marking)
+    #: Free-form provenance, e.g. ``{"algorithm": "Alpha", "log": "..."}``.
+    info: dict[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self._ids = itertools.count(1)
+        self._cache: dict | None = None
+
+    # -- construction -----------------------------------------------------
+    def _fresh_id(self, prefix: str) -> str:
+        while True:
+            candidate = f"{prefix}{next(self._ids)}"
+            if candidate not in self.places and candidate not in self.transitions:
+                return candidate
+
+    def add_place(self, name: str | None = None, id: str | None = None) -> Place:
+        place_id = id or self._fresh_id("p")
+        place = Place(place_id, name if name is not None else place_id)
+        self.places[place_id] = place
+        self._cache = None
+        return place
+
+    def add_transition(self, label: str | None, name: str | None = None,
+                       id: str | None = None) -> Transition:
+        """Add a transition; ``label=None`` makes it silent."""
+        transition_id = id or self._fresh_id("t")
+        display = name if name is not None else (label if label is not None else "τ")
+        transition = Transition(transition_id, display, label)
+        self.transitions[transition_id] = transition
+        self._cache = None
+        return transition
+
+    def add_arc(self, source: Place | Transition | str, target: Place | Transition | str,
+                weight: int = 1) -> Arc:
+        source_id = source if isinstance(source, str) else source.id
+        target_id = target if isinstance(target, str) else target.id
+        source_is_place = source_id in self.places
+        target_is_place = target_id in self.places
+        if source_is_place == target_is_place:
+            raise ValueError("An arc must connect a place and a transition "
+                             f"({source_id!r} -> {target_id!r}).")
+        arc = Arc(source_id, target_id, weight)
+        self.arcs.append(arc)
+        self._cache = None
+        return arc
+
+    def remove_place(self, place_id: str) -> None:
+        self.places.pop(place_id, None)
+        self.arcs = [a for a in self.arcs if place_id not in (a.source, a.target)]
+        self._cache = None
+
+    def remove_transition(self, transition_id: str) -> None:
+        self.transitions.pop(transition_id, None)
+        self.arcs = [a for a in self.arcs if transition_id not in (a.source, a.target)]
+        self._cache = None
+
+    # -- structure (cached; rebuilt after any edit) ------------------------
+    def _structure(self) -> dict:
+        if self._cache is None:
+            pre: dict[str, Counter] = {t: Counter() for t in self.transitions}
+            post: dict[str, Counter] = {t: Counter() for t in self.transitions}
+            place_in: dict[str, set[str]] = {p: set() for p in self.places}
+            place_out: dict[str, set[str]] = {p: set() for p in self.places}
+            for arc in self.arcs:
+                if arc.source in self.transitions:          # t -> p
+                    post[arc.source][arc.target] += arc.weight
+                    place_in[arc.target].add(arc.source)
+                else:                                         # p -> t
+                    pre[arc.target][arc.source] += arc.weight
+                    place_out[arc.source].add(arc.target)
+            self._cache = {
+                "pre": {t: Marking(c) for t, c in pre.items()},
+                "post": {t: Marking(c) for t, c in post.items()},
+                "place_in": place_in,
+                "place_out": place_out,
+            }
+        return self._cache
+
+    def pre(self, transition_id: str) -> Marking:
+        """The input places of ``t`` with arc weights (•t as a multiset)."""
+        return self._structure()["pre"][transition_id]
+
+    def post(self, transition_id: str) -> Marking:
+        """The output places of ``t`` with arc weights (t• as a multiset)."""
+        return self._structure()["post"][transition_id]
+
+    def preset(self, node_id: str) -> set[str]:
+        """•x for any node."""
+        if node_id in self.transitions:
+            return set(self.pre(node_id))
+        return set(self._structure()["place_in"][node_id])
+
+    def postset(self, node_id: str) -> set[str]:
+        """x• for any node."""
+        if node_id in self.transitions:
+            return set(self.post(node_id))
+        return set(self._structure()["place_out"][node_id])
+
+    # -- behaviour --------------------------------------------------------
+    def is_enabled(self, marking: Marking, transition_id: str) -> bool:
+        return marking >= self.pre(transition_id)
+
+    def enabled(self, marking: Marking) -> list[str]:
+        """Ids of all transitions enabled in ``marking``, in a stable order."""
+        return [t for t in self.transitions if marking >= self.pre(t)]
+
+    def fire(self, marking: Marking, transition_id: str) -> Marking:
+        """``M' = M - •t + t•``.  Raises if ``t`` is not enabled."""
+        pre = self.pre(transition_id)
+        if not marking >= pre:
+            raise ValueError(f"Transition {self.transitions[transition_id].name!r} "
+                             f"is not enabled in {marking.describe(self)}.")
+        return marking - pre + self.post(transition_id)
+
+    # -- queries ----------------------------------------------------------
+    def labels(self) -> set[str]:
+        """The set of visible activity labels."""
+        return {t.label for t in self.transitions.values() if t.label is not None}
+
+    def transitions_with_label(self, label: str) -> list[str]:
+        return [t.id for t in self.transitions.values() if t.label == label]
+
+    def source_places(self) -> list[str]:
+        """Places with an empty pre-set."""
+        return [p for p in self.places if not self._structure()["place_in"][p]]
+
+    def sink_places(self) -> list[str]:
+        """Places with an empty post-set."""
+        return [p for p in self.places if not self._structure()["place_out"][p]]
+
+    def node_name(self, node_id: str) -> str:
+        if node_id in self.places:
+            return self.places[node_id].name
+        if node_id in self.transitions:
+            return self.transitions[node_id].name
+        return node_id
+
+    def copy(self) -> "PetriNet":
+        clone = PetriNet(self.name)
+        for p in self.places.values():
+            clone.places[p.id] = Place(p.id, p.name, p.position)
+        for t in self.transitions.values():
+            clone.transitions[t.id] = Transition(t.id, t.name, t.label, t.position)
+        clone.arcs = [Arc(a.source, a.target, a.weight) for a in self.arcs]
+        clone.initial_marking = self.initial_marking
+        clone.final_marking = self.final_marking
+        clone.info = dict(self.info)
+        return clone
+
+    def summary(self) -> str:
+        silent = sum(1 for t in self.transitions.values() if t.silent)
+
+        def count(number: int, noun: str) -> str:
+            return f"{number} {noun}{'' if number == 1 else 's'}"
+        return (f"{count(len(self.places), 'place')}, "
+                f"{count(len(self.transitions), 'transition')} ({silent} silent), "
+                f"{count(len(self.arcs), 'arc')}")
+
+    def __repr__(self) -> str:
+        return f"<PetriNet {self.name!r}: {self.summary()}>"

openprocess/mining/playout.py

@@ -0,0 +1,75 @@
+"""Play-out: generate an event log by simulating a Petri net.
+
+This is the reverse direction of discovery.  Starting from the initial
+marking, repeatedly pick a random enabled transition and fire it; the labels
+of the visible transitions fired form one trace.  A run ends when
+
+* the net reaches its **final marking** (a completed case), or
+* nothing is enabled (a deadlock -- the trace is kept but marked), or
+* the run exceeds ``max_length`` firings (e.g. a loop that could go on forever).
+
+Why it is useful in the course: simulate a model, mine the generated log,
+and compare the discovered model with the original.  A sound model's log
+rediscovered by the Inductive Miner should give back the same behaviour.
+
+Timestamps are synthetic: each case starts ``case_gap`` after the previous
+one and each visible event takes ``event_gap``, so the dotted chart and
+performance views have something regular to show.
+"""
+
+from __future__ import annotations
+
+import random
+from collections import Counter
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+
+from .log import KEY_NAME, KEY_TIME, Event, EventLog, Trace
+from .petrinet import PetriNet
+
+
+@dataclass
+class PlayoutResult:
+    log: EventLog
+    completed: int          # runs that reached the final marking
+    deadlocked: int         # runs that got stuck elsewhere
+    cut_off: int            # runs stopped at max_length
+
+
+def random_run(net: PetriNet, rng: random.Random, max_length: int = 200):
+    """One random run: (visible labels, how it ended)."""
+    marking = net.initial_marking
+    labels: list[str] = []
+    for _ in range(max_length):
+        if net.final_marking and marking == net.final_marking:
+            return labels, "completed"
+        enabled = net.enabled(marking)
+        if not enabled:
+            return labels, "deadlocked"
+        transition = rng.choice(enabled)
+        marking = net.fire(marking, transition)
+        label = net.transitions[transition].label
+        if label is not None:
+            labels.append(label)
+    if net.final_marking and marking == net.final_marking:
+        return labels, "completed"
+    return labels, "cut off"
+
+
+def play_out(net: PetriNet, traces: int = 100, max_length: int = 200, seed: int | None = None,
+             name: str | None = None, start: datetime | None = None,
+             case_gap: timedelta = timedelta(minutes=5),
+             event_gap: timedelta = timedelta(minutes=1)) -> PlayoutResult:
+    rng = random.Random(seed)
+    start = start or datetime(2024, 1, 1, 9, 0, tzinfo=timezone.utc)
+    log = EventLog(attributes={KEY_NAME: name or f"Play-out of {net.name}"})
+    outcomes: Counter = Counter()
+    for number in range(traces):
+        labels, outcome = random_run(net, rng, max_length)
+        outcomes[outcome] += 1
+        begin = start + number * case_gap
+        trace = Trace({KEY_NAME: f"case {number + 1}", "playout:outcome": outcome})
+        for position, label in enumerate(labels):
+            trace.events.append(Event({KEY_NAME: label, KEY_TIME: begin + position * event_gap}))
+        log.traces.append(trace)
+    return PlayoutResult(log, outcomes["completed"], outcomes["deadlocked"], outcomes["cut off"])

openprocess/mining/pm4py_bridge.py

@@ -0,0 +1,82 @@
+"""Optional bridge to PM4Py for the algorithms not implemented natively.
+
+PM4Py is *not* a dependency.  If it is installed (``pip install -e ".[pm4py]"``)
+the app offers these extra discovery algorithms:
+
+* **Heuristics → Petri net (PM4Py)** -- PM4Py's own heuristics net, to
+  compare with the built-in one (:func:`..discovery.heuristics.heuristics_net`);
+* **ILP Miner** -- region-based discovery via integer linear programming;
+* **Split Miner**-style / other miners can be added here the same way.
+
+Models travel between the two libraries as PNML text, the neutral exchange
+format, so nothing in the rest of OpenProcess ever imports PM4Py.
+
+Licensing note: PM4Py is AGPL-3.0.  Importing it at run time from this
+optional module keeps the OpenProcess code base itself independent of it.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from collections import Counter
+from importlib.util import find_spec
+
+from .log import SimpleLog
+from .petrinet import PetriNet
+from .pnml import parse_pnml
+
+
+def available() -> bool:
+    return find_spec("pm4py") is not None
+
+
+def _dataframe(log: SimpleLog):
+    import pandas as pd
+
+    rows, case = [], 0
+    base = pd.Timestamp("2000-01-01")
+    for sequence, count in log.items():
+        for _ in range(count):
+            case += 1
+            for position, activity in enumerate(sequence):
+                rows.append({"case:concept:name": str(case), "concept:name": activity,
+                             "time:timestamp": base + pd.Timedelta(minutes=position)})
+    return pd.DataFrame(rows)
+
+
+def _to_native(net, initial, final, name: str) -> PetriNet:
+    import pm4py
+
+    handle, path = tempfile.mkstemp(suffix=".pnml")
+    os.close(handle)
+    try:
+        pm4py.write_pnml(net, initial, final, path)
+        with open(path, "rb") as stream:
+            native = parse_pnml(stream.read())
+    finally:
+        os.unlink(path)
+    native.name = name
+    return native
+
+
+def heuristics_petri_net(log: SimpleLog, dependency_threshold: float = 0.5) -> PetriNet:
+    import pm4py
+
+    net, im, fm = pm4py.discover_petri_net_heuristics(
+        _dataframe(log), dependency_threshold=dependency_threshold)
+    result = _to_native(net, im, fm, "Heuristics (PM4Py)")
+    result.info["algorithm"] = f"Heuristics Miner via PM4Py (threshold {dependency_threshold:g})"
+    return result
+
+
+def ilp_petri_net(log: SimpleLog, alpha: float = 1.0) -> PetriNet:
+    import pm4py
+
+    net, im, fm = pm4py.discover_petri_net_ilp(_dataframe(log), alpha=alpha)
+    result = _to_native(net, im, fm, "ILP (PM4Py)")
+    result.info["algorithm"] = f"ILP Miner via PM4Py (alpha {alpha:g})"
+    return result
+
+
+__all__ = ["available", "heuristics_petri_net", "ilp_petri_net", "Counter"]