openprocess 0.10.6

Process mining, Petri nets and workflows in one open app.
Every algorithm is there to read, every result can be reproduced, every step can be taught.
Pure Python and Qt. No Java, no Wine, no separate simulator to install.

⬇ Download for macOS, Windows or Linux · no Python needed · or pip install openprocess[app] · install guide

OpenProcess Studio is the workbench; OpenProcess Learn is the teaching mode built on it. Together they bring under one roof what usually takes several tools (and, until version 0.7, went by the name CPNpy):

Contents

• Install
• Quick start
• Folders: one per week
• Petri nets and WF-nets
• Process mining
• Learn
• Coloured Petri nets
• Working on the canvas
• Keyboard shortcuts
• Files
• For developers
• Workflows
• Workflows from Python
• Limitations and roadmap

Install

OpenProcess runs on macOS, Windows and Linux. Download the app, or run it from source if you want to change the code.

Download the app

No Python needed. Take the file for your system from the latest release:

The apps are not signed with a paid developer certificate, so the system asks once, the first time you start one:

• macOS says Apple could not check it. Click Done, then open System Settings ▸ Privacy & Security and click Open Anyway next to OpenProcess. (Or in Terminal: xattr -dr com.apple.quarantine /Applications/OpenProcess.app.)
• Windows shows Windows protected your PC. Click More info, then Run anyway.

Later versions install themselves: the app says when one is out, or ask with Help ▸ Check for Updates….

With pip

For a script, a notebook, a box of your own, or CI, OpenProcess is a normal Python package with no required dependencies:

pip install openprocess            # the engine: process mining, Petri nets, workflows, Learn
pip install "openprocess[app]"     # also the desktop app: then `openprocess studio`
pip install "openprocess[app,science]"   # and the pandas, SciPy and matplotlib boxes

Code written for CPNpy keeps working: import cpnpy is openprocess under its old name (with a one-line warning), so existing boxes and exercise packs run unchanged.

From source

You need Python 3.10 or newer, with Qt through PySide6. The easiest way to set it up is a conda environment called openprocess, defined in environment.yml.

1. Get conda (once)

Install Miniforge, a small conda that uses the conda-forge packages.

2. Get the code and create the environment

The same commands on every system (Terminal on macOS and Linux, Miniforge Prompt or PowerShell on Windows):

git clone https://github.com/s4mstruthers/openprocess.git
cd OpenProcess
conda env create -f environment.yml       # Python 3.12, PySide6, pytest, OpenProcess itself
conda activate openprocess

No git? Use Code ▸ Download ZIP on GitHub, unzip it and cd into the folder.

3. Start the app

openprocess-studio

python -m openprocess.gui.studio does the same. After pulling changes that touch environment.yml or pyproject.toml, run conda env update -f environment.yml --prune.

pip install -e ".[app,dev]"
openprocess-studio

Linux: Qt needs a few system libraries that desktop installs usually have. If the app does not start and the error mentions the "xcb" platform plugin or libEGL.so.1, install them, e.g. on Ubuntu/Debian: sudo apt install libxcb-cursor0 libxkbcommon-x11-0 libegl1.

Keyboard shortcuts follow the system: ⌘ on a Mac, Ctrl on Windows and Linux (see Keyboard shortcuts).

Quick start

Work in a folder (recommended): File ▸ Open Folder… (⌥⌘O / Ctrl+Alt+O) and pick a folder such as Week 2, or drop the folder onto the window. See Folders.

Check whether a WF-net is sound

1. File ▸ New Petri Net (⌘N / Ctrl+N).
2. Pick Place and click on the canvas. Type a name and press Return (or click elsewhere to keep the suggested name), and the tool switches back to Select on its own. Do the same with Transition.
3. Pick Arc and drag from a place to a transition, or the other way round. Drag again from the same node to add more arcs.
4. Open the Analysis tab on the right. It shows whether the net is a WF-net, whether it is sound, its behavioural properties and its footprint. Everything updates after each edit.
5. If it isn't sound, press Show ▶ next to a finding. The net switches to Step through and fires the counterexample, so you can see the problem marking.

