org.nd4j.autodiff.graph.api.IGraph Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of samediff
There is a newer version: 0.9.1
package org.nd4j.autodiff.graph.api;

import org.nd4j.autodiff.graph.exception.NoEdgesException;

import java.util.List;
import java.util.Random;

/** Interface for a IGraph, with objects for each vertex and edge.
 * In the simplest case, edges and vertices may be labelled (i.e., IGraph for example), or may be
 * any arbitrary object (or, null).

 * IGraph may include directed edges, undirected edges, or a combination of both

 * Note: Every vertex in the graph has an integer index, in range of 0 to numVertices() inclusive

 * @param  type for vertex objects
 * @param  type for edge objects
 * @author Alex Black
 */
public interface IGraph {

    /** Number of vertices in the graph */
    int numVertices();

    /**Get a vertex in the graph for a given index
     * @param idx integer index of the vertex to get. must be in range 0 to numVertices()
     * @return vertex
     */
    Vertex getVertex(int idx);

    /** Get multiple vertices in the graph
     * @param indexes the indexes of the vertices to retrieve
     * @return list of vertices
     */
     List> getVertices(int[] indexes);

    /** Get multiple vertices in the graph, with secified indices
     * @param from first vertex to get, inclusive
     * @param to last vertex to get, inclusive
     * @return list of vertices
     */
    List> getVertices(int from, int to);

    /** Add an edge to the graph.
     */
    void addEdge(Edge edge);

    /** Convenience method for adding an edge (directed or undirected) to graph */
    void addEdge(int from, int to, E value, boolean directed);

    /** Returns a list of edges for a vertex with a given index
     * For undirected graphs, returns all edges incident on the vertex
     * For directed graphs, only returns outward directed edges
     * @param vertex index of the vertex to
     * @return list of edges for this vertex
     */
    List> getEdgesOut(int vertex);

    /** Returns the degree of the vertex.

     * For undirected graphs, this is just the degree.

     * For directed graphs, this returns the outdegree
     * @param vertex vertex to get degree for
     * @return vertex degree
     */
    int getVertexDegree(int vertex);

    /** Randomly sample a vertex connected to a given vertex. Sampling is done uniformly at random.
     * Specifically, returns a random X such that either a directed edge (vertex -> X) exists,
     * or an undirected edge (vertex -- X) exists

     * Can be used for example to implement a random walk on the graph (specifically: a unweighted random walk)
     * @param vertex vertex to randomly sample from
     * @param rng Random number generator to use
     * @return A vertex connected to the specified vertex,
     * @throws NoEdgesException thrown if the specified vertex has no edges, or no outgoing edges (in the case
     * of a directed graph).
     */
    Vertex getRandomConnectedVertex(int vertex, Random rng) throws NoEdgesException;

    /**Get a list of all of the vertices that the specified vertex is connected to

     * Specifically, for undirected graphs return list of all X such that (vertex -- X) exists

     * For directed graphs, return list of all X such that (vertex -> X) exists
     * @param vertex Index of the vertex
     * @return list of vertices that the specified vertex is connected to
     */
    List> getConnectedVertices(int vertex);

    /**Return an array of indexes of vertices that the specified vertex is connected to.

     * Specifically, for undirected graphs return int[] of all X.vertexID() such that (vertex -- X) exists

     * For directed graphs, return int[] of all X.vertexID() such that (vertex -> X) exists
     * @param vertex index of the vertex
     * @return list of vertices that the specified vertex is connected to
     * @see #getConnectedVertices(int)
     */
    int[] getConnectedVertexIndices(int vertex);
}