openprocess 0.7.0__py3-none-any.whl

openprocess/mining/filtering.py

@@ -0,0 +1,237 @@
+"""Filtering event logs: keep the part of the log you want to look at.
+
+Real logs are messy: rare variants, noise activities, cases cut off by the
+extraction window.  Filtering is therefore the usual first step before
+discovery, as in ProM ("Filter Log using Simple Heuristics") and Disco.  Every
+filter here returns a **new** log and never changes the original, so you can
+always compare the filtered log with the one it came from.
+
+The filters, in the order :func:`apply_filters` applies them:
+
+1. **Time frame** -- keep cases *contained in*, *started in*, or
+   *intersecting* a period.  Cases without timestamps cannot be placed in
+   time and are dropped.
+2. **Start and end activities** -- keep cases that start (end) with one of
+   the chosen activities, e.g. to drop cases cut off by the extraction.
+3. **Activities** -- three modes, as in Disco:
+
+   * *keep events*: remove every event of the other activities (a projection;
+     cases keep their other events);
+   * *mandatory*: keep cases that contain at least one of the activities;
+   * *forbidden*: keep cases that contain none of them.
+
+4. **Case length** -- keep cases with between ``min`` and ``max`` events.
+5. **Variants** -- keep the most frequent variants, either the top ``k`` or
+   as many as needed to cover a percentage of the cases.
+
+Activities, variants and lengths are seen through the log's *classifier*
+(see :mod:`.log`), so they match what the rest of the app shows.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from .log import KEY_NAME, Classifier, EventLog, Trace
+
+TIME_MODES = ("contained", "started", "intersecting")
+ACTIVITY_MODES = ("keep events", "mandatory", "forbidden")
+
+
+@dataclass
+class FilterSettings:
+    """Which filters to apply.  ``None`` (or empty) means "do not filter on this"."""
+
+    #: ``(from, to, mode)`` with ``mode`` in :data:`TIME_MODES`.
+    time_frame: tuple[datetime, datetime, str] | None = None
+    start_activities: set[str] | None = None
+    end_activities: set[str] | None = None
+    #: ``(activities, mode)`` with ``mode`` in :data:`ACTIVITY_MODES`.
+    activities: tuple[set[str], str] | None = None
+    #: ``(minimum, maximum)`` number of events (after the activity filter).
+    case_length: tuple[int, int] | None = None
+    #: Keep the variants covering this percentage of the cases (0-100].
+    variant_coverage: float | None = None
+    #: Or: keep the ``k`` most frequent variants.
+    top_variants: int | None = None
+
+    def describe(self) -> list[str]:
+        """One line per active filter, for the record kept in the new log."""
+        lines: list[str] = []
+        if self.time_frame is not None:
+            start, end, mode = self.time_frame
+            lines.append(f"cases {mode} {start:%Y-%m-%d %H:%M} – {end:%Y-%m-%d %H:%M}")
+        if self.start_activities is not None:
+            lines.append("start with " + ", ".join(sorted(self.start_activities)))
+        if self.end_activities is not None:
+            lines.append("end with " + ", ".join(sorted(self.end_activities)))
+        if self.activities is not None:
+            names, mode = self.activities
+            lines.append(f"activities ({mode}): " + ", ".join(sorted(names)))
+        if self.case_length is not None:
+            lines.append(f"{self.case_length[0]} to {self.case_length[1]} events per case")
+        if self.variant_coverage is not None:
+            lines.append(f"most frequent variants covering {self.variant_coverage:g}% of cases")
+        if self.top_variants is not None:
+            lines.append(f"the {self.top_variants} most frequent variants")
+        return lines
+
+
+# ---------------------------------------------------------------------------
+# Single filters (each returns a new log)
+# ---------------------------------------------------------------------------
+def _derived(log: EventLog, traces: list[Trace]) -> EventLog:
+    result = log.filtered([])
+    result.traces = traces
+    return result
+
+
+def _span(trace: Trace) -> tuple[datetime, datetime] | None:
+    stamps = [event.timestamp for event in trace if event.timestamp is not None]
+    return (min(stamps), max(stamps)) if stamps else None
+
+
+def filter_time_frame(log: EventLog, start: datetime, end: datetime,
+                      mode: str = "contained") -> EventLog:
+    """Cases *contained* in, *started* in, or *intersecting* ``[start, end]``."""
+    if mode not in TIME_MODES:
+        raise ValueError(f"mode must be one of {TIME_MODES}")
+    kept = []
+    for trace in log:
+        span = _span(trace)
+        if span is None:
+            continue
+        first, last = span
+        if (mode == "contained" and start <= first and last <= end) or \
+                (mode == "started" and start <= first <= end) or \
+                (mode == "intersecting" and first <= end and last >= start):
+            kept.append(trace)
+    return _derived(log, kept)
+
+
+def filter_start_activities(log: EventLog, allowed: set[str],
+                            classifier: Classifier | None = None) -> EventLog:
+    """Cases whose first activity is one of ``allowed``."""
+    kept = [trace for trace, sequence in zip(log, log.sequences(classifier))
+            if sequence and sequence[0] in allowed]
+    return _derived(log, kept)
+
+
+def filter_end_activities(log: EventLog, allowed: set[str],
+                          classifier: Classifier | None = None) -> EventLog:
+    """Cases whose last activity is one of ``allowed``."""
+    kept = [trace for trace, sequence in zip(log, log.sequences(classifier))
+            if sequence and sequence[-1] in allowed]
+    return _derived(log, kept)
+
+
+def filter_activities(log: EventLog, activities: set[str], mode: str = "keep events",
+                      classifier: Classifier | None = None) -> EventLog:
+    """Project onto ``activities``, or keep cases that must (not) contain them.
+
+    *keep events* removes the events of every other activity -- including
+    events the classifier skips (a *start* event of a kept activity stays, so
+    the dotted chart still shows it).  Cases left without events are dropped.
+    """
+    if mode not in ACTIVITY_MODES:
+        raise ValueError(f"mode must be one of {ACTIVITY_MODES}")
+    classifier = classifier or log.default_classifier()
+    if mode == "keep events":
+        kept = []
+        for trace in log:
+            events = [event for event in trace if classifier.label(event) in activities]
+            if any(classifier.accepts(event) for event in events):
+                kept.append(Trace(dict(trace.attributes), events))
+        return _derived(log, kept)
+    kept = []
+    for trace, sequence in zip(log, log.sequences(classifier)):
+        contains = any(activity in activities for activity in sequence)
+        if contains == (mode == "mandatory"):
+            kept.append(trace)
+    return _derived(log, kept)
+
+
+def filter_case_length(log: EventLog, minimum: int, maximum: int,
+                       classifier: Classifier | None = None) -> EventLog:
+    """Cases with between ``minimum`` and ``maximum`` events (inclusive)."""
+    kept = [trace for trace, sequence in zip(log, log.sequences(classifier))
+            if minimum <= len(sequence) <= maximum]
+    return _derived(log, kept)
+
+
+def top_variants(log: EventLog, classifier: Classifier | None = None, *,
+                 coverage: float | None = None, count: int | None = None
+                 ) -> list[tuple[tuple[str, ...], int]]:
+    """The most frequent variants: the top ``count``, or just enough of them
+    to cover ``coverage`` percent of the cases (always at least one).
+
+    Variants with the same frequency are taken in the order they first occur
+    in the log, so the choice is deterministic.  (Keeping every tied variant
+    instead would make the filter useless on the many real logs where most
+    cases have a variant of their own.)
+    """
+    counts = Counter(log.sequences(classifier))       # insertion order = first occurrence
+    ranked = sorted(counts.items(), key=lambda item: -item[1])     # stable sort
+    if count is not None:
+        return ranked[:max(count, 0)]
+    if coverage is None:
+        return ranked
+    needed = sum(counts.values()) * min(max(coverage, 0), 100) / 100
+    chosen, covered = [], 0
+    for variant, frequency in ranked:
+        if chosen and covered >= needed:
+            break
+        chosen.append((variant, frequency))
+        covered += frequency
+    return chosen
+
+
+def filter_variants(log: EventLog, classifier: Classifier | None = None, *,
+                    coverage: float | None = None, count: int | None = None) -> EventLog:
+    """Keep the cases of the most frequent variants (see :func:`top_variants`)."""
+    keep = {variant for variant, _ in top_variants(log, classifier, coverage=coverage,
+                                                   count=count)}
+    kept = [trace for trace, sequence in zip(log, log.sequences(classifier))
+            if sequence in keep]
+    return _derived(log, kept)
+
+
+# ---------------------------------------------------------------------------
+# All together
+# ---------------------------------------------------------------------------
+def apply_filters(log: EventLog, settings: FilterSettings,
+                  classifier: Classifier | None = None, name: str | None = None) -> EventLog:
+    """Apply every active filter of ``settings``, in the order of the module
+    docstring, and name the result.  The new log records what was done in
+    its ``openprocess:filter`` attribute."""
+    classifier = classifier or log.default_classifier()
+    result = log
+    if settings.time_frame is not None:
+        result = filter_time_frame(result, *settings.time_frame)
+    if settings.start_activities is not None:
+        result = filter_start_activities(result, settings.start_activities, classifier)
+    if settings.end_activities is not None:
+        result = filter_end_activities(result, settings.end_activities, classifier)
+    if settings.activities is not None:
+        result = filter_activities(result, *settings.activities, classifier=classifier)
+    if settings.case_length is not None:
+        result = filter_case_length(result, *settings.case_length, classifier=classifier)
+    if settings.variant_coverage is not None or settings.top_variants is not None:
+        result = filter_variants(result, classifier, coverage=settings.variant_coverage,
+                                 count=settings.top_variants)
+    if result is log:
+        result = _derived(log, list(log.traces))
+    result.attributes = dict(log.attributes)
+    result.attributes[KEY_NAME] = name or f"{log.name} (filtered)"
+    result.attributes["openprocess:filter"] = "; ".join(settings.describe()) or "none"
+    result.source_path = None
+    return result
+
+
+__all__ = [
+    "ACTIVITY_MODES", "FilterSettings", "TIME_MODES", "apply_filters",
+    "filter_activities", "filter_case_length", "filter_end_activities",
+    "filter_start_activities", "filter_time_frame", "filter_variants", "top_variants",
+]

openprocess/mining/footprint.py

@@ -0,0 +1,183 @@
+"""Ordering relations and footprint matrices (van der Aalst, ch. 6.2 and 8.4).
+
+From the directly-follows relation ``>_L`` four *log-based ordering
+relations* are derived, for every pair of activities a, b:
+
+====================  ===========================================  =========
+relation              definition                                   symbol
+====================  ===========================================  =========
+causality             ``a > b`` and **not** ``b > a``              ``→``
+inverse causality     ``b > a`` and **not** ``a > b``              ``←``
+parallel              ``a > b`` **and** ``b > a``                  ``‖``
+choice / unrelated    **neither** ``a > b`` nor ``b > a``          ``#``
+====================  ===========================================  =========
+
+Exactly one of the four holds for each ordered pair, so the relations can be
+tabulated as the **footprint matrix**.  Note the diagonal: ``a # a`` unless
+``a`` directly follows itself (a length-one loop), in which case ``a ‖ a``.
+
+Frequencies play no role: a pair that directly follows once counts the same
+as one that follows a thousand times.  That is exactly why the α-algorithm is
+sensitive to noise.
+
+Conformance via footprints (ch. 8.4)
+------------------------------------
+A model has a footprint too (computed from its behaviour).  Comparing the log
+footprint with the model footprint cell by cell gives a simple conformance
+measure::
+
+    fitness_footprint = 1 - (number of differing cells) / (total cells)
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+
+from .dfg import DFG, dfg_from_simple_log
+from .log import SimpleLog
+from .petrinet import PetriNet
+
+CAUSAL = "→"
+INVERSE = "←"
+PARALLEL = "‖"
+CHOICE = "#"
+
+
+@dataclass
+class Footprint:
+    activities: list[str]
+    directly_follows: set[tuple[str, str]]
+    start: set[str]
+    end: set[str]
+
+    def relation(self, a: str, b: str) -> str:
+        forward = (a, b) in self.directly_follows
+        backward = (b, a) in self.directly_follows
+        if forward and backward:
+            return PARALLEL
+        if forward:
+            return CAUSAL
+        if backward:
+            return INVERSE
+        return CHOICE
+
+    # Convenience predicates with the textbook names -----------------------
+    def causal(self, a: str, b: str) -> bool:
+        return self.relation(a, b) == CAUSAL
+
+    def parallel(self, a: str, b: str) -> bool:
+        return self.relation(a, b) == PARALLEL
+
+    def choice(self, a: str, b: str) -> bool:
+        return self.relation(a, b) == CHOICE
+
+    def matrix(self) -> list[list[str]]:
+        return [[self.relation(a, b) for b in self.activities] for a in self.activities]
+
+    def as_text(self) -> str:
+        width = max([len(a) for a in self.activities] + [1])
+        header = " " * (width + 1) + " ".join(a.rjust(width) for a in self.activities)
+        rows = [header]
+        for a, row in zip(self.activities, self.matrix()):
+            rows.append(a.rjust(width) + " " + " ".join(cell.rjust(width) for cell in row))
+        return "\n".join(rows)
+
+
+def footprint_from_dfg(dfg: DFG) -> Footprint:
+    return Footprint(sorted(dfg.activities), set(dfg.edges), set(dfg.start), set(dfg.end))
+
+
+def footprint_of_log(log: SimpleLog) -> Footprint:
+    return footprint_from_dfg(dfg_from_simple_log(log))
+
+
+def footprint_of_net(net: PetriNet, max_states: int = 50_000) -> Footprint:
+    """The footprint of a model's behaviour.
+
+    ``a > b`` holds in the model iff some reachable marking allows ``a`` and
+    then ``b`` with only silent transitions in between.  Computed from the
+    reachability graph, so the net must be bounded.
+    """
+    from .analysis import reachability_graph
+
+    graph = reachability_graph(net, max_states=max_states)
+    if graph.has_omega or graph.truncated:
+        raise ValueError("The model's state space is unbounded or too large to "
+                         "compute its footprint.")
+
+    def visible_next(state: int) -> set[str]:
+        """Labels that can occur next from ``state``, skipping silent steps."""
+        seen, result = {state}, set()
+        queue = deque([state])
+        while queue:
+            current = queue.popleft()
+            for transition, target in graph.successors(current):
+                label = net.transitions[transition].label
+                if label is None:
+                    if target not in seen:
+                        seen.add(target)
+                        queue.append(target)
+                else:
+                    result.add(label)
+        return result
+
+    follows: set[tuple[str, str]] = set()
+    for source, transition, target in graph.edges:
+        label = net.transitions[transition].label
+        if label is None:
+            continue
+        for successor in visible_next(target):
+            follows.add((label, successor))
+    start = visible_next(0)
+    final_states = [i for i, m in enumerate(graph.states) if m == net.final_marking]
+    end: set[str] = set()
+    for source, transition, target in graph.edges:
+        label = net.transitions[transition].label
+        if label is not None and _silently_reaches(graph, net, target, set(final_states)):
+            end.add(label)
+    return Footprint(sorted(net.labels()), follows, start, end)
+
+
+def _silently_reaches(graph, net, state: int, targets: set[int]) -> bool:
+    seen = {state}
+    queue = deque([state])
+    while queue:
+        current = queue.popleft()
+        if current in targets:
+            return True
+        for transition, target in graph.successors(current):
+            if net.transitions[transition].label is None and target not in seen:
+                seen.add(target)
+                queue.append(target)
+    return False
+
+
+@dataclass
+class FootprintComparison:
+    activities: list[str]
+    log_matrix: list[list[str]]
+    model_matrix: list[list[str]]
+
+    @property
+    def differences(self) -> list[tuple[str, str, str, str]]:
+        """(a, b, log relation, model relation) for every differing cell."""
+        result = []
+        for i, a in enumerate(self.activities):
+            for j, b in enumerate(self.activities):
+                if self.log_matrix[i][j] != self.model_matrix[i][j]:
+                    result.append((a, b, self.log_matrix[i][j], self.model_matrix[i][j]))
+        return result
+
+    @property
+    def fitness(self) -> float:
+        cells = len(self.activities) ** 2
+        return 1.0 if cells == 0 else 1 - len(self.differences) / cells
+
+
+def compare_footprints(log_fp: Footprint, model_fp: Footprint) -> FootprintComparison:
+    """Cell-by-cell comparison over the union of both alphabets."""
+    activities = sorted(set(log_fp.activities) | set(model_fp.activities))
+    log_matrix = [[log_fp.relation(a, b) for b in activities] for a in activities]
+    model_matrix = [[model_fp.relation(a, b) for b in activities] for a in activities]
+    return FootprintComparison(activities, log_matrix, model_matrix)