To try this without drawing, use File ▸ Open Example Petri Net ▸ Order handling (unsound — try Analysis).

Mine a log

1. ✎ Log from notation… (⌘L / Ctrl+L) and type [<a,b,c,d>^3, <a,c,b,d>^2, <a,e,d>] (pasting [⟨a,b,c,d⟩³, …] from the book works too), or open a .xes / .csv file.
2. Look through the tabs: Overview, Variants, Cases, Dotted chart, Process map, Footprint. Filter… keeps part of the log as a new log.
3. On the Discover tab, pick an algorithm and press Discover in Mine →: an analysis opens with the log and the miner connected and run. Click the miner for its result, How it was derived, and the Code it ran.
4. + Add box ▸ Check fit on that canvas, wired to the miner and the log, scores fitness, precision and more, every step shown.

Simulate a coloured net

File ▸ Open Coloured Petri Net… (⇧⌘O / Ctrl+Shift+O), then Step through or Simulate.

Folders: one per week

Keep each week's material in a folder (the logs from the course, the nets you draw) and open it: File ▸ Open Folder… (⌥⌘O / Ctrl+Alt+O), or drag the folder onto the window. The sidebar and the folder always match: what you see in OpenProcess is what is in Finder (or Explorer), and the other way round.

Three spaces, one folder. The switcher at the top of the window picks Mine (event logs and analyses), Model (Petri nets and coloured nets) or Learn (exercises). Each has its own sidebar, so mining and modelling never share a list; a document opens in its space, and the folder remembers which space you were in.

In the sidebar

• Mine lists the folder's analyses, and its logs folded under them. Model lists its models. Files that are not open yet are lighter: click one to open it. Closing a file (✕ or ⌘W) puts it back in that state; it stays in the folder.
• Flat lists, the same in both spaces. The folder's own files first, then each subfolder's under a caption naming it ("Week 5 / Part 1"). Nothing to unfold except LOGS. An empty folder shows in both spaces until it has files.
• Organise from the app: right-click for New Folder…, Rename…, Show in Finder and Move to Bin (recoverable from the Bin; never a hard delete). Drag files onto a subfolder to move them on disk. An open file that is moved or renamed stays open, unsaved edits included. Drag a file out of the sidebar to Finder to copy it there.
• Subfolders are listed up to three levels deep and 500 files (a row says so when there are more), with hidden files and tools' folders (__pycache__, .git, …) skipped, as Finder does.

From the app to the folder

• New nets are files from the start: New Petri Net creates Untitled 1.pnml (a coloured net, Untitled 1.cpn) in the folder. Rename the net (double-click its name) and the file is renamed with it.
• Edits are saved as you go (autosave): a second after you stop editing, and when you switch to another file or quit. There is no "edited" dot, and undo still works. Turn it off with File ▸ Autosave. File ▸ Revert to Saved… goes back to the file as it was when you opened it. A .cpn model made in CPN Tools is not autosaved (OpenProcess would rewrite it in its own writer) until you save it once yourself with ⌘S.
• Logs you make are files too: a log typed in notation is saved as <name>.log.txt (still in notation), a filtered log as <log> (filtered).xes next to the log it came from, and a CPN simulation's log as <model> simulation.xes.
• A discovered model stays in the UNSAVED group until you press Keep, so trying algorithms does not fill the folder. Keep saves it as PNML next to its log.
• Saving writes a temporary file and then swaps it in, so a crash never leaves a half-written file.

From the folder to the app

• Files added, renamed or deleted in Finder (or by any other app, a git pull, iCloud) appear and disappear by themselves, in about half a second on macOS.
• An open file changed on disk (a .xes exported again from ProM, a .pnml edited in WoPeD) is reloaded by itself. If it also has edits in OpenProcess that are not saved yet, a bar above the page asks: Reload (lose my edits) or Keep Mine. OpenProcess's own saves are recognised and never reload.
• An open file moved or renamed in Finder, within the folder, stays open and follows the file to its new place, unsaved edits included.
• An open file deleted, or moved out of the folder, stays open, shown in italics with a missing bar: Save As… to keep it. It is not quietly recreated.
• If a net cannot be saved automatically (a read-only folder, a full disk), a bar says so once and the net is saved with ⌘S again, with its "edited" dot, until saving works.
• A file still being copied in is not read half-way.
• With iCloud Drive's Optimise Mac Storage, files that are only in iCloud are listed with a ☁: click one to download and open it.

