Merge remote-tracking branch 'origin/master' into add-vertices-class

Author: clue

src/Balance.php

@@ -0,0 +1,118 @@
+<?php
+
+namespace Fhaculty\Graph\Algorithm;
+
+use Fhaculty\Graph\Algorithm\BaseGraph;
+use Fhaculty\Graph\Edge\Base as Edge;
+use Fhaculty\Graph\Edge\Directed as EdgeDirected;
+use Fhaculty\Graph\Exception\UnexpectedValueException;
+use Fhaculty\Graph\Graph;
+use Fhaculty\Graph\Vertex;
+
+/**
+ * Basic algorithms for working with flow graphs
+ *
+ * A flow network (also known as a transportation network) is a directed graph
+ * where each edge has a capacity and each edge receives a flow.
+ *
+ * @link http://en.wikipedia.org/wiki/Flow_network
+ * @see Algorithm\Balance
+ */
+class Flow extends BaseSet
+{
+    /**
+     * check if this graph has any flow set (any edge has a non-NULL flow)
+     *
+     * @return boolean
+     * @uses Edge::getFlow()
+     */
+    public function hasFlow()
+    {
+        foreach ($this->set->getEdges() as $edge) {
+            if ($edge->getFlow() !== NULL) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Calculates the flow for this Vertex: sum(outflow) - sum(inflow)
+     *
+     * Usually, vertices should have a resulting flow of 0: The sum of flows
+     * entering a vertex must equal the sum of flows leaving a vertex. If the
+     * resulting flow is < 0, this vertex is considered a sink (i.e. there's
+     * more flow into this vertex). If the resulting flow is > 0, this vertex
+     * is considered a "source" (i.e. there's more flow leaving this vertex).
+     *
+     * @param Vertex $vertex
+     * @return float
+     * @throws UnexpectedValueException if they are undirected edges
+     * @see Vertex::getBalance()
+     * @uses Vertex::getEdges()
+     * @uses Edge::getFlow()
+     */
+    public function getFlowVertex(Vertex $vertex)
+    {
+        $sumOfFlow = 0;
+
+        foreach ($vertex->getEdges() as $edge) {
+            if (!($edge instanceof EdgeDirected)) {
+                throw new UnexpectedValueException("TODO: undirected edges not suported yet");
+            }
+
+            // edge is an outgoing edge of this vertex
+            if ($edge->hasVertexStart($vertex)) {
+                // flowing out (flow is "pointing away")
+                $sumOfFlow += $edge->getFlow();
+                // this is an ingoing edge
+            } else {
+                // flowing in
+                $sumOfFlow -= $edge->getFlow();
+            }
+        }
+
+        return $sumOfFlow;
+    }
+
+    public function getBalance()
+    {
+        $balance = 0;
+        // Sum for all vertices of value
+        foreach ($this->set->getVertices() as $vertex) {
+            $balance += $vertex->getBalance();
+        }
+
+        return $balance;
+    }
+
+    /**
+     * check if the current flow is balanced (aka "balanced flow" or "b-flow")
+     *
+     * a flow is considered balanced if each edge's current flow does not exceed its
+     * maximum capacity (which is always guaranteed due to the implementation
+     * of Edge::setFlow()) and each vertices' flow (i.e. outflow-inflow) equals
+     * its balance.
+     *
+     * checking whether the FLOW is balanced is not to be confused with checking
+     * whether the GRAPH is balanced (see Graph::isBalanced() instead)
+     *
+     * @return boolean
+     * @see Algorithm\Degree::isBalanced() if you merely want to check indegree=outdegree
+     * @uses self::getFlowVertex()
+     * @uses Vertex::getBalance()
+     */
+    public function isBalancedFlow()
+    {
+        // no need to check for each edge: flow <= capacity (setters already check that)
+        // check for each vertex: outflow-inflow = balance
+        foreach ($this->set->getVertices() as $vertex) {
+            if ($this->getFlowVertex($vertex) !== $vertex->getBalance()) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+}

src/Flow.php

@@ -19,7 +19,6 @@
 class SuccessiveShortestPath extends Base
 {
     /**
-     * @uses Vertex::getFlow()
      * @uses Graph::createGraphClone()
      * @uses AlgorithmResidualGraph::createGraph()
      * @uses AlgorithmSpMooreBellmanFord::getEdgesTo(Vertex $targetVertex)

src/MinimumCostFlow/SuccessiveShortestPath.php

@@ -0,0 +1,88 @@
+<?php
+
+namespace Fhaculty\Graph\Algorithm\Tree;
+
+use Fhaculty\Graph\Algorithm\BaseGraph;
+use Fhaculty\Graph\Graph;
+use Fhaculty\Graph\Vertex;
+use Fhaculty\Graph\Exception\UnderflowException;
+use Fhaculty\Graph\Exception\UnexpectedValueException;
+use Fhaculty\Graph\Algorithm\Search\StrictDepthFirst;
+
+/**
+ * Abstract base class for tree algorithms
+ *
+ * This abstract base class provides the base interface for working with
+ * graphs that represent a tree.
+ *
+ * A tree is a connected Graph (single component) with no cycles. Every Tree is
+ * a Graph, but not every Graph is a Tree.
+ *
+ *    A
+ *   / \
+ *  B   C
+ *     / \
+ *    D   E
+ *
+ * Special cases are undirected trees (like the one pictured above), handled via
+ * Tree\Undirected and directed, rooted trees (InTree and OutTree), handled via
+ * Tree\BaseDirected.
+ *
+ * @link http://en.wikipedia.org/wiki/Tree_%28graph_theory%29
+ * @link http://en.wikipedia.org/wiki/Tree_%28data_structure%29
+ * @see Undirected for an implementation of these algorithms on (undirected) trees
+ * @see BaseDirected for an abstract implementation of these algorithms on directed, rooted trees
+ */
+abstract class Base extends BaseGraph
+{
+    /**
+     * checks whether the given graph is actually a tree
+     *
+     * @return boolean
+     */
+    abstract public function isTree();
+
+    /**
+     * checks if the given $vertex is a leaf (outermost vertext)
+     *
+     * leaf vertex is also known as leaf node, external node or terminal node
+     *
+     * @param Vertex $vertex
+     * @return boolean
+     */
+    abstract public function isVertexLeaf(Vertex $vertex);
+
+    /**
+     * checks if the given $vertex is an internal vertex (somewhere in the "middle" of the tree)
+     *
+     * internal vertex is also known as inner node (inode) or branch node
+     *
+     * @param Vertex $vertex
+     * @return boolean
+     */
+    abstract public function isVertexInternal(Vertex $vertex);
+
+    /**
+     * get array of leaf vertices (outermost vertices with no children)
+     *
+     * @return Vertex[]
+     * @uses Graph::getVertices()
+     * @uses self::isVertexLeaf()
+     */
+    public function getVerticesLeaf()
+    {
+        return array_filter($this->graph->getVertices(), array($this, 'isVertexLeaf'));
+    }
+
+    /**
+     * get array of internal vertices
+     *
+     * @return Vertex[]
+     * @uses Graph::getVertices()
+     * @uses self::isVertexInternal()
+     */
+    public function getVerticesInternal()
+    {
+        return array_filter($this->graph->getVertices(), array($this, 'isVertexInternal'));
+    }
+}