Metadata-Version: 2.4
Name: s2mflow
Version: 0.1.6
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
License-File: LICENSE
Summary: Meta-generator: generating multicommodity flow instances from single-commodity flow instances.
Author-email: "Felix P. Broesamle" <felix.broesamle@kit.edu>, Stefan Nickel <stefan.nickel@kit.edu>
Maintainer-email: "Felix P. Broesamle" <felix.broesamle@kit.edu>
License: MIT
Requires-Python: >=3.13
Description-Content-Type: text/markdown
Project-URL: Documentation, https://s2mflow.readthedocs.io/en/latest
Project-URL: Homepage, https://github.com/FelixBroesamle/s2mflow
Project-URL: Issues, https://github.com/FelixBroesamle/s2mflow/issues
Project-URL: Repository, https://github.com/FelixBroesamle/s2mflow

# s2mflow

**A meta-generator for generating multicommodity flow instances from single-commodity flow instances.**

`s2mflow` is a Python library with a high-speed Rust core (via PyO3) designed to transform single-commodity minimum-cost flow (MCF) instances into minimum-cost multicommodity flow (MCMCF) instances. It is built for researchers in Operations Research, Mathematical Optimization, and Network Optimization who need to generate reproducible, scalable test data.

## Key Features

- **Blazing Fast**: Core logic implemented in Rust for zero-overhead data handling.
- **DIMACS Compatible**: Load standard `.min` single-commodity files.
- **Custom MCMCF Format**: Introduces the `.mcfmin` format for multicommodity data.
- **Supply Partitioning**:
    - `uniform`: Equal distribution of supply and demand across commodities.
    - `spread`: Randomized, heterogeneous distribution of supply and demand across commodities.
- **Randomizing Capacities and Costs**: Functionality for generating randomized commodity capacities and commodity costs for each arc.
- **Network Utilities**: Support for identifying incoming and outgoing edges.

## Installation

```bash
pip install s2mflow
```

## Quick Start

```python
# .min example data:
# c  *** Minimum cost flow ***
# c
# p min 5 10
# n 1 10
# n 5 -10
# a 1 2 0 10 9
# a 1 4 0 16 2
# a 2 4 0 10 10
# a 2 3 0 10 1
# a 3 5 0 10 10
# a 3 2 0 20 2
# a 3 4 0 17 9
# a 4 3 0 10 9
# a 4 1 0 10 3
# a 4 2 0 19 2

import s2mflow

# 1. Load a single-commodity network
network = s2mflow.load_min_instance("input.min")

# 2. Generate multicommodity data for 3 commodities
mc_data = s2mflow.generate_multi_commodity_data(
    instance=network,
    num_commodities=3,
    is_uniform=False,
    seed=42,
)

# 3. Save as a multi-commodity instance
s2mflow.save_multi_commodity_instance("output.mcfmin", network, mc_data)

# c Multicommodity flow generated by s2mflow
# p min 5 10 3 0 0 0 42
# n 1 10 2 3 5
# n 5 -10 -2 -3 -5
# a 1 2 0 10 10 9
# a 1 4 0 16 16 2
# a 2 4 0 10 10 10
# a 2 3 0 10 10 1
# a 3 5 0 10 10 10
# a 3 2 0 20 20 2
# a 3 4 0 17 17 9
# a 4 3 0 10 10 9
# a 4 1 0 10 10 3
# a 4 2 0 19 19 2
```

## Citing

If you use `s2mflow` in your research, please cite the software:
```text
@software{s2mflow2026,
  author = {Broesamle, Felix P. and Nickel, Stefan},
  title = {s2mflow: A Meta-generator for Multicommodity Flow Instances},
  year = {2026},
  url = {https://github.com/FelixBroesamle/s2mflow}
}
```

## Resources

- **Documentation**: [s2mflow.readthedocs.io](https://s2mflow.readthedocs.io/en/latest/)
- **PyPI Package**: [pypi.org/project/s2mflow](https://pypi.org/project/s2mflow/)

## License

Distributed under the MIT License. See `LICENSE` for more information.
