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 dataSlimLinkedOCEL- Memory-efficient linked OCEL (required by most functions)IndexLinkedOCEL- Indexed OCEL for analysisEventLog- Case-centric event logEventLogActivityProjection- Activity-projected log for discoveryPetriNet,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:
- Reads function metadata from the
process_miningcrate - Generates
r4pm/bindings/with typed Python wrappers and.pyistubs - 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)
| 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)
| File | Actions Reset | |||
|---|---|---|---|---|
| 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 logRelease 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 logRelease 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 logRelease 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 logRelease 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 logRelease 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 logRelease 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 logSecurity 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.
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 logA 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.