The .mcfmin Data Format

The s2mflow library introduces a clean, structured text standard that extends the classic DIMACS minimum-cost flow format to natively capture multicommodity properties, such as commodity-specific bounds, supply/demand splits, and variable cost structures.

File Structure Overview

An .mcfmin file consists of three types of lines:

Problem Line (p): Defines the network dimensions and randomization flags.
Node Line (n): Defines supply/demand and how it is partitioned across commodities.
Arc Line (a): Defines the edges, capacities, and costs. The structure of this line changes dynamically based on the flags set in the problem line.

1. The Problem Line

Syntax: p min <num_nodes> <num_edges> <num_commodities> <randomize_caps> <randomize_costs> <is_uniform> <seed>

randomize_caps (0 or 1): Flag indicating if commodity-specific capacities are used.
randomize_costs (0 or 1): Flag indicating if commodity-specific costs are used.
is_uniform (0 or 1): Flag indicating if the uniform partitioning method was used.
seed (Integer): The random seed used. Relevant if is_uniform = 0 (Spread method) or if randomization flags are set to 1. Defaults to 0.

2. The Node Line

Syntax: n <node_id> <total_demand> <demand_com_1> <demand_com_2> ... <demand_com_K>

This line explicitly lists how the total_demand of the baseline single-commodity node is partitioned into individual supplies/demands for all $K$ commodities.

3. The Arc Line

The length of the arc line expands dynamically depending on the randomization flags:

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>
Fully Randomized (1, 1): a <from> <to> <low> <cap_total> <cap_1> ... <cap_K> <cost_1> ... <cost_K>

Examples for the .mcfmin Format

Below, we illustrate how the file structure shifts when applying different generation configurations.

Based Single-Commodity Instance (input.min)

# c Base single-commodity instance (input.min)
# p min 4 5
# n 1 17
# n 4 -17
# a 1 2 0 10 10
# a 1 3 0 15 5
# a 2 4 0 10 10
# a 3 2 0 5 20
# a 3 4 0 15 4

Strategy 1: Uniform Partitioning

This strategy distributes the nodal demands as evenly as possible across the 4 commodities.

uniform_mc_data = s2mflow.generate_multi_commodity_data(instance=network, num_commodities=4, is_uniform=True, randomize_caps=False, randomize_costs=False)

s2mflow.save_multi_commodity_instance("uniform.mcfmin", network, uniform_mc_data)

# --- Output File Contents (uniform.mcfmin) ---
# c Multicommodity flow generated by s2mflow
# p min 4 5 4 0 0 1 0
# n 1 17 5 4 4 4
# n 4 -17 -5 -4 -4 -4
# a 1 2 0 10 10 10
# a 1 3 0 15 15 5
# a 2 4 0 10 10 10
# a 3 2 0 5 5 20
# a 3 4 0 15 15 4

Strategy 2: Spread Partitioning with Randomized Capacities

This strategy generates high commodity-demand heterogeneity and applies unfirom noise to individual commodity capacities.

# 2. Spread partitioning, randomized capacities
spread_rand_caps_mc_data = s2mflow.generate_multi_commodity_data(
    instance=network,
    num_commodities=NUM_COMMODITIES,
    is_uniform=False,
    randomize_caps=True,
    cap_a=0.6,
    cap_b=1.0,
    randomize_costs=False,
    seed=42,
)
#--- Output file contents--
# c Multicommodity flow generated by s2mflow
# p min 4 5 4 1 0 0 42
# n 1 17 4 6 1 6
# n 4-17-4-6-1-6
# a 1 2 0 10 9 9 9 8 10
# a 1 3 0 15 10 12 14 15 5
# a 2 4 0 10 7 7 10 9 10
# a 3 2 0 5 4 4 5 4 20
# a 3 4 0 15 10 13 10 13 4

Strategy 3: Spread Partitioning with Randomized Costs

This strategy generates high commodity-demand heterogeneity and applies unfirom noise to individual commodity costs.

# 2. Spread partitioning, randomized costs
spread_rand_costs_mc_data = s2mflow.generate_multi_commodity_data(
    instance=network,
    num_commodities=NUM_COMMODITIES,
    is_uniform=False,
    randomize_caps=False,
    randomize_costs=True,
    cost_a=0.5,
    cost_b=2.0,
    seed=42,
)
#--- Output file contents--
# c Multicommodity flow generated by s2mflow
# p min 4 5 4 0 1 0 42
# n 1 17 4 6 1 6
# n 4-17-4-6-1-6
# a 1 2 0 10 10 13 14 15 12
# a 1 3 0 15 15 3 6 9 9
# a 2 4 0 10 10 7 6 19 13
# a 3 2 0 5 5 22 15 26 17
# a 3 4 0 15 15 3 6 3 6

Strategy 4: Spread Partitioning with Randomized Capacities and Costs

This strategy generates high commodity-demand heterogeneity and simultaneously applies uniform noise to individual commodity capacities and arc costs.

spread_rand_caps_costs_mc_data = s2mflow.generate_multi_commodity_data(
    instance=network, num_commodities=4, is_uniform=False,
    randomize_caps=True, cap_a=0.6, cap_b=1.0,
    randomize_costs=True, cost_a=0.5, cost_b=2.0,
    seed=42,
)
s2mflow.save_multi_commodity_instance("spread_full.mcfmin", network, spread_rand_caps_costs_mc_data)

# --- Output File Contents (spread_full.mcfmin) ---
# c Multicommodity flow generated by s2mflow
# p min 4 5 4 1 1 0 42
# n 1 17 4 6 1 6
# n 4 -17 -4 -6 -1 -6
# a 1 2 0 10 9 8 8 10 13 15 6 17
# a 1 3 0 15 10 13 10 11 4 10 6 7
# a 2 4 0 10 9 9 8 7 6 6 18 13
# a 3 2 0 5 4 4 5 5 21 34 23 23
# a 3 4 0 15 15 11 12 12 8 6 6 3

(For demonstrations of isolated randomization configurations, see the examples/demo.py file).