Multiple Flows And Capacity
===========================

When several OD pairs are allocated, ``NetworkFlows`` aggregates their flows on
shared edges.

Capacity-constrained allocation limits assignments to available edge capacity
and records residual demand in ``unassigned_od``.

Shared edges
------------

The two OD pairs below both use edge ``BC`` on their least-cost path.

>>> import pandas as pd
>>> from transport_flow_model.model import Network, NetworkFlows, OD, ODFlows
>>> network = Network(
...     pd.DataFrame(
...         {
...             "edge_from": ["A", "B", "A", "C", "B"],
...             "edge_to": ["B", "C", "C", "D", "D"],
...             "edge_id": ["AB", "BC", "AC", "CD", "BD"],
...             "cost": [1, 2, 5, 1, 10],
...             "capacity": [100, 100, 100, 100, 100],
...         }
...     )
... )
>>> od = OD(
...     pd.DataFrame(
...         {
...             "origin_id": ["A", "B"],
...             "destination_id": ["C", "D"],
...             "flow": [10, 6],
...         }
...     )
... )
>>> result = network.allocate(od, directed=True)
>>> result.od_flows.to_dataframe().to_dict("records")
[{'origin_id': 'A', 'destination_id': 'C', 'flow': 10, 'edge_path': ['AB', 'BC'], 'cost': 3}, {'origin_id': 'B', 'destination_id': 'D', 'flow': 6, 'edge_path': ['BC', 'CD'], 'cost': 3}]
>>> result.network_flows.to_dataframe().set_index("edge_id")["flow"].to_dict()
{'AB': 10, 'BC': 16, 'AC': 0, 'CD': 6, 'BD': 0}

Fair bottleneck sharing
-----------------------

With capacity constraints enabled, flows that require the same bottleneck edge
share its available capacity proportionally. Here both OD pairs request ``10``
units through ``CD``, but ``CD`` only has capacity ``10``. Each pair receives
``5`` and leaves ``5`` unassigned.

>>> bottleneck_network = Network(
...     pd.DataFrame(
...         {
...             "edge_from": ["A", "B", "C"],
...             "edge_to": ["C", "C", "D"],
...             "edge_id": ["AC", "BC", "CD"],
...             "cost": [1, 1, 1],
...             "capacity": [100, 100, 10],
...         }
...     )
... )
>>> bottleneck_od = OD(
...     pd.DataFrame(
...         {
...             "origin_id": ["A", "B"],
...             "destination_id": ["D", "D"],
...             "flow": [10, 10],
...         }
...     )
... )
>>> constrained = bottleneck_network.allocate(
...     bottleneck_od, capacity_constrained=True, directed=True
... )
>>> constrained.od_flows.to_dataframe().sort_values(
...     ["origin_id", "destination_id"]
... ).to_dict("records")
[{'origin_id': 'A', 'destination_id': 'D', 'flow': 5, 'edge_path': ['AC', 'CD'], 'cost': 2}, {'origin_id': 'B', 'destination_id': 'D', 'flow': 5, 'edge_path': ['BC', 'CD'], 'cost': 2}]
>>> constrained.unassigned_od.to_dataframe().sort_values(
...     ["origin_id", "destination_id"]
... ).to_dict("records")
[{'origin_id': 'A', 'destination_id': 'D', 'flow': 5}, {'origin_id': 'B', 'destination_id': 'D', 'flow': 5}]
>>> constrained.network_flows.to_dataframe().set_index("edge_id")["flow"].to_dict()
{'AC': 5, 'BC': 5, 'CD': 10}

Existing edge loads
-------------------

If the network already has a ``flow`` column, capacity-constrained allocation
treats that flow as occupied capacity. Returned edge totals include both the
existing load and newly assigned OD flows.

>>> loaded_network = Network(
...     pd.DataFrame(
...         {
...             "edge_from": ["A"],
...             "edge_to": ["B"],
...             "edge_id": ["AB"],
...             "cost": [1],
...             "capacity": [10],
...             "flow": [8],
...         }
...     )
... )
>>> extra_od = OD(
...     pd.DataFrame(
...         {
...             "origin_id": ["A"],
...             "destination_id": ["B"],
...             "flow": [2],
...         }
...     )
... )
>>> loaded = loaded_network.allocate(
...     extra_od, capacity_constrained=True, directed=True
... )
>>> loaded.network_flows.to_dataframe().set_index("edge_id")["flow"].to_dict()
{'AB': 10}

The same additive behavior is available directly through
``NetworkFlows.from_network_and_od_flows``.

>>> od_flows = ODFlows(
...     pd.DataFrame(
...         {
...             "origin_id": ["A"],
...             "destination_id": ["B"],
...             "flow": [2],
...             "edge_path": [["AB"]],
...             "cost": [1],
...         }
...     )
... )
>>> NetworkFlows.from_network_and_od_flows(
...     loaded_network, od_flows
... ).to_dataframe().set_index("edge_id")["flow"].to_dict()
{'AB': 10}