Skip to main content

r4pm

Python bindings for the Rust4PM Project: Process mining in Python with the speed of Rust

This library provides basic import/export of XES/OCEL event data, as well as other exposed functionality from the Rust4PM project (e.g., process discovery algorithms).

Features

  • Fast XES/OCEL Import/Export: Efficient Rust-based import and export of .xes, .xes.gz, and OCEL2 (.xml/.json) files
  • Auto-Generated Bindings: All process_mining functions automatically exposed with full IDE support (autocomplete, type hints, docs)
  • Registry System: Manage data objects as typed handles and convert between types as needed
  • Conformance Checking: Alignments, fitness and precision on pm4py or r4pm logs and Petri nets
  • Polars DataFrames: Polars facilitates the fast transfer of event data from Python to Rust and vice versa

Installation

pip install r4pm         # default
pip install r4pm-full    # additionally bundles DuckDB (~15 MiB larger)

Both provide the r4pm import package, so install one or the other. pip install r4pm[pm4py] adds pm4py for the pm4py interoperability, pip install r4pm[progress] adds tqdm for progress bars. r4pm-full adds the DuckDB bindings (write_ocel_to_duckdb, stream_ocel_file_to_duckdb, ...) and .duckdb import and export, nothing else differs.

import r4pm

r4pm.__variant__                 # "default" or "full"
r4pm.__features__                # optional features compiled in
r4pm.has_feature("ocel-duckdb")

Quick Start

from r4pm import bindings
import r4pm

# Load an OCEL file into the registry; returns a handle (also usable as the item's ID)
ocel = r4pm.import_item('OCEL', 'data/orders.xml')

# Bindings convert an item to the type they take (most take a SlimLinkedOCEL); convert once
# when calling several of them
locel = ocel.convert('SlimLinkedOCEL')

# Get statistics
num = bindings.num_events(ocel=locel)
print(f"Events: {num}")

# Discover object-centric DFG
dfg = bindings.discover_ocdfg(locel)
print(f"Discovered DFG for {len(dfg['object_type_to_dfg'])} object types")

# For case-centric event logs:
log = r4pm.import_item('EventLog', 'data/log.xes')
case_dfg = bindings.discover_dfg(log)

How It Works

Auto-Generated Bindings

All functions from the process_mining Rust library are automatically discovered and exposed as Python functions with:

  • Full type hints for IDE autocomplete
  • Automatic documentation from Rust docs
  • Type validation via JSON schemas

The bindings are organized by module (mirroring the Rust crate structure):

from r4pm import bindings

# Top-level access to all functions
bindings.discover_dfg(event_log=log_id)
bindings.num_events(ocel=locel_id)

# Or use submodules for organization
from r4pm.bindings.discovery.case_centric import dfg
dfg.discover_dfg(event_log=log_id)

Bindings are automatically generated during the Rust build via build.rs.

Registry System

Data is managed through a registry that holds different object types:

  • OCEL - Raw OCEL data
  • SlimLinkedOCEL - Memory-efficient linked OCEL (required by most functions)
  • IndexLinkedOCEL - Indexed OCEL for analysis
  • EventLog - Case-centric event log
  • EventLogActivityProjection - Activity-projected log for discovery
  • PetriNet, AcceptingPetriNet, ProcessTree, ObjectCentricPetriNet, OCDeclareModel - Process models

Registry items are returned as handles (r4pm.handles), typed by kind (handles.OCEL, handles.EventLog, ...). A handle is a str subclass holding the item's ID, so it works wherever an ID is accepted. A handle returned by r4pm owns its item: the item is removed when the handle is closed, leaves a with block, or is garbage collected. Items created with an explicit ID (item_id=..., output_id=...) stay until removed with r4pm.remove_item.

# Load files into the registry
ocel = r4pm.import_item('OCEL', 'file.xml')
log = r4pm.import_item('EventLog', 'file.xes')

# Convert between types (either like this or using r4pm.convert_item)
locel = ocel.convert('IndexLinkedOCEL')
proj = log.convert('EventLogActivityProjection')

with r4pm.import_item('AcceptingPetriNet', 'model.pnml') as net:
    print(net.kind, net.to_json()["transitions"][0])
# net is removed from the registry here

# List registry contents
for item in r4pm.list_items():
    print(f"{item['id']}: {item['type']}")