Files from elsewhere

Opening a file from outside the folder (File ▸ Open…, Open Recent, or dropping it on the window) asks whether to copy it into the folder (the default: the original stays where it is), move it in, or open it from where it is. Tick Always do this to stop asking for that folder, or set the default in Settings. A file with the same name already in the folder is never overwritten silently: Keep Both (Wilma 50 2.xes) or Replace (the old one goes to the Bin). Dropping a file onto a subfolder in the sidebar puts it there. Files opened where they are appear under OTHER FILES.

Coming back

• What you had open comes back the next time you open the folder, and the app reopens the last folder at launch. This is kept in a small hidden file, .openprocess, in the folder, with paths relative to the folder, so it keeps working if you move or sync the folder. Delete it to start fresh.
• Switch with File ▸ Open Recent Folder, the buttons on the welcome page, or the ⋯ menu next to the folder's name, which also has Show in Finder, New Folder… and Close Folder.

Opening a folder closes the files that are not in it (it asks first about unsaved changes). Without a folder, the app works with loose files as before: nothing is autosaved or created on disk until you save it, and the files you had open come back at launch (File ▸ Reopen Files at Launch turns that off).

A tip for the course: one folder per week inside your course folder, e.g. Process Mining/Week 2, with the week's logs and the nets you make.

Petri nets and WF-nets

Nets drawn as in the lectures and the book:

• Places are circles with black tokens inside, drawn as dots up to 5 and as a number above that.
• Transitions are boxes with their name inside. A silent (τ) transition is a black bar.
• Arc weights above 1 are written on the arc.
• Names go inside the places and transitions, which grow to fit them. Tick Names outside in the toolbar to put them underneath instead; you can then drag each name where you want it. Both are saved in the PNML file.

Select anything to edit it in the Element tab: a place's name and tokens, whether a transition is silent, an arc's weight and direction.

Analysis tab

Every property is defined mathematically in docs/definitions.md. In the app, hover over a property (the ones marked ⓘ) to see its definition filled in for your net — with your place names, and when it fails, the marking and firing sequence that break it. Click it to keep the definition open and follow links to the definitions it builds on; Help ▸ Definitions lists them all.

• WF-net: exactly one source place i, one sink place o, and every node on a path between them.

• Soundness:

  • (i) option to complete;
  • (ii) proper completion;
  • (iii) no dead transitions.

  Every violation comes with a firing sequence as its counterexample, and Show ▶ plays it on the net.

• Short-circuited net N̄: the net plus a transition t* from o back to i. By the soundness theorem, the net is sound iff (N̄, [i]) is live and bounded; both are shown, with the transition that can't fire again and the marking where that happens. Safe and deadlock-free are shown too. Open the short-circuited net draws it.

• Structure: free-choice, well-structured (no PT- or TP-handles in N̄, with the two paths of a handle spelled out) and S-coverable, plus the start and end rule: a quick check for transitions that need i or o together with another place.

• Invariants: the P-invariants (weighted token counts that never change, e.g. start + c1 + c3 + end = 1) and the T-invariants (of N̄ for a WF-net), and whether they cover the net. Covered by P-invariants means bounded from any marking; a transition in no T-invariant of N̄ proves the WF-net unsound. Incidence matrix… shows the matrix they come from.

• Behavioural properties of the net as drawn: bounded, safe, deadlock-free, dead transitions, live, reversible. A WF-net always stops in [o], so that dead marking is marked as expected.

• Footprint: the → ← ‖ # matrix of the net's behaviour, to compare with a log's footprint (α-algorithm, footprint conformance).

• Reachability graph…, or a coverability graph with ω when the net is unbounded.

