API Reference

This section is automatically generated from the source code docstrings.

Classes

class s2mflow.Edge

Bases: object

Represents a single directed arc within the network.

tail

The source node ID of the edge.

Type:: int

head

The destination node ID of the edge.

Type:: int

low

The lower bound of flow permitted on the edge.

Type:: int

up

The upper bound (capacity) of flow permitted on the edge.

Type:: int

cost

The objective weight or routing cost per unit of flow.

Type:: int

class s2mflow.NetworkInstance

Bases: object

A parsed single-commodity network instance loaded from a DIMACS .min file.

num_nodes

Total number of nodes in the network.

Type:: int

num_arcs

Total number of directed edges in the network.

Type:: int

nodes

A list of all node IDs.

Type:: List[int]

edges

A list of Edge objects containing the full topology and parameters.

Type:: List[Edge]

supplies

A mapping of node IDs to their supply (positive) or demand (negative) values.

Type:: Dict[int, int]

arcs

A list of (tail, head) tuples representing the network topology.

Type:: List[Tuple[int, int]]

capacities

An ordered list of total capacities corresponding to the arcs list.

Type:: List[int]

weights

An ordered list of routing costs corresponding to the arcs list.

Type:: List[int]

class s2mflow.MultiCommoditySupplies

Bases: object

Contains the partitioned supply/demand data across multiple commodities.

partition

A mapping of node IDs to a list of supply/demand values, indexed by commodity.

Type:: Dict[int, List[int]]

class s2mflow.MultiCommodityData

Bases: object

The generated multicommodity data structure, lifting the base network into K-commodity space.

supply_partition

Nodal supply/demand mapped to a list of values for each commodity K.

Type:: Dict[int, List[int]]

is_uniform

Flag indicating if uniform partitioning was used (True) or spread partitioning (False).

Type:: bool

commodity_edges

A list of (commodity_id, tail, head) tuples for commodity-wise edges.

Type:: List[Tuple[int, int, int]]

capacities

The shared, mutual capacities for each edge.

Type:: List[int]

weight

A matrix of routing costs.

Type:: List[List[int]]

weights_by_arc

A mapping of edge indices to a list of commodity-specific costs.

Type:: Dict[int, List[int]]

capacities_by_arc

A mapping of edge indices to a list of commodity-specific capacities.

Type:: Dict[int, List[int]]

commodity_capacities

A mapping of (tail, head) tuples to a list of commodity-specific capacities.

Type:: Dict[Tuple[int, int], List[int]]

commodity_weights

A mapping of (tail, head) tuples to a list of commodity-specific costs.

Type:: Dict[Tuple[int, int], List[int]]

num_commodities

The total number of commodities generated (K).

Type:: int

randomized_capacities

Flag indicating if commodity-specific capacities were perturbed with uniform noise.

Type:: bool

randomized_weights

Flag indicating if commodity-specific routing costs were perturbed with uniform noise.

Type:: bool

seed

The random seed used for generating stochastic perturbations.

Type:: int

class s2mflow.ParsedMulticommodityInstance

Bases: object

An object containing multi-commodity data parsed directly from a serialized .mcfmin file.

num_nodes

Total number of nodes.

Type:: int

num_arcs

Total number of directed edges in the network.

Type:: int

num_commodities

Total number of commodities (K).

Type:: int

randomized_capacities

Flag indicating the presence of commodity-specific capacities.

Type:: bool

randomized_weights

Flag indicating the presence of commodity-specific routing costs.

Type:: bool

nodes

List of all node IDs.

Type:: List[int]

edges

List of baseline (tail, head) edges.

Type:: List[Tuple[int, int]]

supplies

Node IDs mapped to their total supply/demand.

Type:: Dict[int, int]

commodity_supply_demand_data

Node IDs mapped to their respective supply/demand arrays across commodities.

Type:: Dict[int, List[int]]

capacities

Shared mutual capacities of the dges.

Type:: List[int]

commodity_capacities

Commodity-specific capacities keyed by (tail, head).

Type:: Dict[Tuple[int, int], List[int]]

commodity_weights

Commodity-specific routing costs keyed by (tail, head).

Type:: Dict[Tuple[int, int], List[int]]

commodity_edges

A list of (commodity_id, tail, head) tuples for commodity-wise edge.

Type:: List[Tuple[int, int, int]]

start_nodes

List of source nodes containing positive supply.

Type:: List[int]

end_nodes

List of sink nodes containing negative supply (demand).

Type:: List[int]

is_uniform

Flag indicating if the instance was generated using uniform partitioning.

Type:: bool

seed

The random seed used during generation.

Type:: int

Functions

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.split_supplies_uniform(data, num_commodities)

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_commodities (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]]

s2mflow.split_supplies_spread(data, num_commodities, 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_commodities (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.generate_multi_commodity_data(instance, num_commodities, is_uniform, randomize_caps=False, cap_a=0.8, cap_b=1.0, 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 True, 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.0.
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.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:

path (str) – Export destination path.
instance (NetworkInstance) – The base network topology.
multi_data (MultiCommodityData) – The multi-commodity data.

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.get_adjacency_mapping(nodes, edges)

Creates adjacency 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]]]