[hotfix] [gelly] Improve graph generator documentation
Project: http://git-wip-us.apache.org/repos/asf/flink/repo Commit: http://git-wip-us.apache.org/repos/asf/flink/commit/9c1b90af Tree: http://git-wip-us.apache.org/repos/asf/flink/tree/9c1b90af Diff: http://git-wip-us.apache.org/repos/asf/flink/diff/9c1b90af Branch: refs/heads/release-1.3 Commit: 9c1b90af0e8081db028f44cbf03e229a3792d6c2 Parents: ee8e454 Author: Greg Hogan <[email protected]> Authored: Mon May 8 12:45:19 2017 -0400 Committer: Greg Hogan <[email protected]> Committed: Thu May 11 12:44:14 2017 -0400 ---------------------------------------------------------------------- docs/dev/libs/gelly/graph_generators.md | 18 +++++++++++------- .../flink/graph/generator/CompleteGraph.java | 2 +- .../apache/flink/graph/generator/CycleGraph.java | 6 ++++-- .../apache/flink/graph/generator/EmptyGraph.java | 2 +- .../apache/flink/graph/generator/GridGraph.java | 5 +++-- .../flink/graph/generator/HypercubeGraph.java | 6 ++++-- .../apache/flink/graph/generator/PathGraph.java | 9 +++++++-- .../apache/flink/graph/generator/RMatGraph.java | 6 +++--- .../flink/graph/generator/SingletonEdgeGraph.java | 7 ++++--- .../apache/flink/graph/generator/StarGraph.java | 6 ++++-- 10 files changed, 42 insertions(+), 25 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/flink/blob/9c1b90af/docs/dev/libs/gelly/graph_generators.md ---------------------------------------------------------------------- diff --git a/docs/dev/libs/gelly/graph_generators.md b/docs/dev/libs/gelly/graph_generators.md index 5598d83..2532ee4 100644 --- a/docs/dev/libs/gelly/graph_generators.md +++ b/docs/dev/libs/gelly/graph_generators.md @@ -48,7 +48,7 @@ boolean wrapEndpoints = false; int parallelism = 4; -Graph<LongValue,NullValue,NullValue> graph = new GridGraph(env) +Graph<LongValue, NullValue, NullValue> graph = new GridGraph(env) .addDimension(2, wrapEndpoints) .addDimension(4, wrapEndpoints) .setParallelism(parallelism) @@ -138,7 +138,8 @@ val graph = new CompleteGraph(env.getJavaEnv, vertexCount).generate() ## Cycle Graph -An undirected graph where all edges form a single cycle. +An undirected graph where the set of edges form a single cycle by connecting +each vertex to two adjacent vertices in a chained loop. <div class="codetabs" markdown="1"> <div data-lang="java" markdown="1"> @@ -194,7 +195,7 @@ val graph = new CycleGraph(env.getJavaEnv, vertexCount).generate() ## Empty Graph -The graph containing no edges. +A graph containing no edges. <div class="codetabs" markdown="1"> <div data-lang="java" markdown="1"> @@ -316,7 +317,7 @@ val graph = new GridGraph(env.getJavaEnv).addDimension(2, wrapEndpoints).addDime ## Hypercube Graph -An undirected graph where edges form an n-dimensional hypercube. Each vertex +An undirected graph where edges form an `n`-dimensional hypercube. Each vertex in a hypercube connects to one other vertex in each dimension. <div class="codetabs" markdown="1"> @@ -391,7 +392,9 @@ val graph = new HypercubeGraph(env.getJavaEnv, dimensions).generate() ## Path Graph -An undirected Graph where all edges form a single path. +An undirected graph where the set of edges form a single path by connecting +two `endpoint` vertices with degree `1` and all midpoint vertices with degree +`2`. A path graph can be formed by removing a single edge from a cycle graph. <div class="codetabs" markdown="1"> <div data-lang="java" markdown="1"> @@ -443,7 +446,7 @@ val graph = new PathGraph(env.getJavaEnv, vertexCount).generate() ## RMat Graph -A directed or undirected power-law graph generated using the +A directed power-law multigraph generated using the [Recursive Matrix (R-Mat)](http://www.cs.cmu.edu/~christos/PUBLICATIONS/siam04.pdf) model. RMat is a stochastic generator configured with a source of randomness implementing the @@ -528,7 +531,8 @@ val graph = new RMatGraph(env.getJavaEnv, rnd, vertexCount, edgeCount).setConsta ## Singleton Edge Graph -An undirected graph containing isolated two-paths. +An undirected graph containing isolated two-paths where every vertex has degree +`1`. <div class="codetabs" markdown="1"> <div data-lang="java" markdown="1"> http://git-wip-us.apache.org/repos/asf/flink/blob/9c1b90af/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/CompleteGraph.java ---------------------------------------------------------------------- diff --git a/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/CompleteGraph.java b/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/CompleteGraph.java index 84cb791..11c0bb0 100644 --- a/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/CompleteGraph.java +++ b/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/CompleteGraph.java @@ -31,7 +31,7 @@ import org.apache.flink.util.Collector; import org.apache.flink.util.LongValueSequenceIterator; import org.apache.flink.util.Preconditions; -/* +/** * @see <a href="http://mathworld.wolfram.com/CompleteGraph.html";>Complete Graph at Wolfram MathWorld</a> */ public class CompleteGraph http://git-wip-us.apache.org/repos/asf/flink/blob/9c1b90af/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/CycleGraph.java ---------------------------------------------------------------------- diff --git a/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/CycleGraph.java b/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/CycleGraph.java index b04d78c..2386fe8 100644 --- a/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/CycleGraph.java +++ b/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/CycleGraph.java @@ -24,7 +24,7 @@ import org.apache.flink.types.LongValue; import org.apache.flink.types.NullValue; import org.apache.flink.util.Preconditions; -/* +/** * @see <a href="http://mathworld.wolfram.com/CycleGraph.html";>Cycle Graph at Wolfram MathWorld</a> */ public class CycleGraph @@ -39,7 +39,9 @@ extends AbstractGraphGenerator<LongValue, NullValue, NullValue> { private long vertexCount; /** - * An undirected {@link Graph} where all edges form a single cycle. + * An undirected {@link Graph} with {@code n} vertices where each vertex + * v<sub>i</sub> is connected to adjacent vertices v<sub>(i+1)%n</sub> and + * v<sub>(i-1)%n</sub>. * * @param env the Flink execution environment * @param vertexCount number of vertices http://git-wip-us.apache.org/repos/asf/flink/blob/9c1b90af/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/EmptyGraph.java ---------------------------------------------------------------------- diff --git a/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/EmptyGraph.java b/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/EmptyGraph.java index 25584ea..23e3a9c 100644 --- a/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/EmptyGraph.java +++ b/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/EmptyGraph.java @@ -33,7 +33,7 @@ import org.apache.flink.util.Preconditions; import java.util.Collections; -/* +/** * @see <a href="http://mathworld.wolfram.com/EmptyGraph.html";>Empty Graph at Wolfram MathWorld</a> */ public class EmptyGraph http://git-wip-us.apache.org/repos/asf/flink/blob/9c1b90af/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/GridGraph.java ---------------------------------------------------------------------- diff --git a/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/GridGraph.java b/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/GridGraph.java index 16a9ab9..23a6f98 100644 --- a/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/GridGraph.java +++ b/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/GridGraph.java @@ -35,7 +35,7 @@ import org.apache.flink.util.Preconditions; import java.util.ArrayList; import java.util.List; -/* +/** * @see <a href="http://mathworld.wolfram.com/GridGraph.html";>Grid Graph at Wolfram MathWorld</a> */ public class GridGraph @@ -50,7 +50,8 @@ extends AbstractGraphGenerator<LongValue, NullValue, NullValue> { private long vertexCount = 1; /** - * An undirected {@link Graph} connecting vertices in a regular tiling in one or more dimensions. + * An undirected {@code Graph} connecting vertices in a regular tiling in + * one or more dimensions and where the endpoints are optionally connected. * * @param env the Flink execution environment */ http://git-wip-us.apache.org/repos/asf/flink/blob/9c1b90af/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/HypercubeGraph.java ---------------------------------------------------------------------- diff --git a/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/HypercubeGraph.java b/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/HypercubeGraph.java index 37590ff..e4eac69 100644 --- a/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/HypercubeGraph.java +++ b/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/HypercubeGraph.java @@ -24,7 +24,7 @@ import org.apache.flink.types.LongValue; import org.apache.flink.types.NullValue; import org.apache.flink.util.Preconditions; -/* +/** * @see <a href="http://mathworld.wolfram.com/HypercubeGraph.html";>Hypercube Graph at Wolfram MathWorld</a> */ public class HypercubeGraph @@ -39,7 +39,9 @@ extends AbstractGraphGenerator<LongValue, NullValue, NullValue> { private long dimensions; /** - * An undirected {@link Graph} where edges form an n-dimensional hypercube. + * An undirected {@code Graph} where edges form an n-dimensional hypercube. + * Each vertex in a hypercube connects to one other vertex in each + * dimension. * * @param env the Flink execution environment * @param dimensions number of dimensions http://git-wip-us.apache.org/repos/asf/flink/blob/9c1b90af/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/PathGraph.java ---------------------------------------------------------------------- diff --git a/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/PathGraph.java b/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/PathGraph.java index dcc4c98..5c4343b 100644 --- a/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/PathGraph.java +++ b/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/PathGraph.java @@ -24,7 +24,7 @@ import org.apache.flink.types.LongValue; import org.apache.flink.types.NullValue; import org.apache.flink.util.Preconditions; -/* +/** * @see <a href="http://mathworld.wolfram.com/PathGraph.html";>Path Graph at Wolfram MathWorld</a> */ public class PathGraph @@ -39,7 +39,12 @@ extends AbstractGraphGenerator<LongValue, NullValue, NullValue> { private long vertexCount; /** - * An undirected {@link Graph} where all edges form a single path. + * An undirected {@link Graph} with {@code n} vertices where each vertex + * v<sub>i</sub> connects to adjacent vertices v<sub>i+1</sub> when + * {@code i < n-1} and v<sub>i-1</sub> when {@code i > 0}. + * <p> + * A {@code PathGraph} is distinguished from a {@code CycleGraph} in that + * the first and last vertex are not connected, breaking the cycle. * * @param env the Flink execution environment * @param vertexCount number of vertices http://git-wip-us.apache.org/repos/asf/flink/blob/9c1b90af/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/RMatGraph.java ---------------------------------------------------------------------- diff --git a/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/RMatGraph.java b/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/RMatGraph.java index 0fa4127..071b415 100644 --- a/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/RMatGraph.java +++ b/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/RMatGraph.java @@ -34,7 +34,7 @@ import org.apache.flink.util.Preconditions; import java.util.List; -/* +/** * @see <a href="http://www.cs.cmu.edu/~christos/PUBLICATIONS/siam04.pdf";>R-MAT: A Recursive Model for Graph Mining</a> */ public class RMatGraph<T extends RandomGenerator> @@ -75,8 +75,8 @@ extends AbstractGraphGenerator<LongValue, NullValue, NullValue> { public float noise = DEFAULT_NOISE; /** - * Generate a directed or undirected power-law {@link Graph} using the - * Recursive Matrix (R-Mat) model. + * A directed power-law multi{@link Graph graph} generated using the + * stochastic Recursive Matrix (R-Mat) model. * * @param env the Flink execution environment * @param randomGeneratorFactory source of randomness http://git-wip-us.apache.org/repos/asf/flink/blob/9c1b90af/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/SingletonEdgeGraph.java ---------------------------------------------------------------------- diff --git a/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/SingletonEdgeGraph.java b/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/SingletonEdgeGraph.java index f3c087e..125501c 100644 --- a/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/SingletonEdgeGraph.java +++ b/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/SingletonEdgeGraph.java @@ -31,8 +31,7 @@ import org.apache.flink.util.LongValueSequenceIterator; import org.apache.flink.util.Preconditions; /** - * A singleton-edge {@link Graph} contains one or more isolated two-paths. The in- and out-degree - * of every vertex is 1. For {@code n} vertices there are {@code n/2} components. + * A singleton-edge {@link Graph} contains one or more isolated two-paths. */ public class SingletonEdgeGraph extends AbstractGraphGenerator<LongValue, NullValue, NullValue> { @@ -46,7 +45,9 @@ extends AbstractGraphGenerator<LongValue, NullValue, NullValue> { private long vertexPairCount; /** - * An undirected {@link Graph} containing isolated two-paths. + * An undirected {@link Graph} containing one or more isolated two-paths. + * The in- and out-degree of every vertex is 1. For {@code n} vertices + * there are {@code n/2} components. * * @param env the Flink execution environment * @param vertexPairCount number of pairs of vertices http://git-wip-us.apache.org/repos/asf/flink/blob/9c1b90af/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/StarGraph.java ---------------------------------------------------------------------- diff --git a/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/StarGraph.java b/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/StarGraph.java index 316d749..f0f4e5a 100644 --- a/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/StarGraph.java +++ b/flink-libraries/flink-gelly/src/main/java/org/apache/flink/graph/generator/StarGraph.java @@ -31,7 +31,7 @@ import org.apache.flink.util.Collector; import org.apache.flink.util.LongValueSequenceIterator; import org.apache.flink.util.Preconditions; -/* +/** * @see <a href="http://mathworld.wolfram.com/StarGraph.html";>Star Graph at Wolfram MathWorld</a> */ public class StarGraph @@ -46,7 +46,9 @@ extends AbstractGraphGenerator<LongValue, NullValue, NullValue> { private long vertexCount; /** - * An undirected {@link Graph} containing a single central {@link Vertex} connected to all other leaf vertices. + * An undirected {@Graph} with {@code n} vertices where the single central + * node has degree {@code n-1}, connecting to the other {@code n-1} + * vertices which have degree {@code 1}. * * @param env the Flink execution environment * @param vertexCount number of vertices
