openprocess 0.7.0__py3-none-any.whl

openprocess/mining/pnml.py

@@ -0,0 +1,223 @@
+"""PNML: the ISO/IEC 15909-2 interchange format for Petri nets.
+
+PNML is what ProM, PM4Py, WoPeD and most academic tools read and write, so
+it is the way to move a discovered model between this app and anything else.
+
+The subset we handle (the "P/T net" type)::
+
+    <pnml>
+      <net id="net1" type="http://www.pnml.org/version-2009/grammar/ptnet">
+        <name><text>My net</text></name>
+        <page id="page1">
+          <place id="p1">
+            <name><text>start</text></name>
+            <initialMarking><text>1</text></initialMarking>
+            <graphics><position x="10" y="20"/></graphics>
+          </place>
+          <transition id="t1">
+            <name><text>register</text></name>
+            <toolspecific tool="ProM" version="6.4" activity="$invisible$"/>
+          </transition>
+          <arc id="a1" source="p1" target="t1">
+            <inscription><text>1</text></inscription>
+          </arc>
+        </page>
+        <finalmarkings>                         <- ProM extension
+          <marking><place idref="p9"><text>1</text></place></marking>
+        </finalmarkings>
+      </net>
+    </pnml>
+
+Silent transitions are marked with ProM's ``toolspecific`` element
+``activity="$invisible$"``; that is the convention PM4Py follows too.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from xml.etree import ElementTree as ET
+from xml.sax.saxutils import escape, quoteattr
+
+from .petrinet import Marking, PetriNet
+
+_INVISIBLE = "$invisible$"
+
+
+def _local(tag: str) -> str:
+    return tag.rsplit("}", 1)[-1]
+
+
+def _child(element: ET.Element, name: str) -> ET.Element | None:
+    for child in element:
+        if _local(child.tag) == name:
+            return child
+    return None
+
+
+def _text_of(element: ET.Element | None) -> str | None:
+    """The ``<text>`` content of a PNML label such as ``<name>``."""
+    if element is None:
+        return None
+    text = _child(element, "text")
+    return text.text.strip() if text is not None and text.text else None
+
+
+def parse_pnml(text: str | bytes) -> PetriNet:
+    root = ET.fromstring(text)
+    net_element = root if _local(root.tag) == "net" else next(
+        (e for e in root.iter() if _local(e.tag) == "net"), None)
+    if net_element is None:
+        raise ValueError("No <net> element found; is this a PNML file?")
+
+    net = PetriNet(_text_of(_child(net_element, "name")) or net_element.get("id") or "Petri net")
+    initial: dict[str, int] = {}
+    arcs: list[tuple[str, str, int]] = []
+
+    # Nodes may sit inside (nested) <page> elements or directly under <net>.
+    for element in net_element.iter():
+        tag = _local(element.tag)
+        # <place idref=...> inside <finalmarkings> is a reference, not a node:
+        # only elements with an id define places, transitions and arcs.
+        if element.get("id") is None:
+            continue
+        if tag == "place":
+            place = net.add_place(_text_of(_child(element, "name")) or element.get("id"),
+                                  id=element.get("id"))
+            place.position = _position(element)
+            place.name_offset = _name_offset(element)
+            tokens = _text_of(_child(element, "initialMarking"))
+            if tokens and tokens.isdigit() and int(tokens) > 0:
+                initial[place.id] = int(tokens)
+        elif tag == "transition":
+            name = _text_of(_child(element, "name")) or element.get("id")
+            invisible = any(
+                _local(sub.tag) == "toolspecific" and sub.get("activity") == _INVISIBLE
+                for sub in element)
+            transition = net.add_transition(None if invisible else name, name=name,
+                                            id=element.get("id"))
+            transition.position = _position(element)
+            transition.name_offset = _name_offset(element)
+        elif tag == "arc":
+            weight_text = _text_of(_child(element, "inscription"))
+            weight = int(weight_text) if weight_text and weight_text.isdigit() else 1
+            graphics = _child(element, "graphics")
+            points = []
+            if graphics is not None:
+                for sub in graphics:
+                    if _local(sub.tag) == "position":
+                        points.append((float(sub.get("x", 0)), float(sub.get("y", 0))))
+            arcs.append((element.get("source"), element.get("target"), weight, points))
+
+    for source, target, weight, points in arcs:
+        net.add_arc(source, target, weight).points = points
+    for element in net_element:
+        if _local(element.tag) == "toolspecific" and element.get("tool") == "OpenProcess" \
+                and element.get("namesOutside") == "true":
+            net.info["names_outside"] = "true"
+    net.initial_marking = Marking(initial)
+
+    final: dict[str, int] = {}
+    finals = _child(net_element, "finalmarkings")
+    if finals is not None:
+        marking = _child(finals, "marking")
+        if marking is not None:
+            for place in marking:
+                tokens = _text_of(place)
+                if tokens and tokens.isdigit() and int(tokens) > 0:
+                    final[place.get("idref")] = int(tokens)
+    if final:
+        net.final_marking = Marking(final)
+    else:
+        # No final marking stored: for a workflow net the obvious choice is
+        # one token in the sink place.
+        sinks = net.sink_places()
+        if len(sinks) == 1:
+            net.final_marking = Marking({sinks[0]: 1})
+    return net
+
+
+def _position(element: ET.Element) -> tuple[float, float] | None:
+    graphics = _child(element, "graphics")
+    position = _child(graphics, "position") if graphics is not None else None
+    if position is None:
+        return None
+    try:
+        return float(position.get("x", 0)), float(position.get("y", 0))
+    except ValueError:
+        return None
+
+
+def _name_offset(element: ET.Element) -> tuple[float, float] | None:
+    """``<name><graphics><offset x y/></graphics></name>``: where the label is."""
+    name = _child(element, "name")
+    graphics = _child(name, "graphics") if name is not None else None
+    offset = _child(graphics, "offset") if graphics is not None else None
+    if offset is None:
+        return None
+    try:
+        return float(offset.get("x", 0)), float(offset.get("y", 0))
+    except ValueError:
+        return None
+
+
+def read_pnml(path: str | Path) -> PetriNet:
+    net = parse_pnml(Path(path).read_bytes())
+    net.info.setdefault("source", str(path))
+    return net
+
+
+def pnml_string(net: PetriNet, positions: dict[str, tuple[float, float]] | None = None) -> str:
+    """Serialise ``net``.  ``positions`` (e.g. from the layout) overrides stored ones."""
+    positions = positions or {}
+
+    def graphics(node_id: str, stored) -> str:
+        point = positions.get(node_id, stored)
+        if point is None:
+            return ""
+        return (f'<graphics><position x="{point[0]:.1f}" y="{point[1]:.1f}"/>'
+                f'<dimension x="40" y="40"/></graphics>')
+
+    def name(node) -> str:
+        """The node's name, with the label position when one was set."""
+        offset = getattr(node, "name_offset", None)
+        where = (f'<graphics><offset x="{offset[0]:.1f}" y="{offset[1]:.1f}"/></graphics>'
+                 if offset is not None else "")
+        return f"<name><text>{escape(node.name)}</text>{where}</name>"
+
+    lines = ['<?xml version="1.0" encoding="UTF-8"?>', "<pnml>",
+             f'  <net id="net1" type="http://www.pnml.org/version-2009/grammar/pnmlcoremodel">',
+             f"    <name><text>{escape(net.name)}</text></name>"]
+    if net.info.get("names_outside") == "true":
+        # OpenProcess's drawing option: names next to the nodes, not inside.
+        lines.append('    <toolspecific tool="OpenProcess" version="1" namesOutside="true"/>')
+    lines.append('    <page id="page1">')
+    for place in net.places.values():
+        tokens = net.initial_marking[place.id]
+        marking = (f"<initialMarking><text>{tokens}</text></initialMarking>" if tokens else "")
+        lines.append(f"      <place id={quoteattr(place.id)}>{name(place)}"
+                     f"{marking}{graphics(place.id, place.position)}</place>")
+    for transition in net.transitions.values():
+        tool = ('<toolspecific tool="ProM" version="6.4" activity="$invisible$" '
+                'localNodeID="" />' if transition.silent else "")
+        lines.append(f"      <transition id={quoteattr(transition.id)}>{name(transition)}{tool}"
+                     f"{graphics(transition.id, transition.position)}</transition>")
+    for index, arc in enumerate(net.arcs, 1):
+        inscription = (f"<inscription><text>{arc.weight}</text></inscription>"
+                       if arc.weight != 1 else "")
+        bends = "".join(f'<position x="{x:.1f}" y="{y:.1f}"/>' for x, y in arc.points)
+        bends = f"<graphics>{bends}</graphics>" if bends else ""
+        lines.append(f"      <arc id=\"arc{index}\" source={quoteattr(arc.source)} "
+                     f"target={quoteattr(arc.target)}>{inscription}{bends}</arc>")
+    lines.append("    </page>")
+    if net.final_marking:
+        lines.append("    <finalmarkings><marking>")
+        for place_id, tokens in net.final_marking.items():
+            lines.append(f"      <place idref={quoteattr(place_id)}><text>{tokens}</text></place>")
+        lines.append("    </marking></finalmarkings>")
+    lines += ["  </net>", "</pnml>", ""]
+    return "\n".join(lines)
+
+
+def write_pnml(net: PetriNet, path: str | Path,
+               positions: dict[str, tuple[float, float]] | None = None) -> None:
+    Path(path).write_text(pnml_string(net, positions), encoding="utf-8")

