s2mflow: Multicommodity Flow Instance Generator

Welcome to the official documentation for s2mflow. This library provides a high-performance tool for generating multicommodity flow instances from single-commodity flow instances.

Introduction

s2mflow bridges the gap between theoretical multicommodity flow research and practical optimization by providing a robust generator implemented in Rust with a seamless Python interface via PyO3.

API Reference

This section is automatically generated from the source code docstrings.

class s2mflow.Edge

Bases: object

cost
head
low
tail
up
class s2mflow.MultiCommodityData

Bases: object

capacites_by_arc
capacities
edges
is_uniform
num_commodities
randomized_capacities
randomized_weights
seed
supply_partition
weight
weights_by_arc
class s2mflow.MultiCommoditySupplies

Bases: object

partition
class s2mflow.NetworkInstance

Bases: object

arcs
capacities
edges
nodes
num_arcs
num_nodes
supplies
weights
class s2mflow.ParsedMulticommodityInstance

Bases: object

capacities
commodity_bundle_capacities
commodity_capacities
commodity_edges
commodity_supply_demand_data
commodity_weights
edges
end_nodes
is_uniform
nodes
num_arcs
num_commodities
num_nodes
randomized_capacities
randomized_weights
seed
start_nodes
s2mflow.generate_multi_commodity_data(instance, num_commodities, is_uniform, randomize_caps=False, cap_a=0.8, cap_b=1.2, randomize_costs=False, cost_a=0.8, cost_b=1.2, seed=42)

Generates a full multi-commodity dataset from a single-commodity instance.

This function handles the partitioning of supplies and the optional randomization of arc capacities and costs across commodities.

Parameters:

  • instance (NetworkInstance) – The base single-commodity network.

  • num_commodities (int) – The number of commodities.

  • is_uniform (bool) – If Ture, uses uniform partitioning; otherwise, uses spread.

  • randomize_caps (bool, optional) – If True, varies capacities per commodity. Default to False.

  • cap_a (float, optional) – Lower multiplier for capacity randomization. Defaults to 0.8.

  • cap_b (float, optional) – Upper multiplier for capacity randomization. Defaults to 1.2.

  • randomize_costs (bool, optional) – If True, varies costs per commodity. Defaults to False.

  • cost_a (float, optional) – Lower multiplier for cost randomization. Defaults to 0.8.

  • cost_b (float, optional) – Upper multiplier for cost randomization. defaults to 1.2.

  • seed (int, optional) – Seed.

Returns:

The generated multi-commodity data.

Return type:

MultiCommodityData

s2mflow.get_incidence_mapping(nodes, edges)

Creates indidence mapping from nodes and edges.

Parameters:

  • nodes (List[int]) – List of node IDs.

  • edges (List[int, int]) – List of edges.

Returns:

Incoming and outgoing.

Return type:

Tuple[Dict[int, List[int]], Dict[int, List[int]]]

s2mflow.load_min_instance(path)

Loads a single-commodity network instance from a DIMACS .min file.

Parameters:

path (str) – The filesystem path to the .min file.

Returns:

An object containing information on the min-cost flow instance.

Return type:

NetworkInstance

Raises:

IOError – If the file cannot be read or the format is invalid.

s2mflow.load_multi_commodity_instance(path)

Loads and parses a multi-commodity DIMACS file into a multicommodity-instance.

This function reads the specialized DIMACS format generated by this package. It reconstructs the multicommodity instance.

Parameters:

path (str) – The filesystem path to the multi-commodity .min file.

Returns:

An object containing multi-commodity data.

Return type:

ParsedMulticommodityInstance

Raises:

  • RuntimeError – If the file header is inconsistent or the arc data is malformed.

  • IOError – If the file cannot be accessed.

s2mflow.save_multi_commodity_instance(path, instance, multi_data)

Exports a multi-commodity instance to a DIMACS-formatted file.

Uses a specialized hybrid format that compresses non-randomized arc data while allowing expanded per-commodity values when necessary.

Parameters:
s2mflow.split_supplies_spread(data, num_k, seed)

Partitions nodal supply/demand into K commodities using a spread distribution.

Parameters:

  • data (Dict[int, int]) – A mapping of node IDs to their total supply/demand.

  • num_k (int) – The number of commodities.

  • seed (int) – Seed.

Returns:

A mapping where each node ID points to a list of the commodity supplies/demands.

Return type:

Dict[int, List[int]]

s2mflow.split_supplies_uniform(data, num_k)

Partitions nodal supply/demand into K commodities using a uniform distribution.

Parameters:

  • data (Dict[int, int]) – A mapping of node IDs to their total supply/demand.

  • num_k (int) – The number of commodities.

Returns:

A mapping where each node ID points to a list of the commodity supplies/demands

Return type:

Dict[int, List[int]]

Indices and tables