• Check against a log › (Analysis tab) builds an analysis in Mine with this net, a log you pick and Check fit, connected and run.

• Every analysis card has a { } code link that opens the function it is computed by, so nothing here is a black box.

The counterexample, replayed	The footprint of the net

Also on the Petri net page

• Step through / Simulate: the token game, fired by hand or at random. With Trace ticked, every fired transition shows its step numbers and the arcs the tokens used light up, the latest step strongest.
• Mine a simulated log ›: plays the net out many times, saves the traces as a log in the folder and opens Mine on a new analysis reading it.
• Check against a log › (Analysis tab): picks a log and opens Mine on a new analysis with this net, the log and Check fit, connected and run.
• Saving: nets are saved as PNML (ProM, WoPeD and PM4Py read it), or as .cpn. Save As names the net after its file. With a folder open, a new net is Untitled 1.pnml in the folder from the start and is saved as you edit (Folders); without one, it is called Untitled 1 until you save it.
• Renaming: double-click the net's name in the sidebar, or its title above the canvas. The file is renamed with it, in the same folder (an existing file is never overwritten).
• Opening: a .pnml file opens in this editor. A net discovered in Mine has Open a copy in Model › to bring a copy here; the original result is never changed, and the copy's header links back to the analysis.

Process mining

Log overview	Dotted chart

• Logs:

  • XES, XES.GZ and CSV (you map the columns);
  • the course's notation, e.g. [<a,b,c,d>^3, <a,e,d>] (or ⟨a,b⟩³ as in the book);
  • XES, CSV and notation export.

• Edit… a log after opening it: as notation (a log you typed comes back exactly as you typed it, so you can change it), or case by case — add, delete, duplicate and reorder events and cases, edit activities, timestamps and resources, rename or remove an activity everywhere. The edit is saved to the log's file; XES and CSV logs keep their other attributes.

• Filter (as in ProM and Disco): keep cases in a time frame, cases that start or end with chosen activities, only the events of chosen activities (or the cases that do or do not contain them), cases of a certain length, and the most frequent variants. A preview shows what is left; the result opens as a new log.

• Explore: overview figures, variants, cases, a ProM-style dotted chart, a process map (directly-follows graph with frequency or performance), and the footprint matrix.

  • Dotted chart axes: actual time, time since case start, % of case duration, or logical order (in the log, or within the case).
  • Time unit (Auto, or seconds up to years) and a grid step you can type in.
  • Colour and shape by any attribute. The default palette can be changed per value: right-click a value in the legend and pick its colour.

• Discover hands the log to an analysis in Mine (Discover in Mine →), where the miner is a box with its result, its How and its Code:

  • α-algorithm, which shows its eight steps;
  • Inductive Miner (with a noise setting for IMf);
  • Heuristics Miner, as a Petri net: which forks are AND and which XOR is learned from the log (a causal net, whose bindings are listed). Like in ProM, such a net fits its log but is not always sound;
  • state-based regions, two-phase: Classical states turns the log into a transition system through a state function you choose (the prefix, postfix or both of each event; as a set, multiset or sequence; over the last k events or all of them), and Regions to net makes its minimal regions the places. The derivation shows the transition system, the regions, GER and minimal pre- and post-regions of every event, state separation and forward closure, and whether the net's reachability graph is isomorphic to the transition system.

  In Learn, an exercise's log page keeps the miners on the page, since the exercise is the context there.

• Transition systems (File ▸ New Transition System…, or a ts.txt file): type one as s0 -a-> s1, s0 -b-> s2 and get the same region analysis and synthesis. Is this a region? answers yes or no for any set of states (type it or click the states), and for no names the event and the two transitions that cross it differently.

• Models:

  • token game;
  • soundness and properties;
  • reachability graph;
  • PNML / PNG / SVG export.

• Conformance:

  • token-based replay and optimal alignments, both drawn on the model;
  • fitness, precision, generalisation and simplicity;
  • alignments per variant.

• Compare logs: key figures, activity and variant shares, and linked dotted charts, side by side.