openprocess/mining/processtree.py

@@ -0,0 +1,216 @@
+"""Process trees: block-structured models that are sound by construction.
+
+A process tree (Leemans, Fahland & van der Aalst) is a tree whose leaves are
+activities or τ (silent), and whose inner nodes are operators:
+
+=========  ======  =====================================================
+operator   symbol  meaning
+=========  ======  =====================================================
+sequence   →       execute the children in order, left to right
+choice     ×       execute exactly one child (exclusive choice, XOR)
+parallel   ∧       execute all children, interleaved in any order (AND)
+loop       ↺       execute the first child ("do"); then, any number of
+                   times, a redo child followed by the do child again
+=========  ======  =====================================================
+
+Example: ``→(a, ×(b, c), ↺(d, τ))`` means "a, then b or c, then d one or
+more times".
+
+Why the Inductive Miner produces trees rather than nets directly: every tree
+translates into a *sound* workflow net, so the IM can never return a model
+that deadlocks or leaves tokens behind -- unlike the α-algorithm.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+from .petrinet import Marking, PetriNet
+
+
+class Operator(Enum):
+    SEQUENCE = "→"
+    XOR = "×"
+    PARALLEL = "∧"
+    LOOP = "↺"
+
+
+@dataclass(eq=False)
+class ProcessTree:
+    """A node: an operator with children, or a leaf (``label`` or τ)."""
+
+    operator: Operator | None = None
+    children: list["ProcessTree"] = field(default_factory=list)
+    label: str | None = None          # leaves only; None = τ
+
+    # -- constructors -----------------------------------------------------
+    @classmethod
+    def leaf(cls, label: str | None) -> "ProcessTree":
+        return cls(label=label)
+
+    @classmethod
+    def tau(cls) -> "ProcessTree":
+        return cls(label=None)
+
+    @classmethod
+    def node(cls, operator: Operator, children: list["ProcessTree"]) -> "ProcessTree":
+        return cls(operator=operator, children=list(children))
+
+    @property
+    def is_leaf(self) -> bool:
+        return self.operator is None
+
+    @property
+    def is_tau(self) -> bool:
+        return self.is_leaf and self.label is None
+
+    # -- display ----------------------------------------------------------
+    def __str__(self) -> str:
+        if self.is_leaf:
+            return "τ" if self.label is None else self.label
+        return f"{self.operator.value}(" + ", ".join(map(str, self.children)) + ")"
+
+    __repr__ = __str__
+
+    def pretty(self, indent: str = "") -> str:
+        """Multi-line indented rendering."""
+        if self.is_leaf:
+            return indent + str(self)
+        lines = [indent + self.operator.value]
+        lines += [child.pretty(indent + "    ") for child in self.children]
+        return "\n".join(lines)
+
+    def activities(self) -> set[str]:
+        if self.is_leaf:
+            return set() if self.label is None else {self.label}
+        return set().union(*(child.activities() for child in self.children))
+
+    def simplified(self) -> "ProcessTree":
+        """Flatten nested identical operators: →(a, →(b, c)) becomes →(a, b, c).
+
+        Loops are not flattened -- ↺ is not associative.
+        """
+        if self.is_leaf:
+            return self
+        children = [child.simplified() for child in self.children]
+        flat: list[ProcessTree] = []
+        for child in children:
+            if (self.operator is not Operator.LOOP and child.operator is self.operator):
+                flat.extend(child.children)
+            else:
+                flat.append(child)
+        if len(flat) == 1 and self.operator is not Operator.LOOP:
+            return flat[0]
+        return ProcessTree.node(self.operator, flat)
+
+
+# ---------------------------------------------------------------------------
+# Translation to a workflow net
+# ---------------------------------------------------------------------------
+def to_petri_net(tree: ProcessTree, name: str = "Process tree") -> PetriNet:
+    """Translate a tree into a sound WF-net, block by block.
+
+    Every block is built between an *entry* place and an *exit* place:
+
+    * leaf ``a`` / τ:  entry → [a] → exit
+    * ``→(C1..Cn)``:   chain the children through fresh intermediate places
+    * ``×(C1..Cn)``:   every child between the same entry and exit
+    * ``∧(C1..Cn)``:   a τ *split* puts a token in each child's own entry
+      place; a τ *join* waits for all children's exit places
+    * ``↺(do, r1..rn)``: τ from entry to a loop place ``s``; ``do`` from s to
+      ``e``; each redo from ``e`` back to ``s``; τ from ``e`` to exit.  The
+      extra τs keep the loop's places private, so a redo can never re-enter
+      a choice made *outside* the loop.
+
+    Afterwards, τ transitions that merely connect two private places in
+    series are removed (Murata's "fusion of series places"), which keeps the
+    picture readable without changing behaviour.
+    """
+    net = PetriNet(name)
+    source = net.add_place("source", id="source")
+    sink = net.add_place("sink", id="sink")
+
+    def build(node: ProcessTree, entry, exit_) -> None:
+        if node.is_leaf:
+            transition = net.add_transition(node.label)
+            net.add_arc(entry, transition)
+            net.add_arc(transition, exit_)
+        elif node.operator is Operator.SEQUENCE:
+            current = entry
+            for index, child in enumerate(node.children):
+                following = exit_ if index == len(node.children) - 1 else net.add_place()
+                build(child, current, following)
+                current = following
+        elif node.operator is Operator.XOR:
+            for child in node.children:
+                build(child, entry, exit_)
+        elif node.operator is Operator.PARALLEL:
+            split = net.add_transition(None, name="τ split")
+            join = net.add_transition(None, name="τ join")
+            net.add_arc(entry, split)
+            net.add_arc(join, exit_)
+            for child in node.children:
+                child_entry, child_exit = net.add_place(), net.add_place()
+                net.add_arc(split, child_entry)
+                net.add_arc(child_exit, join)
+                build(child, child_entry, child_exit)
+        elif node.operator is Operator.LOOP:
+            loop_start, loop_end = net.add_place(), net.add_place()
+            enter = net.add_transition(None, name="τ enter")
+            leave = net.add_transition(None, name="τ exit")
+            net.add_arc(entry, enter)
+            net.add_arc(enter, loop_start)
+            net.add_arc(loop_end, leave)
+            net.add_arc(leave, exit_)
+            build(node.children[0], loop_start, loop_end)
+            for redo in node.children[1:]:
+                build(redo, loop_end, loop_start)
+
+    build(tree, source, sink)
+    net.initial_marking = Marking({source.id: 1})
+    net.final_marking = Marking({sink.id: 1})
+    reduce_silent_transitions(net)
+    net.info["algorithm"] = "Process tree"
+    return net
+
+
+def reduce_silent_transitions(net: PetriNet) -> None:
+    """Remove τ transitions that only connect two places in series.
+
+    Rule (fusion of series places): if τ has exactly one input place ``p`` and
+    one output place ``q``, ``p``'s only consumer is τ, and ``q``'s only
+    producer is τ, then firing τ is the *only* thing a token in p can do and
+    the *only* way into q -- so p and q can be merged and τ deleted without
+    changing the visible behaviour.  The source and sink are never merged
+    away, so the result is still a WF-net with the same markings.
+    """
+    changed = True
+    while changed:
+        changed = False
+        for transition in list(net.transitions.values()):
+            if not transition.silent:
+                continue
+            inputs, outputs = net.preset(transition.id), net.postset(transition.id)
+            if len(inputs) != 1 or len(outputs) != 1:
+                continue
+            (p,), (q,) = inputs, outputs
+            if p == q or net.postset(p) != {transition.id} or net.preset(q) != {transition.id}:
+                continue
+            if any(a.weight != 1 for a in net.arcs
+                   if transition.id in (a.source, a.target)):
+                continue
+            # Keep source/sink ids stable: merge the other place into them.
+            keep, drop = (q, p) if p not in ("source", "sink") else (p, q)
+            if drop in ("source", "sink"):
+                continue
+            net.remove_transition(transition.id)
+            for arc in net.arcs:
+                if arc.source == drop:
+                    arc.source = keep
+                if arc.target == drop:
+                    arc.target = keep
+            net.places.pop(drop)
+            net._cache = None
+            changed = True
+            break