Metadata-Version: 2.4
Name: tvaw-lib
Version: 1.0.0
Summary: TVAW Nets implementation
Author-email: "Sergeev I.I." <mrapple433@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Sergeev Ilya Ivanovich (mrapple433@gmail.com)
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Keywords: process-mining,pm4py,object-centric-petri-nets,event-log,tvaw
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pm4py<3.0,>=2.7
Requires-Dist: pandas>=2.0
Requires-Dist: numpy>=2.0
Requires-Dist: networkx>=3.0
Requires-Dist: scipy>=1.10
Requires-Dist: matplotlib>=3.8
Requires-Dist: lxml>=5.0
Requires-Dist: tqdm>=4.66
Requires-Dist: graphviz>=0.20
Requires-Dist: cvxopt>=1.3
Requires-Dist: z3-solver>=4.12
Dynamic: license-file

# TVAW Miner: Typed Petri Nets with Variable Weight Arcs

**Authors**: Sergeev I.I., Lomazova I. A.
**Scope**: Object-Centric Process Mining

## Overview

**TVAW Lib** - an open-source Python library for the discovery, analysis, and evaluation of **Typed Petri Nets with Variable Weight Arcs (TVAWs)**. The tool extends classical Petri net–based process mining by supporting typed tokens and variable arc weights, enabling richer modeling of object-centric and multi-entity processes.

The framework is currently built on top of the PM4Py ecosystem, with planned native integration in future releases.

## Motivation

Traditional process discovery techniques often assume homogeneous tokens and fixed arc semantics, limiting their applicability in object-centric settings. TVAWs generalize these models by:

- Introducing **typed tokens** to distinguish object classes,
- Allowing **variable arc weights** to capture flexible consumption/production rules,
- Supporting **fine-grained behavioral constraints** across interacting entities.

This aligns with recent advances in object-centric process mining .

## Features

1. **Discovery of TVAW models** from event logs
2. **Conformance checking** (precision and other metrics)
3. **Metric computation** for model quality evaluation
4. **Visualization** for visual analysis
5. **Integration with PM4Py** pipelines

## Usage

### TVAW Discovery & evaluation

In code:

```python

ocel = pm4py.read_ocel(ocel_path)
net, im, fm = discover_tvaw(ocel)
```

Then visualize with:

```python
tvaw_gviz = visualize_tvaw(net)
ocpn_visualizer.save(tvaw_gviz, f"{out_path_dir}/tvaw.png")
```

With CLI:

Create _n_ virtual environments:

```sh
# For main discovery
python3 -m venv venv
pip3 install -r requirements.txt

# For analysis
python3 -m venv venv1
pip3 install -r precision/requirements.txt

# For testing
python3 -m venv venv2
pip3 install -r requirements_test.txt
```

```sh
source ./venv2/bin/activate && python3 test.py \
    --logs-dir ./test/jsonocel \
    --results-dir ./results/logistics \
    --compare-python ./venv/bin/python  \
    --precision-python ./venv1/bin/python \
    --compare-script ./produce_comparison.py \
    --precision-script ./precision/calc_precision.py
```

### OCEL Generation

Example:

```sh
python3 ./gen_tvaw_logs.py test/gen_configs/cars_min.json test/jsonocel/cars_min.jsonocel
```

## Architecture

The tool is structured into the following components:

1. **Discovery Module**: Constructs TVAWs from event logs
2. **Models layer**: Defines the base structures
3. **Evaluation Module**: Computes precision, and structural metrics (fitness is proven to be = 1)
4. **Visualization Module**: Provides visualization capabilities

## Theoretical Foundations

The theoretical basis for TVAWs are defined in the “Typed Petri Nets with Variable Arc Weights” paper by Irina A. Lomazova, Alexey A. Mitsyuk, and Andrey Rivkin. For the details of the discovery approach, see the `docs` folder

## Roadmap

- Full integration into PM4Py
- Advanced visualization of TVAW models
- Performance optimization for large-scale logs
- Support for real-time process monitoring

## Contributing

Contributions are welcome. A PR shall contain documentation, review instructions and tests. Each contribution should have a particular defined and developed scope.

Please submit PRs or open issues for discussion.

## License

This project is licensed under the **MIT License**.

```
MIT License

Copyright (c) 2026

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...
```

## Acknowledgments

This work is inspired by foundational research in process mining and Petri nets, particularly in object-centric modeling and evaluation frameworks .