openprocess/mining/invariants.py

@@ -0,0 +1,191 @@
+"""The incidence matrix, place invariants and transition invariants.
+
+Linear algebra instead of state spaces
+--------------------------------------
+Everything in :mod:`.analysis` explores markings one by one.  Invariants
+answer questions from the *structure* alone, with a little linear algebra,
+so they work even when the state space is huge or infinite.
+
+**Incidence matrix.**  ``C`` has a row per place and a column per transition;
+``C(p, t) = W(t, p) − W(p, t)`` is what firing ``t`` does to ``p`` (the tokens
+it puts in minus the tokens it takes out).  Firing a sequence ``σ`` whose
+Parikh vector ``σ⃗`` counts how often each transition fires gives the
+**marking equation**::
+
+    M  --σ-->  M'    implies    M' = M + C · σ⃗
+
+**Place invariant (P-invariant).**  A weighting ``y`` of the places with
+``yᵀ · C = 0``.  Multiplying the marking equation by ``yᵀ`` gives
+``y · M' = y · M``: the weighted token count is the same in *every* reachable
+marking.  In a WF-net, ``i + c1 + c2 + o`` being invariant says "exactly one
+token moves through these places".
+
+**Transition invariant (T-invariant).**  A firing count ``x`` with
+``C · x = 0``: firing every transition as often as ``x`` says (in any
+enabled order) leads back to the marking you started from.  A cycle of the
+net's behaviour.
+
+We compute the **minimal semi-positive** invariants (no negative weights, not
+all zero, and no other invariant uses a strict subset of their places or
+transitions).  Every semi-positive invariant is a non-negative combination
+of these, so they are *the* invariants to show.  The method is Farkas'
+algorithm (Martínez & Silva, 1982): start from ``[C | I]`` and eliminate one
+column of ``C`` at a time by adding pairs of rows with opposite signs.
+
+What they tell you
+------------------
+* Every place in some semi-positive P-invariant (**covered by P-invariants**)
+  ⇒ the net is *structurally bounded*: bounded from any initial marking.
+* A net that is live and bounded is covered by T-invariants, so a transition
+  in no T-invariant means "not both live and bounded".  For a WF-net, apply
+  that to the short-circuited net N̄: by the soundness theorem, a sound
+  WF-net's N̄ is covered by T-invariants.
+
+The number of minimal invariants can grow exponentially with the size of the
+net.  :func:`invariants` stops at ``limit`` intermediate rows and says so.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from math import gcd
+
+from .petrinet import Marking, PetriNet
+
+
+class TooManyInvariants(Exception):
+    """Farkas' algorithm needed more than the allowed number of rows."""
+
+
+def incidence_matrix(net: PetriNet) -> tuple[list[str], list[str], list[list[int]]]:
+    """``(places, transitions, C)`` with ``C[i][j] = W(t_j, p_i) − W(p_i, t_j)``."""
+    places = list(net.places)
+    transitions = list(net.transitions)
+    row = {p: i for i, p in enumerate(places)}
+    column = {t: j for j, t in enumerate(transitions)}
+    matrix = [[0] * len(transitions) for _ in places]
+    for arc in net.arcs:
+        if arc.source in row and arc.target in column:          # p -> t: consumed
+            matrix[row[arc.source]][column[arc.target]] -= arc.weight
+        elif arc.source in column and arc.target in row:        # t -> p: produced
+            matrix[row[arc.target]][column[arc.source]] += arc.weight
+    return places, transitions, matrix
+
+
+def _normalise(vector: list[int]) -> list[int]:
+    divisor = 0
+    for value in vector:
+        divisor = gcd(divisor, value)
+    return [value // divisor for value in vector] if divisor > 1 else vector
+
+
+def _support(vector: list[int]) -> frozenset[int]:
+    return frozenset(i for i, value in enumerate(vector) if value)
+
+
+def _minimal(rows: list[tuple[list[int], list[int]]]) -> list[tuple[list[int], list[int]]]:
+    """Drop duplicate rows and rows whose support strictly contains another's."""
+    unique: dict[tuple[int, ...], tuple[list[int], list[int]]] = {}
+    for rest, generator in rows:
+        unique.setdefault(tuple(rest) + tuple(generator), (rest, generator))
+    rows = list(unique.values())
+    supports = [_support(generator) for _, generator in rows]
+    return [row for row, support in zip(rows, supports)
+            if not any(other < support for other in supports)]
+
+
+def semi_positive_invariants(matrix: list[list[int]], limit: int = 5_000) -> list[list[int]]:
+    """Minimal semi-positive solutions ``y ≥ 0, y ≠ 0`` of ``yᵀ · matrix = 0``.
+
+    ``matrix`` has one row per variable.  Farkas' algorithm: rows are pairs
+    (what is left of the matrix row, the combination of variables it stands
+    for).  Column by column, rows with opposite signs in that column are
+    combined so that it cancels, and rows that do not cancel are dropped.
+    """
+    count = len(matrix)
+    columns = len(matrix[0]) if count else 0
+    rows = [(list(matrix[i]), [1 if j == i else 0 for j in range(count)]) for i in range(count)]
+    for column in range(columns):
+        keep = [row for row in rows if row[0][column] == 0]
+        positive = [row for row in rows if row[0][column] > 0]
+        negative = [row for row in rows if row[0][column] < 0]
+        for up_rest, up_generator in positive:
+            for down_rest, down_generator in negative:
+                # a·up + b·down cancels the column, with a, b > 0.
+                a, b = -down_rest[column], up_rest[column]
+                combined = _normalise([a * x + b * y for x, y in zip(
+                    up_rest + up_generator, down_rest + down_generator)])
+                keep.append((combined[:columns], combined[columns:]))
+        rows = _minimal(keep)
+        if len(rows) > limit:
+            raise TooManyInvariants(f"more than {limit} candidate invariants")
+    invariants = [_normalise(generator) for _, generator in _minimal(rows) if any(generator)]
+    return sorted(invariants, key=lambda v: (sum(1 for x in v if x), [-x for x in v]))
+
+
+@dataclass
+class Invariants:
+    """The incidence matrix and the minimal semi-positive invariants of a net."""
+
+    net: PetriNet
+    places: list[str]
+    transitions: list[str]
+    #: ``incidence[i][j]``: the effect of transitions[j] on places[i].
+    incidence: list[list[int]]
+    #: Each P-invariant as ``{place id: weight}`` (weights > 0 only).
+    p_invariants: list[dict[str, int]] = field(default_factory=list)
+    #: Each T-invariant as ``{transition id: count}`` (counts > 0 only).
+    t_invariants: list[dict[str, int]] = field(default_factory=list)
+    #: Set when there were too many to compute: the lists are then empty.
+    p_truncated: bool = False
+    t_truncated: bool = False
+
+    def uncovered_places(self) -> list[str]:
+        covered = {p for invariant in self.p_invariants for p in invariant}
+        return [p for p in self.places if p not in covered]
+
+    def uncovered_transitions(self) -> list[str]:
+        covered = {t for invariant in self.t_invariants for t in invariant}
+        return [t for t in self.transitions if t not in covered]
+
+    @property
+    def covered_by_p_invariants(self) -> bool | None:
+        """Every place in some P-invariant (⇒ structurally bounded)."""
+        return None if self.p_truncated else not self.uncovered_places()
+
+    @property
+    def covered_by_t_invariants(self) -> bool | None:
+        return None if self.t_truncated else not self.uncovered_transitions()
+
+    def token_sum(self, invariant: dict[str, int], marking: Marking | None = None) -> int:
+        """``y · M``: the weighted token count the invariant keeps constant."""
+        marking = self.net.initial_marking if marking is None else marking
+        return sum(weight * marking[place] for place, weight in invariant.items())
+
+    def describe(self, invariant: dict[str, int], with_value: bool = False) -> str:
+        """``2·p1 + p2`` (P-invariant) or ``a + b + t*`` (T-invariant), by name."""
+        terms = [(f"{weight}·" if weight != 1 else "") + self.net.node_name(node)
+                 for node, weight in invariant.items()]
+        text = " + ".join(terms)
+        if with_value:
+            text += f" = {self.token_sum(invariant)}"
+        return text
+
+
+def invariants(net: PetriNet, limit: int = 5_000) -> Invariants:
+    """Incidence matrix plus minimal semi-positive P- and T-invariants."""
+    places, transitions, matrix = incidence_matrix(net)
+    result = Invariants(net, places, transitions, matrix)
+    try:
+        for vector in semi_positive_invariants(matrix, limit):
+            result.p_invariants.append({p: w for p, w in zip(places, vector) if w})
+    except TooManyInvariants:
+        result.p_truncated = True
+    transposed = [list(column) for column in zip(*matrix)] if places else \
+        [[] for _ in transitions]
+    try:
+        for vector in semi_positive_invariants(transposed, limit):
+            result.t_invariants.append({t: w for t, w in zip(transitions, vector) if w})
+    except TooManyInvariants:
+        result.t_truncated = True
+    return result