s2mflow 0.1.19

Meta-generator: generating multicommodity flow instances from single-commodity flow instances.

s2mflow

A high-performance meta-generation framework for lifting single-commodity flow instances into the multicommodity space.

s2mflow is a Python library PyPI 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:

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 neighboring nodes.

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

Standard Installation

pip install s2mflow
# or via poetry
poetry add s2mflow

Building from Source

git clone https://github.com/FelixBroesamle/s2mflow.git
cd s2mflow
poetry install -vvv
poetry run maturin develop --release

Quick Start

# .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:

@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:

@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
• PyPI Package: pypi.org/project/s2mflow

License

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