===========
split-miner
===========


Description
===========

**split-miner** is a Python implementation of the Split Miner algorithm
for automated discovery of BPMN process models from event logs.

Split Miner (Augusto et al., 2017/2019) produces simple process models
with low branching complexity and consistently high and balanced fitness
and precision, while being guaranteed to produce deadlock-free models
with concurrency.

This package implements Split Miner 1.0 with the following pipeline:

1. DFG and loops discovery
2. Concurrency discovery
3. Edge filtering
4. Split gateways discovery
5. Join gateways discovery (via RPST / SPQR-tree)
6. OR-joins minimization (via dominator tree)

Features:

- Pure Python --- no compiled extensions.
- Implements Split Miner 1.0 from the original papers.
- Uses SPQR-tree for correct RPST computation.
- Typed package with PEP 561 support.
- Requires Python 3.10 or later.


Installation
============

You can install split-miner with ``pip``:

::

    pip install split-miner

You may also install the latest source from the
`split-miner GitHub repository`_.

::

    pip install git+https://github.com/imacat/split-miner.git


Quick Start
===========

.. code-block:: python

    from split_miner import BPMNModel, split_miner

    # Create an event log (trace -> frequency)
    traces: dict[tuple[str, ...], int] = {
        ("a", "b", "c", "d"): 10,
        ("a", "c", "b", "d"): 10,
    }

    # Discover a BPMN model
    model: BPMNModel = split_miner(traces)

    # Inspect the model
    print(f"Tasks: {len(model.tasks)}")
    print(f"Gateways: {len(model.gateways)}")
    print(f"Edges: {len(model.edges)}")


Parameters
==========

- **epsilon** (float, 0--1): Controls concurrency detection sensitivity.
  Lower values require more balanced directly-follows frequencies to
  detect concurrency.  Default: 0.33.
- **eta** (float, 0--1): Controls edge filtering / retention.
  Lower values retain more edges, resulting in higher fitness at the
  cost of lower precision.  Default: 0.8.


References
==========

- A. Augusto, R. Conforti, M. Dumas, M. La Rosa, and A. Polyvyanyy,
  "Split Miner: Automated Discovery of Accurate and Simple Business
  Process Models from Event Logs," *Knowledge and Information Systems*,
  vol. 59, no. 2, pp. 251--284, 2019.
  `doi:10.1007/s10115-018-1214-x`_

- A. Augusto, R. Conforti, M. Dumas, M. La Rosa, and
  A. Polyvyanyy, "Split Miner: Discovering Accurate and Simple
  Business Process Models from Event Logs," *Proc. ICDM 2017*,
  pp. 1--10, 2017. `doi:10.1109/ICDM.2017.9`_


Acknowledgments
===============

This project was implemented from scratch in Python based on the
original Split Miner papers.

Development was assisted by `Claude Code`_ (Anthropic).


Copyright
=========

 Copyright (c) 2026 imacat.

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.


Authors
=======

| imacat
| imacat@mail.imacat.idv.tw
| 2026/3/10

.. _split-miner GitHub repository: https://github.com/imacat/split-miner
.. _doi\:10.1007/s10115-018-1214-x: https://doi.org/10.1007/s10115-018-1214-x
.. _doi\:10.1109/ICDM.2017.9: https://doi.org/10.1109/ICDM.2017.9
.. _Claude Code: https://claude.com/claude-code