Metadata-Version: 2.4
Name: s2mflow
Version: 0.1.7
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 high-performance meta-generation framework for lifting single-commodity flow instances into the multicommodity space.**

`s2mflow` is a Python library [PyPI](https://pypi.org/project/s2mflow/) 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.

`s2mflow` implements and extends the meta-generation framework introduced in:
```text
Felix P. Broesamle and Stefan Nickel. 2026. "On the Single-Multi-Commodity Gap: Lifting Single- to Multicommodity Flow Instances". Optimization Online. Preprint. Available at https://optimization-online.org/?p=34287.
```

## Key Features

- **High Performance**: 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 standardized multicommodity data storage.
- **Supply Partitioning Methods**:
    - `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-specific capacities and costs for each arc.
- **Network Utilities**: Support for identifying incoming and outgoing edges.

## The Extended `.mcfmin` Format

The library uses a natural extension of the DIMACS `.min` format to support multiple commodities:

- **Problem Line**: `p min <num_nodes> <num_edges> <num_commodities> <randomize_caps> <randomize_costs> <is_uniform> <seed = 0>`.
    - `seed`: relevant if `is_uniform = 0` (Spread method) or if randomization of commodity-specific capacities or costs is enabled (`randomize_caps = 1` or `randomize_costs = 1`).
- **Node Line**: `n <node_id> <total_demand> <demand_com_1> <demand_com_2> ... <demand_com_K>`.
- **Arc Line**: Depending on the randomization flags `(randomize_caps, randomize_costs)`:
    - Default `(0, 0)`: `a <from> <to> <low> <cap_total> <cap_total> <cost>`.
    - Commodity-specific capacities `(1, 0)`: `a <from> <to> <low> <cap_total> <cap_1> ... <cap_K> <cost>`.
    - Commodity-specific costs `(0, 1)`: `a <from> <to> <low> <cap_total> <cap_total> <cost_1> ... <cost_K>`.
    - Commodity-specific capacities and costs `(1, 1)`: `a <from> <to> <low> <cap_total> <cap_1> ... <cap_K> <cost_1> ... <cost_K>`.


## 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 use the following preferred citation for the framework:
```text
@misc{BroesamleNickel:SMCG,
    author = {Broesamle, Felix P. and Nickel, Stefan},
    title = {On the Single-Multi-Commodity Gap: Lifting Single- to Multicommodity Flow Instances},
    year = {2026},
    howpublished = {Optimization Online},
    note = {Preprint. Available at \url{https://optimization-online.org/?p=34287}},
    url = {https://optimization-online.org/?p=34287},
}
```

To cite `s2mflow` specifically 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.