Arguments that take a registry item also accept a path to a file, which is loaded only for that call. Bindings that change an item in place (e.g., locel_add_event) need a stored item instead. Failed calls raise r4pm.BindingError.

A binding that returns a value and also produces an item, like extraction_run, takes a required output_id. It stores the item under that ID and returns the value (here the ExtractionReport).

Progress and cancellation

Long-running bindings report their progress. r4pm.set_progress shows it for every binding call, and the progress= argument of each binding overrides that for one call:

r4pm.set_progress("tqdm")      # one tqdm bar per stage (pip install r4pm[progress])
r4pm.set_progress(lambda stage, done, total: print(stage, done, total))  # total may be None
r4pm.set_progress(None)        # the default: no progress display

bindings.discover_oc_declare(locel, progress="tqdm")
bindings.discover_oc_declare(locel, progress=False)  # nothing for this call

Ctrl+C cancels a running binding, and so does an exception raised by the progress callback. The call stops at the next cancellation check of the binding and stores nothing, then the KeyboardInterrupt (or the callback's exception) is raised. A binding that never checks runs to the end first. Warnings of a binding (e.g., skipped rows in an import) become Python UserWarnings.

r4pm.import_item and r4pm.df.import_ocel (with its _xml/_json/_pm4py variants) work the same way: they take progress= (for most file formats, stage "Importing" with the bytes read), and a cancelled import_item adds nothing to the registry.

Simple Import/Export API

For direct DataFrame operations without the registry, use the df submodule.

XES

import r4pm

# Import returns (DataFrame, log_attributes_json)
xes, attrs = r4pm.df.import_xes("file.xes", date_format="%Y-%m-%d")
r4pm.df.export_xes(xes, "test_data/output.xes")

OCEL

# Returns dict with DataFrames: events, objects, relations, o2o, object_changes
ocel = r4pm.df.import_ocel("file.xml")
print(ocel['events'].shape)
r4pm.df.export_ocel(ocel, "export.xml")

# PM4Py integration (requires pm4py)
ocel_pm4py = r4pm.df.import_ocel_pm4py("file.xml")
print(ocel['events'].shape)
r4pm.df.export_ocel_pm4py(ocel_pm4py, "export.xml")

Petri Nets

A Petri net is a JSON-compatible dict (r4pm.petri_net.PetriNet) with places and transitions in lists, identified by index. Each transition lists its input and output arcs as [place index, weight], a silent transition has label None, and markings map place indices to token counts:

from r4pm import petri_net

net = petri_net.import_pnml("model.pnml")
# {'places': [{'name': 'source'}, {'name': 'sink'}],
#  'transitions': [{'label': 'a', 'name': 't1', 'inputs': [[0, 1]], 'outputs': [[1, 1]]}],
#  'initial_marking': {'0': 1}, 'final_marking': {'1': 1}}
petri_net.export_pnml(net, "copy.pnml")

pm4py_net, im, fm = petri_net.to_pm4py(net)        # and back with petri_net.from_pm4py
handle = petri_net.to_handle(net)                  # keep it in the registry

Conformance Checking

r4pm.conformance computes alignments, fitness and precision with the Rust implementation. Logs can be pm4py EventLogs, pandas or polars DataFrames (pm4py column names), r4pm handles, XES paths, or lists of activity sequences. Nets can be pm4py nets with markings, Petri net dicts, handles, or PNML paths.

With pm4py objects, the results have pm4py's shape:

import pm4py
from r4pm import conformance

log = pm4py.read_xes("log.xes")
net, im, fm = pm4py.discover_petri_net_inductive(log, noise_threshold=0.2)

conformance.fitness(log, net, im, fm)
# {'log_fitness': 0.962, 'average_trace_fitness': 0.907, 'percentage_of_fitting_traces': 62.6, ...}
conformance.precision(log, net, im, fm, preset="pm4py")   # as pm4py.precision_alignments

aligned = conformance.alignments(log, net, im, fm)          # one per trace, as pm4py
aligned[0]["alignment"]   # [('A', 'A'), ('>>', None), ('B', '>>'), ...]
conformance.precision(aligned)                              # reuses the alignments

With r4pm objects, nothing passes through Python but the result:

import r4pm
from r4pm import bindings, conformance
from r4pm.conformance import AlignmentOptions

log = r4pm.import_item("EventLog", "log.xes")
net = bindings.discover_inductive_net(log)    # Petri net dict

conformance.fitness(log, net)
conformance.fitness(log, net, method="token_based")    # nets without silent transitions
conformance.precision(log, "model.pnml", preset="prom")
conformance.precision_result(log, net, report_escaping_edges=True)

options = AlignmentOptions(log_move_cost=2, max_states=1_000_000, max_memory_mib=4096)
aligned = conformance.alignments(log, net, options=options, num_threads=4)
for variant in aligned.variants:                   # typed, one per trace variant
    print(variant.frequency, variant.fitness, [m.kind for m in variant.moves or []])

Precision presets: "default" (paths from optimal alignments), "prom" (ProM's "Check Precision using Escaping Edges") and "pm4py" (as pm4py.precision_alignments).

r4pm.interop converts event logs between pm4py and the registry (log_from_pm4py, log_to_pm4py), and Petri nets (net_from_pm4py, net_to_pm4py).

Reflow

Reflow decides which object types flow through each activity, so discovery runs on a smaller log. It is available through the generated bindings:

import r4pm
from r4pm import bindings

with r4pm.import_item("OCEL", "order-management.json") as ocel:
    slim = ocel.convert("SlimLinkedOCEL")
    result = bindings.reflow(slim)                     # flow layer and cell states
    flow = bindings.reflow_flow_projection(bindings.reflow_tag(slim, result))
    model = bindings.reflow_annotated_ocpn(slim, result)
    svg = bindings.reflow_annotated_ocpn_svg(model)    # show in Jupyter with IPython.display.SVG

reflow_tag returns the log with non-flow participations marked by the qualifier prefix !, readable by any OCEL 2.0 tool; reflow_flow_projection keeps only the flowing ones.

Examples

examples/ holds short scripts that check their own results: progress.py (progress, cancellation, warnings) and extraction.py (OCEL extraction from SQLite with a blueprint). Run one with python examples/progress.py. pytest tests/test_examples.py runs all of them.

Development

Setup

# Install Rust: https://rustup.rs/
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install in development mode
pip install maturin
maturin develop --release

How Bindings Are Generated

Python bindings are automatically generated during the Rust build via build.rs. Thus, bindings are always in sync with the Rust code and do not require manual regeneration.

The build script:

  1. Reads function metadata from the process_mining crate
  2. Generates r4pm/bindings/ with typed Python wrappers and .pyi stubs
  3. Organizes functions by their Rust module structure

Building for Release

maturin build --release  # Creates wheels in target/wheels/

The wheel automatically includes the generated bindings.

Running Tests

pip install pytest pm4py polars pandas pyarrow
maturin develop
pytest

The test suite (tests/) covers conformance checking against pm4py (alignment fitness, per-trace alignments, precision, token-based replay), the input and output forms, registry handles, Petri net conversion, and the generated bindings and stubs.

LICENSE

This package is licensed under either Apache License Version 2.0 or MIT License at your option.

Metadata

Release files for r4pm 0.7.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for r4pm 0.7.1
File Size Uploaded Provenance Actions
r4pm-0.7.1.tar.gz 115.5 kB With provenance Details for r4pm-0.7.1.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for r4pm 0.7.1
File Actions
r4pm-0.7.1-cp39-abi3-win_amd64.whl CPython 3.9 abi3 Windows x86-64 Details for r4pm-0.7.1-cp39-abi3-win_amd64.whl
r4pm-0.7.1-cp39-abi3-musllinux_1_2_x86_64.whl CPython 3.9 abi3 Linux musl 1.2+ x86-64 Details for r4pm-0.7.1-cp39-abi3-musllinux_1_2_x86_64.whl
r4pm-0.7.1-cp39-abi3-manylinux_2_28_x86_64.whl CPython 3.9 abi3 Linux glibc 2.28+ x86-64 Details for r4pm-0.7.1-cp39-abi3-manylinux_2_28_x86_64.whl
r4pm-0.7.1-cp39-abi3-manylinux_2_28_aarch64.whl CPython 3.9 abi3 Linux glibc 2.28+ ARM64 Details for r4pm-0.7.1-cp39-abi3-manylinux_2_28_aarch64.whl
r4pm-0.7.1-cp39-abi3-macosx_11_0_arm64.whl CPython 3.9 abi3 macOS 11.0+ ARM64 Details for r4pm-0.7.1-cp39-abi3-macosx_11_0_arm64.whl
r4pm-0.7.1-cp39-abi3-macosx_10_12_x86_64.whl CPython 3.9 abi3 macOS 10.12+ x86-64 Details for r4pm-0.7.1-cp39-abi3-macosx_10_12_x86_64.whl

Total release size: 96.4 MB

Release files / r4pm-0.7.1.tar.gz

Download URL r4pm-0.7.1.tar.gz
Size 115.5 kB
Tags Source
SHA-256 checksum
How to use checksums
cb174228a6514c391239f2e47a5e87a91a4b8244f5441220081bc33f7254ba4d
BLAKE2b-256 checksum
How to use checksums
21ac302e69e1e78d735f98e0fede1cf4c66ed834b08f7a63730511fe2f170e9e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / r4pm-0.7.1-cp39-abi3-win_amd64.whl

Download URL r4pm-0.7.1-cp39-abi3-win_amd64.whl
Size 15.0 MB
Tags CPython 3.9 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
da0beffbbbd2fe8d075e0e18ed5ccb480df49a08b502bc003ea5cab499633d4e
BLAKE2b-256 checksum
How to use checksums
0c0d7b587ca696fee5d664b74720b87c9ec18b45c9949d301d8cb3b8ad801303
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / r4pm-0.7.1-cp39-abi3-musllinux_1_2_x86_64.whl

Download URL r4pm-0.7.1-cp39-abi3-musllinux_1_2_x86_64.whl
Size 17.8 MB
Tags CPython 3.9 Linux musl 1.2+ x86-64 abi3
SHA-256 checksum
How to use checksums
9de34a85a13b120f0f69576bbd212b39bc4a2b9c8ba3a7f3f66a00980409465c
BLAKE2b-256 checksum
How to use checksums
e30e8cec3e978023199cc523926d12f22b44d91ef4390622b0b6777c21e62943
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / r4pm-0.7.1-cp39-abi3-manylinux_2_28_x86_64.whl

Download URL r4pm-0.7.1-cp39-abi3-manylinux_2_28_x86_64.whl
Size 16.4 MB
Tags CPython 3.9 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
e6608bfcf53cd266f2a2a8ad5f2a834280a233baa13ea8f0610580536d4123d1
BLAKE2b-256 checksum
How to use checksums
ff24e1306f2c99c4d476aa2595492ca96b0960833efb132a275771dc5b7019b1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / r4pm-0.7.1-cp39-abi3-manylinux_2_28_aarch64.whl

Download URL r4pm-0.7.1-cp39-abi3-manylinux_2_28_aarch64.whl
Size 16.9 MB
Tags CPython 3.9 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
021745a6d4e9ffb97a5758e8626cc9a586cab29276ce8ca90ad349831c71794b
BLAKE2b-256 checksum
How to use checksums
a6142c5bc05eae8a1ea693d0ddd4f6910e76f93d39e83fe13c8fbcd07dee7bc8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / r4pm-0.7.1-cp39-abi3-macosx_11_0_arm64.whl

Download URL r4pm-0.7.1-cp39-abi3-macosx_11_0_arm64.whl
Size 14.6 MB
Tags CPython 3.9 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
b1c5c8b98978314449f9364fece51657e987cbbc80a5c40eb0b0f64f4fd8dfc3
BLAKE2b-256 checksum
How to use checksums
5d4a602aa88647cca41a738260b400665543b16f109aa5f1a2d72b2febd6855b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / r4pm-0.7.1-cp39-abi3-macosx_10_12_x86_64.whl

Download URL r4pm-0.7.1-cp39-abi3-macosx_10_12_x86_64.whl
Size 15.4 MB
Tags CPython 3.9 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
69b68e0e734326d7d7a99221f57c143fa48f2ff9b7b0ce274b9ad64bb96ea963
BLAKE2b-256 checksum
How to use checksums
b9f34ad7b1b910e473b9c13eba6852b3c65aa415d63442af2b916ff938d4adba
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for r4pm 0.7.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 7 files in this release have been uploaded with provenance metadata.

Select from 7 files

Attestation for r4pm-0.7.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page