org.jgrapht.alg.flow.mincost.MinimumCostFlowProblem Maven / Gradle / Ivy
/*
* (C) Copyright 2018-2023, by Timofey Chudakov and Contributors.
*
* JGraphT : a free Java graph-theory library
*
* See the CONTRIBUTORS.md file distributed with this work for additional
* information regarding copyright ownership.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License 2.0 which is available at
* http://www.eclipse.org/legal/epl-2.0, or the
* GNU Lesser General Public License v2.1 or later
* which is available at
* http://www.gnu.org/licenses/old-licenses/lgpl-2.1-standalone.html.
*
* SPDX-License-Identifier: EPL-2.0 OR LGPL-2.1-or-later
*/
package org.jgrapht.alg.flow.mincost;
import org.jgrapht.*;
import org.jgrapht.alg.interfaces.*;
import java.util.*;
import java.util.function.*;
/**
* This class represents a
* minimum cost flow problem. It serves as input for the minimum cost flow algorithms.
*
* The minimum cost flow problem is defined as follows: \[ \begin{align} \mbox{minimize}~&
* \sum_{e\in \delta^+(s)}c_e\cdot f_e &\\ \mbox{s.t. }&\sum_{e\in \delta^-(i)} f_e -
* \sum_{e\in \delta^+(i)} f_e = b_e & \forall i\in V\\ &l_e\leq f_e \leq u_e & \forall
* e\in E \end{align} \] Here $\delta^+(i)$ and $\delta^-(i)$ denote the outgoing and incoming edges
* of vertex $i$ respectively. The parameters $c_{e}$ define a cost for each unit of flow on the arc
* $e$, $l_{e}$ define minimum arc flow and $u_{e}$ define maximum arc flow.
*
* @param the graph vertex type
* @param the graph edge type
* @author Timofey Chudakov
* @see MinimumCostFlowAlgorithm
*/
public interface MinimumCostFlowProblem
{
/**
* Returns the flow network
*
* @return the flow network
*/
Graph getGraph();
/**
* Returns a function which defines the supply and demand of each node in that network. Supplies
* can be positive, negative or 0. Nodes with positive negative supply are the demand nodes,
* nodes with zero supply are the transhipment nodes. Flow is always directed from nodes with
* positive supply to nodes with negative supply. Summed over all nodes, the total demand should
* equal 0.
*
* @return supply function
*/
Function getNodeSupply();
/**
* Returns a function which specifies the minimum capacity of an arc. The minimum capacity is
* the minimum amount of flow that has to go through an arc.
*
* @return arc capacity lower bounding function
*/
Function getArcCapacityLowerBounds();
/**
* Returns a function which specifies the maximum capacity of an arc. The flow through an arc
* cannot exceed this upper bound.
*
* @return arc capacity upper bounding function
*/
Function getArcCapacityUpperBounds();
/**
* Returns a function which specifies the network arc costs. Every unit of flow through an arc
* will have the price of the cost of this arc.
*
* @return arc cost function
*/
Function getArcCosts();
/**
* Default implementation of a Minimum Cost Flow Problem
*
* @param the graph vertex type
* @param the graph edge type
*/
class MinimumCostFlowProblemImpl
implements MinimumCostFlowProblem
{
private final Graph graph;
private final Function nodeSupplies;
private final Function arcCapacityLowerBounds;
private final Function arcCapacityUpperBounds;
private final Function arcCosts;
/**
* Constructs a new minimum cost flow problem without arc capacity lower bounds.
*
* @param graph the flow network
* @param supplyMap the node demands
* @param arcCapacityUpperBounds the arc capacity upper bounds
*/
public MinimumCostFlowProblemImpl(
Graph graph, Function supplyMap,
Function arcCapacityUpperBounds)
{
this(graph, supplyMap, arcCapacityUpperBounds, a -> 0);
}
/**
* Constructs a new minimum cost flow problem
*
* @param graph the flow network
* @param nodeSupplies the node demands
* @param arcCapacityUpperBounds the arc capacity upper bounds
* @param arcCapacityLowerBounds the arc capacity lower bounds
*/
public MinimumCostFlowProblemImpl(
Graph graph, Function nodeSupplies,
Function arcCapacityUpperBounds,
Function arcCapacityLowerBounds)
{
this(
graph, nodeSupplies, arcCapacityUpperBounds, arcCapacityLowerBounds,
graph::getEdgeWeight);
}
/**
* Constructs a new minimum cost flow problem
*
* @param graph the flow network
* @param nodeSupplies the node demands
* @param arcCapacityUpperBounds the arc capacity upper bounds
* @param arcCapacityLowerBounds the arc capacity lower bounds
* @param arcCosts the arc costs
*/
public MinimumCostFlowProblemImpl(
Graph graph, Function nodeSupplies,
Function arcCapacityUpperBounds,
Function arcCapacityLowerBounds, Function arcCosts)
{
this.graph = Objects.requireNonNull(graph);
this.nodeSupplies = Objects.requireNonNull(nodeSupplies);
this.arcCapacityUpperBounds = Objects.requireNonNull(arcCapacityUpperBounds);
this.arcCapacityLowerBounds = Objects.requireNonNull(arcCapacityLowerBounds);
this.arcCosts = Objects.requireNonNull(arcCosts);
}
/**
* {@inheritDoc}
*/
@Override
public Graph getGraph()
{
return graph;
}
/**
* {@inheritDoc}
*/
@Override
public Function getNodeSupply()
{
return nodeSupplies;
}
/**
* {@inheritDoc}
*/
@Override
public Function getArcCapacityLowerBounds()
{
return arcCapacityLowerBounds;
}
/**
* {@inheritDoc}
*/
@Override
public Function getArcCapacityUpperBounds()
{
return arcCapacityUpperBounds;
}
/**
* {@inheritDoc}
*/
@Override
public Function getArcCosts()
{
return arcCosts;
}
}
}