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.0

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.0
File Size Uploaded Provenance Actions
r4pm-0.7.0.tar.gz 107.9 kB With provenance Details for r4pm-0.7.0.tar.gz

Built distributions (wheels)

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

Total release size: 95.9 MB

Release files / r4pm-0.7.0.tar.gz

Download URL r4pm-0.7.0.tar.gz
Size 107.9 kB
Tags Source
SHA-256 checksum
How to use checksums
ee1f21257aa00441af073b9e123c627fd90997f706c37da4deac2cc080f6b1cf
BLAKE2b-256 checksum
How to use checksums
3517f10071e5459e8810bdd8f30f49af07f14d7fd776ba07e3638ebfc35fbc1b
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 18, 2026.

Transparency log

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

Download URL r4pm-0.7.0-cp39-abi3-win_amd64.whl
Size 14.9 MB
Tags CPython 3.9 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
cf52c4a466a377cc027680b482eaca702971bd50fee67095dee5d9f7eb2bb228
BLAKE2b-256 checksum
How to use checksums
22175b7684a1abef4c17be9e324bb4ac83fefdaf77d75c78459b9266f9fcb117
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 18, 2026.

Transparency log

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

Download URL r4pm-0.7.0-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
54ee33cfbe7586d99fff959bf5d875dddf5dd6db55c219b98951f03d605249e9
BLAKE2b-256 checksum
How to use checksums
7d02ee4a71232f8a3ae6b2e502af1b9fdc559f5ffbd944c9860553e95553285f
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 18, 2026.

Transparency log

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

Download URL r4pm-0.7.0-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
f0ae64eec0726a827ca05288d95784bd1be5b2edd55bbd395c44dc0bf2b56ff3
BLAKE2b-256 checksum
How to use checksums
204b341933488112a331d2110f852816e80a9da770339f27995e6b44b4c14957
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 18, 2026.

Transparency log

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

Download URL r4pm-0.7.0-cp39-abi3-manylinux_2_28_aarch64.whl
Size 16.8 MB
Tags CPython 3.9 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
50682c25816cf3115042fcdf2a14074bbbfdd12b4462346a3b366d263e1aec80
BLAKE2b-256 checksum
How to use checksums
5dae9f737c613d2d6d92d26dd9e729c5ec1e03df201f6a9a3eab171920c6865d
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 18, 2026.

Transparency log

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

Download URL r4pm-0.7.0-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
1b862fe41c6b860c798279d8137a9c3e30c77566f25df9e11aea05b1354f9b51
BLAKE2b-256 checksum
How to use checksums
d1a712923c292c390c2d1e239a21da30409412f0a98a26ebee7c25d85ca9ddde
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 18, 2026.

Transparency log

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

Download URL r4pm-0.7.0-cp39-abi3-macosx_10_12_x86_64.whl
Size 15.3 MB
Tags CPython 3.9 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
742a098042c7b91a70ad40ab46a4e2485a4f065584b7d18c50bb91b98997f370
BLAKE2b-256 checksum
How to use checksums
6d691fd3a83ed81c5ff91b827c6022a178587fcdd6b3f8adeca4573b71d84573
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 18, 2026.

Transparency log

Security for r4pm 0.7.0

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.0.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 18, 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