# 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)
```python
# 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.

```python
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.

```python
# 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.

```python
# 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.

```python
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).