• Compare nets (File ▸ Compare Nets…): do two nets allow the same complete traces? Silent steps are ignored and transitions matched by label, so layout and place names do not matter. You get the shortest traces that differ, both ways, each replayable in the token game. Exact for bounded nets; for unbounded ones, up to a trace length (and it says so).

Process map	Discovering a model

α-algorithm result	Conformance (alignments on the model)

Comparing two logs	Linked dotted charts of three boarding strategies

The app follows the system's light or dark appearance:

Learn

OpenProcess Learn is the teaching side of the app, built on top of it: exercise packs with answer boxes that the app checks. Click an exercise folder in the sidebar, Learn ▸ Open Exercise Pack…, or Learn ▸ Open Demo Exercises (it asks where to put a copy, since your answers are saved next to the exercises): the window switches to a view made for working through a pack without distractions, and Exit brings your folder back exactly as it was.

• The worksheet on the left is the question top to bottom, with an answer box wherever one is needed: yes/no, multiple choice, a set ({a, b}, sets of sets, or pairs like ({a}, {b,d})), a number, a short text, a footprint matrix, a firing sequence (which you can play in the net), a marking or a set of markings, the net as (P, T, F, m₀), an incidence matrix or a reachability graph, the Inductive Miner's cuts, sublogs and process tree, a replay table (p, c, m, r), an alignment, a ranking of models, a prediction of what an algorithm will give, free text, a net to draw in the editor beside it, or a workflow to build on the canvas beside it.
• Check says whether each answer is right — and when it is not, how far off it is (“2 of your items are right, 1 is missing”, the wrong cells of a matrix, which part of the tuple is off, the shortest traces where your net differs, which you can replay) without giving the answer away. Typed notations show how they are read as you type. Hint and Show answer are there when you want them.
• The materials on the right are what the exercise gives: the log, the transition system, the given net (to play, not change), your own net, and the Workflow tab. Results that would give answers away — soundness, the footprint, discovered models, regions… — stay hidden until you reveal them.
• Notes (✎ in the top bar) opens scratch paper under the worksheet for working things out, kept with the exercise.
• Points and exams. Every answer box is worth points (a partly right answer earns a part), and the overview shows the score so far. A pack can be an exam: a clock in the top bar, no hints or answers, nothing revealed, and the answers locked when the time is up. ⋯ ▸ Export Marks… writes the marks as CSV. A pack can also give every student a variant of its own (a log played out from a net with a seed made from their name).
• Your work is saved as you go, in the exercise's folder: my answers.json, my answer.pnml for a net, my workflow.cpnflow for a workflow and my notes.md.

Writing a pack (for a course or an exam) is plain Markdown: put an answer block wherever students should answer.

**b.** Give the start activities $T_I$.

```answer
type: set
compute: alpha.T_I
points: 2
hint: Which activities does a trace begin with?
```

compute: works the right answer out from the exercise's own log, net or transition system (α-algorithm steps, the Inductive Miner's cuts, soundness and its conditions, markings and matrices, replay, regions, fitness… and any box of the workflow library: box(alpha_miner).net.transitions), so most answers need not be written by hand. Learn ▸ Writing Exercise Packs (openprocess/learn/exercise-packs.md) lists every box type and computed answer. From a terminal, openprocess exercises check <pack> reports mistakes in a pack before you share it, openprocess exercises marks <pack> prints the marks, openprocess exercises computes lists every compute, and openprocess exercises import exam.txt <pack> (or Learn ▸ Make a Pack from an Exam…) turns a past exam's text into a skeleton pack, one exercise per question with an answer block per part, for you to finish. Exercises written for earlier versions still work: a sheet written in lettered parts (a., b., …) gets a box under each part, with that part of answer.md as its model answer.

The code is openprocess.learn (no Qt: the worksheet format, the notations, the computed answers and the checks) and openprocess.gui.learn (the window).

Coloured Petri nets

A reimplementation of the modelling, simulation and analysis parts of CPN Tools / CPN IDE, including their CPN ML inscription language: colour sets, variables, functions, guards and timed tokens.

• Edit: places, transitions and arcs, with their inscriptions, guards, time delays and declarations (syntax-highlighted). Undo and redo cover everything.
• Hierarchy: substitution transitions run their subpages (a port place is the socket place it is assigned to), also several levels deep. Select a substitution transition and press Open subpage to go there.
• Step through: green transitions are enabled. Click one to fire it, or pick an exact binding in the inspector. Back undoes a step, and Trace highlights the path so far.
• Simulate: Play (1–60 firings per second) or Fast-forward. The firing history can be exported as an event log and mined straight away.
• State space: runs in a separate process, so it can be stopped at any moment. It reports dead markings, home markings, liveness and bounds.
• Rendering: models look the way CPN Tools and CPN IDE draw them (bendpoints, label positions, token bubbles), and they save back to .cpn.

Stepping through a model	Editing an arc (handles on every bend)

Working on the canvas

Both editors work the same way. Arcs follow the rules of CPN IDE.

The tool buttons have icons, and the mouse cursor over the canvas shows the active tool: a plain pointer for Select, a crosshair with a circle, square or arrow for the others.

Keyboard shortcuts

The app shows each shortcut the way your system writes it.

Files

Example files: examples/petri/*.pnml (Petri nets), examples/*.cpn (coloured nets) and tests/data/ (a plane-boarding model and log from the course).

For developers

pytest -q                 # the whole suite, including GUI tests that run offscreen
openprocess --help              # command line: check, simulate, state space, mining

The same commands work on macOS, Windows and Linux. openprocess mine covers the process mining side: stats, filter, discover (α, IM, IMf, heuristics), conform, soundness and invariants; openprocess exercises check, marks, import and computes serve exercise packs. docs/definitions.md is generated from openprocess/mining/definitions.py; after editing a definition, run python -m openprocess.mining.definitions > docs/definitions.md (a test checks it). Likewise docs/references.md — every source OpenProcess's notation and algorithms follow, also in the app under Help ▸ References — is generated from openprocess/references.py with python -m openprocess.references > docs/references.md.

The engines (openprocess.mining, openprocess.ml, openprocess.sim, openprocess.analysis) have no dependencies, so they work in a notebook or a script:

from openprocess.mining import read_xes, inductive_miner
from openprocess.mining.analysis import check_soundness

net = inductive_miner(read_xes("log.xes").simple_log()).net
report = check_soundness(net)
print(report.sound, report.findings)

docs/how-it-works.md covers the architecture, the CPN ML subset, binding search, timed nets, the state space, the file format and the project layout.

Workflows

File ▸ New Workflow opens a workflow that already runs on the first log of your folder (or a typed log): Discover and check (a log, the Inductive Miner, a fitness check), Compare discovery (three miners side by side), Noise sweep (one setting over a range, the scores stacked), Fitness with confidence (bootstrap intervals, a test and a plot; needs the science extra) and Predict the next activity. Or start empty.

• The page is the canvas. Its header has Canvas | Summary, then + Add box, Run ▶, and ⋯ for Re-run, Record, Export experiment and Save. The sidebar beside it lists the folder's analyses and, folded under them, its logs.
• + Add box (or a double-click on the canvas) opens every box, by group: the six core groups side by side (Input, Filter, Discover, Check, Compare, Output) and one line for the rest (Science, Predict, Coloured nets, Sweep, your own boxes) with Show all. Under Input, the folder's own files: one click adds the box that reads the file, already set. Type to search them all: "alpha" finds the α-algorithm, "boarding" the log; Enter adds the first match.
• Files flow into the canvas. Drop a log, an OCEL 2.0 object-centric log (.jsonocel), a PNML file, a .cpn or a ts.txt on the canvas and it becomes its input box at that spot; an input box names its file ("INPUT · boarding.xes"). Open log… and Log from notation… in the sidebar land as boxes on the current analysis (or a new one named after the file). In a box's Settings, Choose… picks the file and the list beside it offers only the files the box can read.
• Summary is the key figure of every box, in one place: a tile per box, in the order the boxes run (a score's first metric, a table's size, a log's cases, a net's places and transitions). Nothing is computed there: a tile is the box's result, as on the canvas, and a tile opens the box. The process map under the tiles is the Directly-follows graph box's result; an analysis without that box offers to add it in one click.
• Connect by dragging from the dot on the right of a box: while you drag, only the inputs that take that kind of result light up, so a wrong connection cannot be made. Click a wire and press Delete to remove it.
• Click a box and the side panel appears beside the canvas, on Result (the net, the log's figures, the table, the figure; a log's Result has Open as log › for the dotted chart, process map, footprint, variants and cases, and a net's has Open a copy in Model ›). A page opened this way shows "‹ Back to " above its title. A discovered net can be tidied on the Result tab by dragging its places and transitions (the layout is saved with the workflow); the net itself is not changed there. Its other tabs: How (what the box reported: notes, intermediate values, the derivation), Code (the box's few lines and, under them, the actual algorithm it calls: the α-algorithm's eight steps, the Inductive Miner's cuts, with the work each follows and Whole file for the module) and Settings (a control per setting; Sweep a number over a range). ⤢ opens the tab in a window of its own; ✕, or a click on the canvas, puts the panel away.
• Only what changed runs again. Every box shows a status dot: waiting, running, done, failed (the error is on the Result tab; the rest keeps working), or waiting for your OK.
• Record shows the workflow as Python and the file with its record; Re-run says what changed since it was saved (an input file, a box file, a seed) before running everything again.
• Your own boxes: a .py file in the folder's boxes/ subfolder (see below). The app asks once per folder before running them, and reloads a box when its file is saved.
• Groups: select boxes and press ⌘G to make one box of them, with the connections that reach outside; double-click it to open its own canvas, ⇧⌘G to ungroup. Save as a box in the side panel writes the group to boxes/, so it is listed under Yours and can be used in any workflow.
• Export experiment (under ⋯) writes a zip with the workflow file and its record, the inputs, your boxes, every result as a file (CSV, PNML, SVG, XES), a requirements.lock and a README that says what was run: supplementary material for a paper, which openprocess run --check can verify.
• The side panel resizes by dragging the gap beside it; double-click the gap, or View ▸ Reset Workflow Layout, for its default width.
• Connections (at the bottom of the sidebar, or View ▸ Connections) draws what flows in, OpenProcess and its boxes, what flows out, and the optional tools (pandas, numpy, scipy, matplotlib, …) with whether each is installed, how to install it and the boxes it brings. All of it is read from the box library. Install… works in the downloaded app too: it carries pip and installs into a folder of your own (on a Mac, ~/Library/Application Support/OpenProcess/packages), and the boxes that need the package come alive without a restart. PM4Py needs a Python install (pip install pm4py), as parts of it are built from source.
• Motion is kept short: a space switch, the side panel and Canvas ↔ Summary settle in a fifth of a second, and a box pulses once when it finishes. OPENPROCESS_NO_MOTION=1 turns it off.

Workflows from Python

Every algorithm is also a box: a Python function with type hints that the app (from 0.7) draws on a canvas. A workflow of boxes runs from Python or from the command line, and its .cpnflow file records what is needed to get the same numbers again: fingerprints of the input files and of the box code, every seed, and the installed packages.

from openprocess.flow import Workflow, Runner, save
from openprocess.flow.boxes.input import open_log
from openprocess.flow.boxes.discover import inductive_miner
from openprocess.flow.boxes.check import check_fit

wf = Workflow("orders")
log = wf.add(open_log, {"file": "orders.xes"})
model = wf.add(inductive_miner, {"noise": 0.2})
fit = wf.add(check_fit)
wf.connect(log, model); wf.connect(model, fit, "model"); wf.connect(log, fit, "log")
run = Runner().run(wf)
print(run.value(fit).metrics)                  # fitness, precision, generalisation, simplicity
print(run.result(model).explanation.steps)     # how the Inductive Miner got there
save(wf, "orders.cpnflow", run)

openprocess run orders.cpnflow --check     # re-run; fails if any result differs from the record
openprocess run orders.cpnflow --sweep noise=0..0.5 step 0.1
openprocess boxes                          # the 47 boxes, with a folder's boxes/
openprocess datasets list                  # the BPI Challenge, Sepsis, ... logs by name

A box of your own is one function in a boxes/ folder:

from openprocess.flow import box, EventLog, TransitionSystem

@box(group="Discover")
def last_two(log: EventLog, representation: str = "multiset") -> TransitionSystem:
    """The last two activities as the state."""
    ...

pip install -e ".[science]" adds the pandas, NumPy, SciPy and matplotlib boxes (describe, bootstrap intervals, tests, plots). Large logs are read into columns rather than objects, so a million events fit in memory. docs/workflows.md has the whole framework: writing a box, the types, the How tab, sweeps, the prediction pipeline, the record and running in CI.

Building the apps. packaging/ turns OpenProcess into a standalone app with PyInstaller. In the environment:

pip install pyinstaller
python packaging/build.py      # → dist/OpenProcess.app or dist/OpenProcess/, plus a .dmg / .zip / .tar.gz

The script also smoke-tests the result. Each system can only build its own app, so the Build apps workflow builds all of them on GitHub: for every pull request (after the test suite passes; not for documentation-only changes) and for every release tag. Download them from the run's page, under Artifacts, or start a build by hand with Run workflow on the Actions tab.

Publishing a release:

1. Add a section for the new version at the top of CHANGELOG.md (## 0.4.0, then a few bullet points). Write it for the people using the app: it becomes the text of the release on GitHub, and the app shows it when it offers the update.

2. Set __version__ in openprocess/__init__.py to the same version and merge both into main. It is the only place the version is written: pyproject.toml, the download names and the app's update check all read it from there.

3. Tag that commit with the same version and push the tag:

   git pull
   git tag v0.4.0
   git push origin v0.4.0
   

About five minutes later the Releases page has the macOS (Apple silicon and Intel), Windows and Linux apps. The build refuses a tag that does not match __version__, or a version with no section in CHANGELOG.md.

Updates. Each time it opens, the app checks the latest release on GitHub (Settings turns that off). If there is a newer version, a slim bar at the top of the window says so, without getting in the way: What's New shows the changelog of every version you don't have yet, Install Now installs it, Skip This Version stays quiet until the next one, and ✕ closes the bar until next time. Help ▸ Check for Updates… checks straight away. Installing downloads the file for the system, checks it against the SHA-256 GitHub lists for it, unpacks it next to the app, and restarts into the new version (the old one is kept until the new one is in place).

Run from source (a git clone), the app never changes itself: the bar's button says How to Update and explains git pull. It only appears when the clone is older than the latest release. See openprocess/gui/studio/updates.py.

Limitations and roadmap

Plainly stated:

1. A subpage used by several substitution transitions (one module, several instances) is reported as a problem rather than simulated: give each use its own copy of the page. Subpages used once, at any depth, simulate.
2. No CPN monitors or simulation reports, and no fairness properties in the state space report (it says so).
3. CPN ML is a large subset, not all of Standard ML: no exception declarations or handle, no datatype or structure declarations, and characters are one-letter strings. See docs/how-it-works.md.
4. Alignments are exact but unoptimised: they can take seconds on heavily concurrent models. They run in the background.
5. Plain Petri nets live on one page.
6. Regions are found exhaustively, so only for transition systems of up to 26 states (the result says when this limit is hit), and label splitting for transition systems that are not elementary is not suggested yet. Transition systems are typed, not drawn.

Next up: several instances of a subpage, CPN monitors, and signed apps that open without a security prompt.

Cite

If OpenProcess helped with a course, a thesis or a paper, cite it. Help ▸ Cite OpenProcess… in the app gives BibTeX and a one-line citation, and each algorithm's Code tab has Cite for the paper it follows. GitHub's Cite this repository reads CITATION.cff. Releases are archived on Zenodo, which gives each version a DOI; the all-versions DOI goes into CITATION.cff (doi:) once the first release is archived, and the app's citations pick it up from there.

Licence

MIT. See LICENSE.