Skip to content

GitLab

Unverified Commit 6c53f351 authored by Hongzhi (Steve), Chen's avatar Hongzhi (Steve), Chen Committed by GitHub
Browse files

Replace \xxx with @XXX in structured comment. (#4815) 



* replace

* more

* file

* change
Co-authored-by: default avatarSteve <ubuntu@ip-172-31-34-29.ap-northeast-1.compute.internal>
parent 33a2d9e1
Hide whitespace changes
Inline Side-by-side
Showing with 862 additions and 861 deletions
featgraph/include/featgraph.h
View file @ 6c53f351
/*!
* Copyright (c) 2020 by Contributors
* \file featgraph/include/featgraph.h
* \brief FeatGraph kernel headers.
* @file featgraph/include/featgraph.h
* @brief FeatGraph kernel headers.
*/
#ifndef FEATGRAPH_H_
#define FEATGRAPH_H_
......@@ -11,10 +11,10 @@
namespace dgl {
namespace featgraph {
/* \brief Load Featgraph module from given path. */
/* @brief Load Featgraph module from given path. */
void LoadFeatGraphModule(const std::string& path);
/* \brief Call Featgraph's SDDMM kernel. */
/* @brief Call Featgraph's SDDMM kernel. */
void SDDMMTreeReduction(
DLManagedTensor* row, DLManagedTensor* col, DLManagedTensor* lhs,
DLManagedTensor* rhs, DLManagedTensor* out);
......
featgraph/src/featgraph.cc
View file @ 6c53f351
/*!
* Copyright (c) 2020 by Contributors
* \file featgraph/src/featgraph.cc
* \brief FeatGraph kernels.
* @file featgraph/src/featgraph.cc
* @brief FeatGraph kernels.
*/
#include <dmlc/logging.h>
#include <featgraph.h>
......@@ -12,7 +12,7 @@
namespace dgl {
namespace featgraph {
/* \brief Singleton that loads the featgraph module. */
/* @brief Singleton that loads the featgraph module. */
class FeatGraphModule {
public:
static FeatGraphModule* Global() {
......@@ -38,12 +38,12 @@ class FeatGraphModule {
FeatGraphModule() {}
};
/* \brief Load Featgraph module from given path. */
/* @brief Load Featgraph module from given path. */
void LoadFeatGraphModule(const std::string& path) {
FeatGraphModule::Global()->Load(path);
}
/* \brief Convert DLDataType to string. */
/* @brief Convert DLDataType to string. */
inline std::string DTypeAsStr(const DLDataType& t) {
switch (t.code) {
case 0U:
......@@ -59,14 +59,14 @@ inline std::string DTypeAsStr(const DLDataType& t) {
}
}
/* \brief Get operator filename. */
/* @brief Get operator filename. */
inline std::string GetOperatorName(
const std::string& base_name, const DLDataType& dtype,
const DLDataType& idtype) {
return base_name + "_" + DTypeAsStr(dtype) + "_" + DTypeAsStr(idtype);
}
/* \brief Call FeatGraph's SDDMM kernel. */
/* @brief Call FeatGraph's SDDMM kernel. */
void SDDMMTreeReduction(
DLManagedTensor* row, DLManagedTensor* col, DLManagedTensor* lhs,
DLManagedTensor* rhs, DLManagedTensor* out) {
......
featgraph/src/tvm_runtime_pack.cc
View file @ 6c53f351
......@@ -22,7 +22,7 @@
*/
/*!
* \brief This is an all in one TVM runtime file.
* @brief This is an all in one TVM runtime file.
*
* You only have to use this file to compile libtvm_runtime to
* include in your project.
......
include/dgl/array.h
View file @ 6c53f351
/*!
* Copyright (c) 2020 by Contributors
* \file dgl/array.h
* \brief Common array operations required by DGL.
* @file dgl/array.h
* @brief Common array operations required by DGL.
*
* Note that this is not meant for a full support of array library such as ATen.
* Only a limited set of operators required by DGL are implemented.
......
include/dgl/array_iterator.h
View file @ 6c53f351
/*!
* Copyright (c) 2020 by Contributors
* \file dgl/array_iterator.h
* \brief Various iterators.
* @file dgl/array_iterator.h
* @brief Various iterators.
*/
#ifndef DGL_ARRAY_ITERATOR_H_
#define DGL_ARRAY_ITERATOR_H_
......
include/dgl/aten/spmat.h
View file @ 6c53f351
/*!
* Copyright (c) 2020 by Contributors
* \file dgl/aten/spmat.h
* \brief Sparse matrix definitions
* @file dgl/aten/spmat.h
* @brief Sparse matrix definitions
*/
#ifndef DGL_ATEN_SPMAT_H_
#define DGL_ATEN_SPMAT_H_
......@@ -15,7 +15,7 @@
namespace dgl {
/*!
* \brief Sparse format.
* @brief Sparse format.
*/
enum class SparseFormat {
kCOO = 1,
......@@ -24,7 +24,7 @@ enum class SparseFormat {
};
/*!
* \brief Sparse format codes
* @brief Sparse format codes
*/
const dgl_format_code_t ALL_CODE = 0x7;
const dgl_format_code_t ANY_CODE = 0x0;
......
include/dgl/aten/types.h
View file @ 6c53f351
/*!
* Copyright (c) 2020 by Contributors
* \file dgl/aten/types.h
* \brief Array and ID types
* @file dgl/aten/types.h
* @brief Array and ID types
*/
#ifndef DGL_ATEN_TYPES_H_
#define DGL_ATEN_TYPES_H_
......@@ -14,7 +14,7 @@ namespace dgl {
typedef uint64_t dgl_id_t;
typedef uint64_t dgl_type_t;
/*! \brief Type for dgl fomrat code, whose binary representation indices
/*! @brief Type for dgl fomrat code, whose binary representation indices
* which sparse format is in use and which is not.
*
* Suppose the binary representation is xyz, then
......
include/dgl/base_heterograph.h
View file @ 6c53f351
/*!
* Copyright (c) 2019 by Contributors
* \file dgl/heterograph_interface.h
* \brief DGL heterogeneous graph index class.
* @file dgl/heterograph_interface.h
* @brief DGL heterogeneous graph index class.
*/
#ifndef DGL_BASE_HETEROGRAPH_H_
......@@ -31,14 +31,14 @@ typedef std::shared_ptr<FlattenedHeteroGraph> FlattenedHeteroGraphPtr;
struct HeteroSubgraph;
/*! \brief Enum class for edge direction */
/*! @brief Enum class for edge direction */
enum class EdgeDir {
kIn, // in edge direction
kOut // out edge direction
};
/*!
* \brief Base heterogenous graph.
* @brief Base heterogenous graph.
*
* In heterograph, nodes represent entities and edges represent relations.
* Nodes and edges are associated with types. The same pair of entity types
......@@ -74,63 +74,63 @@ class BaseHeteroGraph : public runtime::Object {
virtual GraphPtr meta_graph() const { return meta_graph_; }
/*!
* \brief Return the bipartite graph of the given edge type.
* \param etype The edge type.
* \return The bipartite graph.
* @brief Return the bipartite graph of the given edge type.
* @param etype The edge type.
* @return The bipartite graph.
*/
virtual HeteroGraphPtr GetRelationGraph(dgl_type_t etype) const = 0;
///////////////////// query/operations on realized graph /////////////////////
/*! \brief Add vertices to the given vertex type */
/*! @brief Add vertices to the given vertex type */
virtual void AddVertices(dgl_type_t vtype, uint64_t num_vertices) = 0;
/*! \brief Add one edge to the given edge type */
/*! @brief Add one edge to the given edge type */
virtual void AddEdge(dgl_type_t etype, dgl_id_t src, dgl_id_t dst) = 0;
/*! \brief Add edges to the given edge type */
/*! @brief Add edges to the given edge type */
virtual void AddEdges(dgl_type_t etype, IdArray src_ids, IdArray dst_ids) = 0;
/*!
* \brief Clear the graph. Remove all vertices/edges.
* @brief Clear the graph. Remove all vertices/edges.
*/
virtual void Clear() = 0;
/*!
* \brief Get the data type of node and edge IDs of this graph.
* @brief Get the data type of node and edge IDs of this graph.
*/
virtual DGLDataType DataType() const = 0;
/*!
* \brief Get the device context of this graph.
* @brief Get the device context of this graph.
*/
virtual DGLContext Context() const = 0;
/*!
* \brief Pin graph.
* @brief Pin graph.
*/
virtual void PinMemory_() = 0;
/*!
* \brief Check if this graph is pinned.
* @brief Check if this graph is pinned.
*/
virtual bool IsPinned() const = 0;
/*!
* \brief Record stream for this graph.
* \param stream The stream that is using the graph
* @brief Record stream for this graph.
* @param stream The stream that is using the graph
*/
virtual void RecordStream(DGLStreamHandle stream) = 0;
/*!
* \brief Get the number of integer bits used to store node/edge ids (32 or
* @brief Get the number of integer bits used to store node/edge ids (32 or
* 64).
*/
// TODO(BarclayII) replace NumBits() calls to DataType() calls
virtual uint8_t NumBits() const = 0;
/*!
* \return whether the graph is a multigraph
* @return whether the graph is a multigraph
*/
virtual bool IsMultigraph() const = 0;
......@@ -166,28 +166,28 @@ class BaseHeteroGraph : public runtime::Object {
dgl_type_t etype, IdArray src_ids, IdArray dst_ids) const = 0;
/*!
* \brief Find the predecessors of a vertex.
* \note The given vertex should belong to the source vertex type
* @brief Find the predecessors of a vertex.
* @note The given vertex should belong to the source vertex type
* of the given edge type.
* \param etype The edge type
* \param vid The vertex id.
* \return the predecessor id array.
* @param etype The edge type
* @param vid The vertex id.
* @return the predecessor id array.
*/
virtual IdArray Predecessors(dgl_type_t etype, dgl_id_t dst) const = 0;
/*!
* \brief Find the successors of a vertex.
* \note The given vertex should belong to the dest vertex type
* @brief Find the successors of a vertex.
* @note The given vertex should belong to the dest vertex type
* of the given edge type.
* \param etype The edge type
* \param vid The vertex id.
* \return the successor id array.
* @param etype The edge type
* @param vid The vertex id.
* @return the successor id array.
*/
virtual IdArray Successors(dgl_type_t etype, dgl_id_t src) const = 0;
/*!
* \brief Get all edge ids between the two given endpoints
* \note The given src and dst vertices should belong to the source vertex
* @brief Get all edge ids between the two given endpoints
* @note The given src and dst vertices should belong to the source vertex
* type and the dest vertex type of the given edge type, respectively. \param
* etype The edge type \param src The source vertex. \param dst The
* destination vertex. \return the edge id array.
......@@ -196,93 +196,93 @@ class BaseHeteroGraph : public runtime::Object {
dgl_type_t etype, dgl_id_t src, dgl_id_t dst) const = 0;
/*!
* \brief Get all edge ids between the given endpoint pairs.
* @brief Get all edge ids between the given endpoint pairs.
*
* \param etype The edge type
* \param src The src vertex ids.
* \param dst The dst vertex ids.
* \return EdgeArray containing all edges between all pairs.
* @param etype The edge type
* @param src The src vertex ids.
* @param dst The dst vertex ids.
* @return EdgeArray containing all edges between all pairs.
*/
virtual EdgeArray EdgeIdsAll(
dgl_type_t etype, IdArray src, IdArray dst) const = 0;
/*!
* \brief Get edge ids between the given endpoint pairs.
* @brief Get edge ids between the given endpoint pairs.
*
* Only find one matched edge Ids even if there are multiple matches due to
* parallel edges. The i^th Id in the returned array is for edge (src[i],
* dst[i]).
*
* \param etype The edge type
* \param src The src vertex ids.
* \param dst The dst vertex ids.
* \return EdgeArray containing all edges between all pairs.
* @param etype The edge type
* @param src The src vertex ids.
* @param dst The dst vertex ids.
* @return EdgeArray containing all edges between all pairs.
*/
virtual IdArray EdgeIdsOne(
dgl_type_t etype, IdArray src, IdArray dst) const = 0;
/*!
* \brief Find the edge ID and return the pair of endpoints
* \param etype The edge type
* \param eid The edge ID
* \return a pair whose first element is the source and the second the
* @brief Find the edge ID and return the pair of endpoints
* @param etype The edge type
* @param eid The edge ID
* @return a pair whose first element is the source and the second the
* destination.
*/
virtual std::pair<dgl_id_t, dgl_id_t> FindEdge(
dgl_type_t etype, dgl_id_t eid) const = 0;
/*!
* \brief Find the edge IDs and return their source and target node IDs.
* \param etype The edge type
* \param eids The edge ID array.
* \return EdgeArray containing all edges with id in eid. The order is
* @brief Find the edge IDs and return their source and target node IDs.
* @param etype The edge type
* @param eids The edge ID array.
* @return EdgeArray containing all edges with id in eid. The order is
* preserved.
*/
virtual EdgeArray FindEdges(dgl_type_t etype, IdArray eids) const = 0;
/*!
* \brief Get the in edges of the vertex.
* \note The given vertex should belong to the dest vertex type
* @brief Get the in edges of the vertex.
* @note The given vertex should belong to the dest vertex type
* of the given edge type.
* \param etype The edge type
* \param vid The vertex id.
* \return the edges
* @param etype The edge type
* @param vid The vertex id.
* @return the edges
*/
virtual EdgeArray InEdges(dgl_type_t etype, dgl_id_t vid) const = 0;
/*!
* \brief Get the in edges of the vertices.
* \note The given vertex should belong to the dest vertex type
* @brief Get the in edges of the vertices.
* @note The given vertex should belong to the dest vertex type
* of the given edge type.
* \param etype The edge type
* \param vids The vertex id array.
* \return the id arrays of the two endpoints of the edges.
* @param etype The edge type
* @param vids The vertex id array.
* @return the id arrays of the two endpoints of the edges.
*/
virtual EdgeArray InEdges(dgl_type_t etype, IdArray vids) const = 0;
/*!
* \brief Get the out edges of the vertex.
* \note The given vertex should belong to the source vertex type
* @brief Get the out edges of the vertex.
* @note The given vertex should belong to the source vertex type
* of the given edge type.
* \param etype The edge type
* \param vid The vertex id.
* \return the id arrays of the two endpoints of the edges.
* @param etype The edge type
* @param vid The vertex id.
* @return the id arrays of the two endpoints of the edges.
*/
virtual EdgeArray OutEdges(dgl_type_t etype, dgl_id_t vid) const = 0;
/*!
* \brief Get the out edges of the vertices.
* \note The given vertex should belong to the source vertex type
* @brief Get the out edges of the vertices.
* @note The given vertex should belong to the source vertex type
* of the given edge type.
* \param etype The edge type
* \param vids The vertex id array.
* \return the id arrays of the two endpoints of the edges.
* @param etype The edge type
* @param vids The vertex id array.
* @return the id arrays of the two endpoints of the edges.
*/
virtual EdgeArray OutEdges(dgl_type_t etype, IdArray vids) const = 0;
/*!
* \brief Get all the edges in the graph.
* \note If order is "srcdst", the returned edges list is sorted by their src
* @brief Get all the edges in the graph.
* @note If order is "srcdst", the returned edges list is sorted by their src
* and dst ids. If order is "eid", they are in their edge id order. Otherwise,
* in the arbitrary order. \param etype The edge type \param order The order
* of the returned edge list. \return the id arrays of the two endpoints of
......@@ -292,83 +292,83 @@ class BaseHeteroGraph : public runtime::Object {
dgl_type_t etype, const std::string& order = "") const = 0;
/*!
* \brief Get the in degree of the given vertex.
* \note The given vertex should belong to the dest vertex type
* @brief Get the in degree of the given vertex.
* @note The given vertex should belong to the dest vertex type
* of the given edge type.
* \param etype The edge type
* \param vid The vertex id.
* \return the in degree
* @param etype The edge type
* @param vid The vertex id.
* @return the in degree
*/
virtual uint64_t InDegree(dgl_type_t etype, dgl_id_t vid) const = 0;
/*!
* \brief Get the in degrees of the given vertices.
* \note The given vertex should belong to the dest vertex type
* @brief Get the in degrees of the given vertices.
* @note The given vertex should belong to the dest vertex type
* of the given edge type.
* \param etype The edge type
* \param vid The vertex id array.
* \return the in degree array
* @param etype The edge type
* @param vid The vertex id array.
* @return the in degree array
*/
virtual DegreeArray InDegrees(dgl_type_t etype, IdArray vids) const = 0;
/*!
* \brief Get the out degree of the given vertex.
* \note The given vertex should belong to the source vertex type
* @brief Get the out degree of the given vertex.
* @note The given vertex should belong to the source vertex type
* of the given edge type.
* \param etype The edge type
* \param vid The vertex id.
* \return the out degree
* @param etype The edge type
* @param vid The vertex id.
* @return the out degree
*/
virtual uint64_t OutDegree(dgl_type_t etype, dgl_id_t vid) const = 0;
/*!
* \brief Get the out degrees of the given vertices.
* \note The given vertex should belong to the source vertex type
* @brief Get the out degrees of the given vertices.
* @note The given vertex should belong to the source vertex type
* of the given edge type.
* \param etype The edge type
* \param vid The vertex id array.
* \return the out degree array
* @param etype The edge type
* @param vid The vertex id array.
* @return the out degree array
*/
virtual DegreeArray OutDegrees(dgl_type_t etype, IdArray vids) const = 0;
/*!
* \brief Return the successor vector
* \note The given vertex should belong to the source vertex type
* @brief Return the successor vector
* @note The given vertex should belong to the source vertex type
* of the given edge type.
* \param vid The vertex id.
* \return the successor vector iterator pair.
* @param vid The vertex id.
* @return the successor vector iterator pair.
*/
virtual DGLIdIters SuccVec(dgl_type_t etype, dgl_id_t vid) const = 0;
/*!
* \brief Return the out edge id vector
* \note The given vertex should belong to the source vertex type
* @brief Return the out edge id vector
* @note The given vertex should belong to the source vertex type
* of the given edge type.
* \param vid The vertex id.
* \return the out edge id vector iterator pair.
* @param vid The vertex id.
* @return the out edge id vector iterator pair.
*/
virtual DGLIdIters OutEdgeVec(dgl_type_t etype, dgl_id_t vid) const = 0;
/*!
* \brief Return the predecessor vector
* \note The given vertex should belong to the dest vertex type
* @brief Return the predecessor vector
* @note The given vertex should belong to the dest vertex type
* of the given edge type.
* \param vid The vertex id.
* \return the predecessor vector iterator pair.
* @param vid The vertex id.
* @return the predecessor vector iterator pair.
*/
virtual DGLIdIters PredVec(dgl_type_t etype, dgl_id_t vid) const = 0;
/*!
* \brief Return the in edge id vector
* \note The given vertex should belong to the dest vertex type
* @brief Return the in edge id vector
* @note The given vertex should belong to the dest vertex type
* of the given edge type.
* \param vid The vertex id.
* \return the in edge id vector iterator pair.
* @param vid The vertex id.
* @return the in edge id vector iterator pair.
*/
virtual DGLIdIters InEdgeVec(dgl_type_t etype, dgl_id_t vid) const = 0;
/*!
* \brief Get the adjacency matrix of the graph.
* @brief Get the adjacency matrix of the graph.
*
* TODO(minjie): deprecate this interface; replace it with GetXXXMatrix.
*
......@@ -381,113 +381,113 @@ class BaseHeteroGraph : public runtime::Object {
* If the fmt is 'coo', the function should return one array of shape (2,
* nnz), representing a horitonzal stack of row and col indices.
*
* \param transpose A flag to transpose the returned adjacency matrix.
* \param fmt the format of the returned adjacency matrix.
* \return a vector of IdArrays.
* @param transpose A flag to transpose the returned adjacency matrix.
* @param fmt the format of the returned adjacency matrix.
* @return a vector of IdArrays.
*/
virtual std::vector<IdArray> GetAdj(
dgl_type_t etype, bool transpose, const std::string& fmt) const = 0;
/*!
* \brief Determine which format to use with a preference.
* @brief Determine which format to use with a preference.
*
* Otherwise, it will return whatever DGL thinks is the most appropriate given
* the arguments.
*
* \param etype Edge type.
* \param preferred_formats Preferred sparse formats.
* \return Available sparse format.
* @param etype Edge type.
* @param preferred_formats Preferred sparse formats.
* @return Available sparse format.
*/
virtual SparseFormat SelectFormat(
dgl_type_t etype, dgl_format_code_t preferred_formats) const = 0;
/*!
* \brief Return sparse formats already created for the graph.
* @brief Return sparse formats already created for the graph.
*
* \return a number of type dgl_format_code_t.
* @return a number of type dgl_format_code_t.
*/
virtual dgl_format_code_t GetCreatedFormats() const = 0;
/*!
* \brief Return allowed sparse formats for the graph.
* @brief Return allowed sparse formats for the graph.
*
* \return a number of type dgl_format_code_t.
* @return a number of type dgl_format_code_t.
*/
virtual dgl_format_code_t GetAllowedFormats() const = 0;
/*!
* \brief Return the graph in specified available formats.
* @brief Return the graph in specified available formats.
*
* \return The new graph.
* @return The new graph.
*/
virtual HeteroGraphPtr GetGraphInFormat(dgl_format_code_t formats) const = 0;
/*!
* \brief Get adjacency matrix in COO format.
* \param etype Edge type.
* \return COO matrix.
* @brief Get adjacency matrix in COO format.
* @param etype Edge type.
* @return COO matrix.
*/
virtual aten::COOMatrix GetCOOMatrix(dgl_type_t etype) const = 0;
/*!
* \brief Get adjacency matrix in CSR format.
* @brief Get adjacency matrix in CSR format.
*
* The row and column sizes are equal to the number of dsttype and srctype
* nodes, respectively.
*
* \param etype Edge type.
* \return CSR matrix.
* @param etype Edge type.
* @return CSR matrix.
*/
virtual aten::CSRMatrix GetCSRMatrix(dgl_type_t etype) const = 0;
/*!
* \brief Get adjacency matrix in CSC format.
* @brief Get adjacency matrix in CSC format.
*
* A CSC matrix is equivalent to the transpose of a CSR matrix.
* We reuse the CSRMatrix data structure as return value. The row and column
* sizes are equal to the number of dsttype and srctype nodes, respectively.
*
* \param etype Edge type.
* \return A CSR matrix.
* @param etype Edge type.
* @return A CSR matrix.
*/
virtual aten::CSRMatrix GetCSCMatrix(dgl_type_t etype) const = 0;
/*!
* \brief Extract the induced subgraph by the given vertices.
* @brief Extract the induced subgraph by the given vertices.
*
* The length of the given vector should be equal to the number of vertex
* types. Empty arrays can be provided if no vertex is needed for the type.
* The result subgraph has the same meta graph with the parent, but some types
* can have no node/edge.
*
* \param vids the induced vertices per type.
* \return the subgraph.
* @param vids the induced vertices per type.
* @return the subgraph.
*/
virtual HeteroSubgraph VertexSubgraph(
const std::vector<IdArray>& vids) const = 0;
/*!
* \brief Extract the induced subgraph by the given edges.
* @brief Extract the induced subgraph by the given edges.
*
* The length of the given vector should be equal to the number of edge types.
* Empty arrays can be provided if no edge is needed for the type. The result
* subgraph has the same meta graph with the parent, but some types can have
* no node/edge.
*
* \param eids The edges in the subgraph.
* \param preserve_nodes If true, the vertices will not be relabeled, so some
* @param eids The edges in the subgraph.
* @param preserve_nodes If true, the vertices will not be relabeled, so some
* vertices may have no incident edges. \return the subgraph.
*/
virtual HeteroSubgraph EdgeSubgraph(
const std::vector<IdArray>& eids, bool preserve_nodes = false) const = 0;
/*!
* \brief Convert the list of requested unitgraph graphs into a single
* @brief Convert the list of requested unitgraph graphs into a single
* unitgraph graph.
*
* \param etypes The list of edge type IDs.
* \return The flattened graph, with induced source/edge/destination
* @param etypes The list of edge type IDs.
* @return The flattened graph, with induced source/edge/destination
* types/IDs.
*/
virtual FlattenedHeteroGraphPtr Flatten(
......@@ -496,7 +496,7 @@ class BaseHeteroGraph : public runtime::Object {
return nullptr;
}
/*! \brief Cast this graph to immutable graph */
/*! @brief Cast this graph to immutable graph */
virtual GraphPtr AsImmutableGraph() const {
LOG(FATAL) << "AsImmutableGraph not supported.";
return nullptr;
......@@ -506,7 +506,7 @@ class BaseHeteroGraph : public runtime::Object {
DGL_DECLARE_OBJECT_TYPE_INFO(BaseHeteroGraph, runtime::Object);
protected:
/*! \brief meta graph */
/*! @brief meta graph */
GraphPtr meta_graph_;
// empty constructor
......@@ -517,7 +517,7 @@ class BaseHeteroGraph : public runtime::Object {
DGL_DEFINE_OBJECT_REF(HeteroGraphRef, BaseHeteroGraph);
/*!
* \brief Hetero-subgraph data structure.
* @brief Hetero-subgraph data structure.
*
* This class can be used as arguments and return values of a C API.
*
......@@ -531,17 +531,17 @@ DGL_DEFINE_OBJECT_REF(HeteroGraphRef, BaseHeteroGraph);
* </code>
*/
struct HeteroSubgraph : public runtime::Object {
/*! \brief The heterograph. */
/*! @brief The heterograph. */
HeteroGraphPtr graph;
/*!
* \brief The induced vertex ids of each entity type.
* @brief The induced vertex ids of each entity type.
* The vector length is equal to the number of vertex types in the parent
* graph. Each array i has the same length as the number of vertices in type
* i. Empty array is allowed if the mapping is identity.
*/
std::vector<IdArray> induced_vertices;
/*!
* \brief The induced edge ids of each relation type.
* @brief The induced edge ids of each relation type.
* The vector length is equal to the number of edge types in the parent graph.
* Each array i has the same length as the number of edges in type i.
* Empty array is allowed if the mapping is identity.
......@@ -555,46 +555,46 @@ struct HeteroSubgraph : public runtime::Object {
// Define HeteroSubgraphRef
DGL_DEFINE_OBJECT_REF(HeteroSubgraphRef, HeteroSubgraph);
/*! \brief The flattened heterograph */
/*! @brief The flattened heterograph */
struct FlattenedHeteroGraph : public runtime::Object {
/*! \brief The graph */
/*! @brief The graph */
HeteroGraphRef graph;
/*!
* \brief Mapping from source node ID to node type in parent graph
* \note The induced type array guarantees that the same type always appear
* @brief Mapping from source node ID to node type in parent graph
* @note The induced type array guarantees that the same type always appear
* contiguously.
*/
IdArray induced_srctype;
/*!
* \brief The set of node types in parent graph appearing in source nodes.
* @brief The set of node types in parent graph appearing in source nodes.
*/
IdArray induced_srctype_set;
/*! \brief Mapping from source node ID to local node ID in parent graph */
/*! @brief Mapping from source node ID to local node ID in parent graph */
IdArray induced_srcid;
/*!
* \brief Mapping from edge ID to edge type in parent graph
* \note The induced type array guarantees that the same type always appear
* @brief Mapping from edge ID to edge type in parent graph
* @note The induced type array guarantees that the same type always appear
* contiguously.
*/
IdArray induced_etype;
/*!
* \brief The set of edge types in parent graph appearing in edges.
* @brief The set of edge types in parent graph appearing in edges.
*/
IdArray induced_etype_set;
/*! \brief Mapping from edge ID to local edge ID in parent graph */
/*! @brief Mapping from edge ID to local edge ID in parent graph */
IdArray induced_eid;
/*!
* \brief Mapping from destination node ID to node type in parent graph
* \note The induced type array guarantees that the same type always appear
* @brief Mapping from destination node ID to node type in parent graph
* @note The induced type array guarantees that the same type always appear
* contiguously.
*/
IdArray induced_dsttype;
/*!
* \brief The set of node types in parent graph appearing in destination
* @brief The set of node types in parent graph appearing in destination
* nodes.
*/
IdArray induced_dsttype_set;
/*! \brief Mapping from destination node ID to local node ID in parent graph
/*! @brief Mapping from destination node ID to local node ID in parent graph
*/
IdArray induced_dstid;
......@@ -619,7 +619,7 @@ DGL_DEFINE_OBJECT_REF(FlattenedHeteroGraphRef, FlattenedHeteroGraph);
// Declarations of functions and algorithms
/*!
* \brief Create a heterograph from meta graph and a list of bipartite graph,
* @brief Create a heterograph from meta graph and a list of bipartite graph,
* additionally specifying number of nodes per type.
*/
HeteroGraphPtr CreateHeteroGraph(
......@@ -627,18 +627,18 @@ HeteroGraphPtr CreateHeteroGraph(
const std::vector<int64_t>& num_nodes_per_type = {});
/*!
* \brief Create a heterograph from COO input.
* \param num_vtypes Number of vertex types. Must be 1 or 2.
* \param num_src Number of nodes in the source type.
* \param num_dst Number of nodes in the destination type.
* \param row Src node ids of the edges.
* \param col Dst node ids of the edges.
* \param row_sorted Whether the `row` array is in sorted ascending order.
* \param col_sorted When `row_sorted` is true, whether the columns within each
* @brief Create a heterograph from COO input.
* @param num_vtypes Number of vertex types. Must be 1 or 2.
* @param num_src Number of nodes in the source type.
* @param num_dst Number of nodes in the destination type.
* @param row Src node ids of the edges.
* @param col Dst node ids of the edges.
* @param row_sorted Whether the `row` array is in sorted ascending order.
* @param col_sorted When `row_sorted` is true, whether the columns within each
* row are also sorted. When `row_sorted` is false, this flag must also be
* false.
* \param formats Sparse formats used for storing this graph.
* \return A heterograph pointer.
* @param formats Sparse formats used for storing this graph.
* @return A heterograph pointer.
*/
HeteroGraphPtr CreateFromCOO(
int64_t num_vtypes, int64_t num_src, int64_t num_dst, IdArray row,
......@@ -646,73 +646,73 @@ HeteroGraphPtr CreateFromCOO(
dgl_format_code_t formats = ALL_CODE);
/*!
* \brief Create a heterograph from COO input.
* \param num_vtypes Number of vertex types. Must be 1 or 2.
* \param mat The COO matrix
* \param formats Sparse formats used for storing this graph.
* \return A heterograph pointer.
* @brief Create a heterograph from COO input.
* @param num_vtypes Number of vertex types. Must be 1 or 2.
* @param mat The COO matrix
* @param formats Sparse formats used for storing this graph.
* @return A heterograph pointer.
*/
HeteroGraphPtr CreateFromCOO(
int64_t num_vtypes, const aten::COOMatrix& mat,
dgl_format_code_t formats = ALL_CODE);
/*!
* \brief Create a heterograph from CSR input.
* \param num_vtypes Number of vertex types. Must be 1 or 2.
* \param num_src Number of nodes in the source type.
* \param num_dst Number of nodes in the destination type.
* \param indptr Indptr array
* \param indices Indices array
* \param edge_ids Edge ids
* \param formats Sparse formats for storing this graph.
* \return A heterograph pointer.
* @brief Create a heterograph from CSR input.
* @param num_vtypes Number of vertex types. Must be 1 or 2.
* @param num_src Number of nodes in the source type.
* @param num_dst Number of nodes in the destination type.
* @param indptr Indptr array
* @param indices Indices array
* @param edge_ids Edge ids
* @param formats Sparse formats for storing this graph.
* @return A heterograph pointer.
*/
HeteroGraphPtr CreateFromCSR(
int64_t num_vtypes, int64_t num_src, int64_t num_dst, IdArray indptr,
IdArray indices, IdArray edge_ids, dgl_format_code_t formats = ALL_CODE);
/*!
* \brief Create a heterograph from CSR input.
* \param num_vtypes Number of vertex types. Must be 1 or 2.
* \param mat The CSR matrix
* \param formats Sparse formats for storing this graph.
* \return A heterograph pointer.
* @brief Create a heterograph from CSR input.
* @param num_vtypes Number of vertex types. Must be 1 or 2.
* @param mat The CSR matrix
* @param formats Sparse formats for storing this graph.
* @return A heterograph pointer.
*/
HeteroGraphPtr CreateFromCSR(
int64_t num_vtypes, const aten::CSRMatrix& mat,
dgl_format_code_t formats = ALL_CODE);
/*!
* \brief Create a heterograph from CSC input.
* \param num_vtypes Number of vertex types. Must be 1 or 2.
* \param num_src Number of nodes in the source type.
* \param num_dst Number of nodes in the destination type.
* \param indptr Indptr array
* \param indices Indices array
* \param edge_ids Edge ids
* \param formats Sparse formats used for storing this graph.
* \return A heterograph pointer.
* @brief Create a heterograph from CSC input.
* @param num_vtypes Number of vertex types. Must be 1 or 2.
* @param num_src Number of nodes in the source type.
* @param num_dst Number of nodes in the destination type.
* @param indptr Indptr array
* @param indices Indices array
* @param edge_ids Edge ids
* @param formats Sparse formats used for storing this graph.
* @return A heterograph pointer.
*/
HeteroGraphPtr CreateFromCSC(
int64_t num_vtypes, int64_t num_src, int64_t num_dst, IdArray indptr,
IdArray indices, IdArray edge_ids, dgl_format_code_t formats = ALL_CODE);
/*!
* \brief Create a heterograph from CSC input.
* \param num_vtypes Number of vertex types. Must be 1 or 2.
* \param mat The CSC matrix
* \param formats Sparse formats available for storing this graph.
* \return A heterograph pointer.
* @brief Create a heterograph from CSC input.
* @param num_vtypes Number of vertex types. Must be 1 or 2.
* @param mat The CSC matrix
* @param formats Sparse formats available for storing this graph.
* @return A heterograph pointer.
*/
HeteroGraphPtr CreateFromCSC(
int64_t num_vtypes, const aten::CSRMatrix& mat,
dgl_format_code_t formats = ALL_CODE);
/*!
* \brief Extract the subgraph of the in edges of the given nodes.
* \param graph Graph
* \param nodes Node IDs of each type
* \param relabel_nodes Whether to remove isolated nodes and relabel the rest
* @brief Extract the subgraph of the in edges of the given nodes.
* @param graph Graph
* @param nodes Node IDs of each type
* @param relabel_nodes Whether to remove isolated nodes and relabel the rest
* ones \return Subgraph containing only the in edges. The returned graph has
* the same schema as the original one.
*/
......@@ -721,10 +721,10 @@ HeteroSubgraph InEdgeGraph(
bool relabel_nodes = false);
/*!
* \brief Extract the subgraph of the out edges of the given nodes.
* \param graph Graph
* \param nodes Node IDs of each type
* \param relabel_nodes Whether to remove isolated nodes and relabel the rest
* @brief Extract the subgraph of the out edges of the given nodes.
* @param graph Graph
* @param nodes Node IDs of each type
* @param relabel_nodes Whether to remove isolated nodes and relabel the rest
* ones \return Subgraph containing only the out edges. The returned graph has
* the same schema as the original one.
*/
......@@ -733,31 +733,31 @@ HeteroSubgraph OutEdgeGraph(
bool relabel_nodes = false);
/*!
* \brief Joint union multiple graphs into one graph.
* @brief Joint union multiple graphs into one graph.
*
* All input graphs should have the same metagraph.
*
* TODO(xiangsx): remove the meta_graph argument
*
* \param meta_graph Metagraph of the inputs and result.
* \param component_graphs Input graphs
* \return One graph that unions all the components
* @param meta_graph Metagraph of the inputs and result.
* @param component_graphs Input graphs
* @return One graph that unions all the components
*/
HeteroGraphPtr JointUnionHeteroGraph(
GraphPtr meta_graph, const std::vector<HeteroGraphPtr>& component_graphs);
/*!
* \brief Union multiple graphs into one with each input graph as one disjoint
* @brief Union multiple graphs into one with each input graph as one disjoint
* component.
*
* All input graphs should have the same metagraph.
*
* TODO(minjie): remove the meta_graph argument
*
* \tparam IdType Graph's index data type, can be int32_t or int64_t
* \param meta_graph Metagraph of the inputs and result.
* \param component_graphs Input graphs
* \return One graph that unions all the components
* @tparam IdType Graph's index data type, can be int32_t or int64_t
* @param meta_graph Metagraph of the inputs and result.
* @param component_graphs Input graphs
* @return One graph that unions all the components
*/
template <class IdType>
HeteroGraphPtr DisjointUnionHeteroGraph(
......@@ -767,18 +767,18 @@ HeteroGraphPtr DisjointUnionHeteroGraph2(
GraphPtr meta_graph, const std::vector<HeteroGraphPtr>& component_graphs);
/*!
* \brief Slice a contiguous subgraph, e.g. retrieve a component graph from a
* @brief Slice a contiguous subgraph, e.g. retrieve a component graph from a
* batched graph.
*
* TODO(mufei): remove the meta_graph argument
*
* \param meta_graph Metagraph of the input and result.
* \param batched_graph Input graph.
* \param num_nodes_per_type Number of vertices of each type in the result.
* \param start_nid_per_type Start vertex ID of each type to slice.
* \param num_edges_per_type Number of edges of each type in the result.
* \param start_eid_per_type Start edge ID of each type to slice.
* \return Sliced graph
* @param meta_graph Metagraph of the input and result.
* @param batched_graph Input graph.
* @param num_nodes_per_type Number of vertices of each type in the result.
* @param start_nid_per_type Start vertex ID of each type to slice.
* @param num_edges_per_type Number of edges of each type in the result.
* @param start_eid_per_type Start edge ID of each type to slice.
* @return Sliced graph
*/
HeteroGraphPtr SliceHeteroGraph(
GraphPtr meta_graph, HeteroGraphPtr batched_graph,
......@@ -786,7 +786,7 @@ HeteroGraphPtr SliceHeteroGraph(
IdArray num_edges_per_type, IdArray start_eid_per_type);
/*!
* \brief Split a graph into multiple disjoin components.
* @brief Split a graph into multiple disjoin components.
*
* Edges across different components are ignored. All the result graphs have the
* same metagraph as the input one.
......@@ -798,12 +798,12 @@ HeteroGraphPtr SliceHeteroGraph(
* TODO(minjie): remove the meta_graph argument; use vector<IdArray> for
* vertex_sizes and edge_sizes.
*
* \tparam IdType Graph's index data type, can be int32_t or int64_t
* \param meta_graph Metagraph.
* \param batched_graph Input graph.
* \param vertex_sizes Number of vertices of each component.
* \param edge_sizes Number of vertices of each component.
* \return A list of graphs representing each disjoint components.
* @tparam IdType Graph's index data type, can be int32_t or int64_t
* @param meta_graph Metagraph.
* @param batched_graph Input graph.
* @param vertex_sizes Number of vertices of each component.
* @param edge_sizes Number of vertices of each component.
* @return A list of graphs representing each disjoint components.
*/
template <class IdType>
std::vector<HeteroGraphPtr> DisjointPartitionHeteroBySizes(
......@@ -815,7 +815,7 @@ std::vector<HeteroGraphPtr> DisjointPartitionHeteroBySizes2(
IdArray edge_sizes);
/*!
* \brief Structure for pickle/unpickle.
* @brief Structure for pickle/unpickle.
*
* The design principle is to leverage the NDArray class as much as possible so
* that when they are converted to backend-specific tensors, we could leverage
......@@ -827,29 +827,29 @@ std::vector<HeteroGraphPtr> DisjointPartitionHeteroBySizes2(
* This class can be used as arguments and return values of a C API.
*/
struct HeteroPickleStates : public runtime::Object {
/*! \brief version number */
/*! @brief version number */
int64_t version = 0;
/*! \brief Metainformation
/*! @brief Metainformation
*
* metagraph, number of nodes per type, format, flags
*/
std::string meta;
/*! \brief Arrays representing graph structure (coo or csr) */
/*! @brief Arrays representing graph structure (coo or csr) */
std::vector<IdArray> arrays;
/* To support backward compatibility, we have to retain fields in the old
* version of HeteroPickleStates
*/
/*! \brief Metagraph(64bits ImmutableGraph) */
/*! @brief Metagraph(64bits ImmutableGraph) */
GraphPtr metagraph;
/*! \brief Number of nodes per type */
/*! @brief Number of nodes per type */
std::vector<int64_t> num_nodes_per_type;
/*! \brief adjacency matrices of each relation graph */
/*! @brief adjacency matrices of each relation graph */
std::vector<std::shared_ptr<SparseMatrix> > adjs;
static constexpr const char* _type_key = "graph.HeteroPickleStates";
......@@ -860,31 +860,31 @@ struct HeteroPickleStates : public runtime::Object {
DGL_DEFINE_OBJECT_REF(HeteroPickleStatesRef, HeteroPickleStates);
/*!
* \brief Create a heterograph from pickling states.
* @brief Create a heterograph from pickling states.
*
* \param states Pickle states
* \return A heterograph pointer
* @param states Pickle states
* @return A heterograph pointer
*/
HeteroGraphPtr HeteroUnpickle(const HeteroPickleStates& states);
/*!
* \brief Get the pickling state of the relation graph structure in backend
* @brief Get the pickling state of the relation graph structure in backend
* tensors.
*
* \return a HeteroPickleStates object
* @return a HeteroPickleStates object
*/
HeteroPickleStates HeteroPickle(HeteroGraphPtr graph);
/*!
* \brief Old version of HeteroUnpickle, for backward compatibility
* @brief Old version of HeteroUnpickle, for backward compatibility
*
* \param states Pickle states
* \return A heterograph pointer
* @param states Pickle states
* @return A heterograph pointer
*/
HeteroGraphPtr HeteroUnpickleOld(const HeteroPickleStates& states);
/*!
* \brief Create heterograph from pickling states pickled by ForkingPickler.
* @brief Create heterograph from pickling states pickled by ForkingPickler.
*
* This is different from HeteroUnpickle where
* (1) Backward compatibility is not required,
......@@ -893,7 +893,7 @@ HeteroGraphPtr HeteroUnpickleOld(const HeteroPickleStates& states);
HeteroGraphPtr HeteroForkingUnpickle(const HeteroPickleStates& states);
/*!
* \brief Get the pickling states of the relation graph structure in backend
* @brief Get the pickling states of the relation graph structure in backend
* tensors for ForkingPickler.
*
* This is different from HeteroPickle where
......
include/dgl/bcast.h
View file @ 6c53f351
/*!
* Copyright (c) 2020 by Contributors * \file dgl/aten/bcast.h
* \brief Broadcast related function C++ header.
* Copyright (c) 2020 by Contributors
* @file dgl/aten/bcast.h
* @brief Broadcast related function C++ header.
*/
#ifndef DGL_BCAST_H_
#define DGL_BCAST_H_
......@@ -14,12 +15,12 @@ using namespace dgl::runtime;
namespace dgl {
/*!
* \brief Broadcast offsets and auxiliary information.
* @brief Broadcast offsets and auxiliary information.
*/
struct BcastOff {
/*!
* \brief offset vector of lhs operand and rhs operand.
* \note lhs_offset[i] indicates the start position of the scalar
* @brief offset vector of lhs operand and rhs operand.
* @note lhs_offset[i] indicates the start position of the scalar
* in lhs operand that required to compute the i-th element
* in the output, likewise for rhs_offset.
*
......@@ -35,11 +36,11 @@ struct BcastOff {
* rhs array.
*/
std::vector<int64_t> lhs_offset, rhs_offset;
/*! \brief Whether broadcast is required or not. */
/*! @brief Whether broadcast is required or not. */
bool use_bcast;
/*!
* \brief Auxiliary information for kernel computation
* \note lhs_len refers to the left hand side operand length.
* @brief Auxiliary information for kernel computation
* @note lhs_len refers to the left hand side operand length.
* e.g. 15 for shape (1, 3, 5)
* rhs_len refers to the right hand side operand length.
* e.g. 15 for shape (3, 1, 5)
......@@ -52,13 +53,13 @@ struct BcastOff {
};
/*!
* \brief: Compute broadcast and auxiliary information given operator
* @brief: Compute broadcast and auxiliary information given operator
* and operands for kernel computation.
* \param op: a string indicates the operator, could be `add`, `sub`,
* @param op: a string indicates the operator, could be `add`, `sub`,
* `mul`, `div`, `dot`, 'copy_u`, `copy_e`.
* \param lhs The left hand side operand of NDArray class.
* \param rhs The right hand side operand of NDArray class.
* \return the broadcast information of BcastOff class.
* @param lhs The left hand side operand of NDArray class.
* @param rhs The right hand side operand of NDArray class.
* @return the broadcast information of BcastOff class.
*/
BcastOff CalcBcastOff(const std::string& op, NDArray lhs, NDArray rhs);
......
include/dgl/graph.h
View file @ 6c53f351
/*!
* Copyright (c) 2018 by Contributors
* \file dgl/graph.h
* \brief DGL graph index class.
* @file dgl/graph.h
* @brief DGL graph index class.
*/
#ifndef DGL_GRAPH_H_
#define DGL_GRAPH_H_
......@@ -21,20 +21,20 @@ class Graph;
class GraphOp;
typedef std::shared_ptr<Graph> MutableGraphPtr;
/*! \brief Mutable graph based on adjacency list. */
/*! @brief Mutable graph based on adjacency list. */
class Graph : public GraphInterface {
public:
/*! \brief default constructor */
/*! @brief default constructor */
Graph() {}
/*! \brief construct a graph from the coo format. */
/*! @brief construct a graph from the coo format. */
Graph(IdArray src_ids, IdArray dst_ids, size_t num_nodes);
/*! \brief default copy constructor */
/*! @brief default copy constructor */
Graph(const Graph& other) = default;
#ifndef _MSC_VER
/*! \brief default move constructor */
/*! @brief default move constructor */
Graph(Graph&& other) = default;
#else
Graph(Graph&& other) {
......@@ -48,36 +48,36 @@ class Graph : public GraphInterface {
}
#endif // _MSC_VER
/*! \brief default assign constructor */
/*! @brief default assign constructor */
Graph& operator=(const Graph& other) = default;
/*! \brief default destructor */
/*! @brief default destructor */
~Graph() = default;
/*!
* \brief Add vertices to the graph.
* \note Since vertices are integers enumerated from zero, only the number of
* @brief Add vertices to the graph.
* @note Since vertices are integers enumerated from zero, only the number of
* vertices to be added needs to be specified.
* \param num_vertices The number of vertices to be added.
* @param num_vertices The number of vertices to be added.
*/
void AddVertices(uint64_t num_vertices) override;
/*!
* \brief Add one edge to the graph.
* \param src The source vertex.
* \param dst The destination vertex.
* @brief Add one edge to the graph.
* @param src The source vertex.
* @param dst The destination vertex.
*/
void AddEdge(dgl_id_t src, dgl_id_t dst) override;
/*!
* \brief Add edges to the graph.
* \param src_ids The source vertex id array.
* \param dst_ids The destination vertex id array.
* @brief Add edges to the graph.
* @param src_ids The source vertex id array.
* @param dst_ids The destination vertex id array.
*/
void AddEdges(IdArray src_ids, IdArray dst_ids) override;
/*!
* \brief Clear the graph. Remove all vertices/edges.
* @brief Clear the graph. Remove all vertices/edges.
*/
void Clear() override {
adjlist_.clear();
......@@ -93,13 +93,13 @@ class Graph : public GraphInterface {
uint8_t NumBits() const override { return 64; }
/*!
* \note not const since we have caches
* \return whether the graph is a multigraph
* @note not const since we have caches
* @return whether the graph is a multigraph
*/
bool IsMultigraph() const override;
/*!
* \return whether the graph is read-only
* @return whether the graph is read-only
*/
bool IsReadonly() const override { return false; }
......@@ -121,48 +121,48 @@ class Graph : public GraphInterface {
BoolArray HasEdgesBetween(IdArray src_ids, IdArray dst_ids) const override;
/*!
* \brief Find the predecessors of a vertex.
* \param vid The vertex id.
* \param radius The radius of the neighborhood. Default is immediate neighbor
* @brief Find the predecessors of a vertex.
* @param vid The vertex id.
* @param radius The radius of the neighborhood. Default is immediate neighbor
* (radius=1).
* \return the predecessor id array.
* @return the predecessor id array.
*/
IdArray Predecessors(dgl_id_t vid, uint64_t radius = 1) const override;
/*!
* \brief Find the successors of a vertex.
* \param vid The vertex id.
* \param radius The radius of the neighborhood. Default is immediate neighbor
* @brief Find the successors of a vertex.
* @param vid The vertex id.
* @param radius The radius of the neighborhood. Default is immediate neighbor
* (radius=1).
* \return the successor id array.
* @return the successor id array.
*/
IdArray Successors(dgl_id_t vid, uint64_t radius = 1) const override;
/*!
* \brief Get all edge ids between the two given endpoints
* \note Edges are associated with an integer id start from zero.
* @brief Get all edge ids between the two given endpoints
* @note Edges are associated with an integer id start from zero.
* The id is assigned when the edge is being added to the graph.
* \param src The source vertex.
* \param dst The destination vertex.
* \return the edge id array.
* @param src The source vertex.
* @param dst The destination vertex.
* @return the edge id array.
*/
IdArray EdgeId(dgl_id_t src, dgl_id_t dst) const override;
/*!
* \brief Get all edge ids between the given endpoint pairs.
* \note Edges are associated with an integer id start from zero.
* @brief Get all edge ids between the given endpoint pairs.
* @note Edges are associated with an integer id start from zero.
* The id is assigned when the edge is being added to the graph.
* If duplicate pairs exist, the returned edge IDs will also duplicate.
* The order of returned edge IDs will follow the order of src-dst pairs
* first, and ties are broken by the order of edge ID.
* \return EdgeArray containing all edges between all pairs.
* @return EdgeArray containing all edges between all pairs.
*/
EdgeArray EdgeIds(IdArray src, IdArray dst) const override;
/*!
* \brief Find the edge ID and return the pair of endpoints
* \param eid The edge ID
* \return a pair whose first element is the source and the second the
* @brief Find the edge ID and return the pair of endpoints
* @param eid The edge ID
* @return a pair whose first element is the source and the second the
* destination.
*/
std::pair<dgl_id_t, dgl_id_t> FindEdge(dgl_id_t eid) const override {
......@@ -170,57 +170,57 @@ class Graph : public GraphInterface {
}
/*!
* \brief Find the edge IDs and return their source and target node IDs.
* \param eids The edge ID array.
* \return EdgeArray containing all edges with id in eid. The order is
* @brief Find the edge IDs and return their source and target node IDs.
* @param eids The edge ID array.
* @return EdgeArray containing all edges with id in eid. The order is
* preserved.
*/
EdgeArray FindEdges(IdArray eids) const override;
/*!
* \brief Get the in edges of the vertex.
* \note The returned dst id array is filled with vid.
* \param vid The vertex id.
* \return the edges
* @brief Get the in edges of the vertex.
* @note The returned dst id array is filled with vid.
* @param vid The vertex id.
* @return the edges
*/
EdgeArray InEdges(dgl_id_t vid) const override;
/*!
* \brief Get the in edges of the vertices.
* \param vids The vertex id array.
* \return the id arrays of the two endpoints of the edges.
* @brief Get the in edges of the vertices.
* @param vids The vertex id array.
* @return the id arrays of the two endpoints of the edges.
*/
EdgeArray InEdges(IdArray vids) const override;
/*!
* \brief Get the out edges of the vertex.
* \note The returned src id array is filled with vid.
* \param vid The vertex id.
* \return the id arrays of the two endpoints of the edges.
* @brief Get the out edges of the vertex.
* @note The returned src id array is filled with vid.
* @param vid The vertex id.
* @return the id arrays of the two endpoints of the edges.
*/
EdgeArray OutEdges(dgl_id_t vid) const override;
/*!
* \brief Get the out edges of the vertices.
* \param vids The vertex id array.
* \return the id arrays of the two endpoints of the edges.
* @brief Get the out edges of the vertices.
* @param vids The vertex id array.
* @return the id arrays of the two endpoints of the edges.
*/
EdgeArray OutEdges(IdArray vids) const override;
/*!
* \brief Get all the edges in the graph.
* \note If sorted is true, the returned edges list is sorted by their src and
* @brief Get all the edges in the graph.
* @note If sorted is true, the returned edges list is sorted by their src and
* dst ids. Otherwise, they are in their edge id order.
* \param sorted Whether the returned edge list is sorted by their src and dst
* @param sorted Whether the returned edge list is sorted by their src and dst
* ids.
* \return the id arrays of the two endpoints of the edges.
* @return the id arrays of the two endpoints of the edges.
*/
EdgeArray Edges(const std::string& order = "") const override;
/*!
* \brief Get the in degree of the given vertex.
* \param vid The vertex id.
* \return the in degree
* @brief Get the in degree of the given vertex.
* @param vid The vertex id.
* @return the in degree
*/
uint64_t InDegree(dgl_id_t vid) const override {
CHECK(HasVertex(vid)) << "invalid vertex: " << vid;
......@@ -228,16 +228,16 @@ class Graph : public GraphInterface {
}
/*!
* \brief Get the in degrees of the given vertices.
* \param vid The vertex id array.
* \return the in degree array
* @brief Get the in degrees of the given vertices.
* @param vid The vertex id array.
* @return the in degree array
*/
DegreeArray InDegrees(IdArray vids) const override;
/*!
* \brief Get the out degree of the given vertex.
* \param vid The vertex id.
* \return the out degree
* @brief Get the out degree of the given vertex.
* @param vid The vertex id.
* @return the out degree
*/
uint64_t OutDegree(dgl_id_t vid) const override {
CHECK(HasVertex(vid)) << "invalid vertex: " << vid;
......@@ -245,14 +245,14 @@ class Graph : public GraphInterface {
}
/*!
* \brief Get the out degrees of the given vertices.
* \param vid The vertex id array.
* \return the out degree array
* @brief Get the out degrees of the given vertices.
* @param vid The vertex id array.
* @return the out degree array
*/
DegreeArray OutDegrees(IdArray vids) const override;
/*!
* \brief Construct the induced subgraph of the given vertices.
* @brief Construct the induced subgraph of the given vertices.
*
* The induced subgraph is a subgraph formed by specifying a set of vertices
* V' and then selecting all of the edges from the original graph that connect
......@@ -265,13 +265,13 @@ class Graph : public GraphInterface {
*
* The result subgraph is read-only.
*
* \param vids The vertices in the subgraph.
* \return the induced subgraph
* @param vids The vertices in the subgraph.
* @return the induced subgraph
*/
Subgraph VertexSubgraph(IdArray vids) const override;
/*!
* \brief Construct the induced edge subgraph of the given edges.
* @brief Construct the induced edge subgraph of the given edges.
*
* The induced edges subgraph is a subgraph formed by specifying a set of
* edges E' and then selecting all of the nodes from the original graph that
......@@ -284,16 +284,16 @@ class Graph : public GraphInterface {
*
* The result subgraph is read-only.
*
* \param eids The edges in the subgraph.
* \return the induced edge subgraph
* @param eids The edges in the subgraph.
* @return the induced edge subgraph
*/
Subgraph EdgeSubgraph(
IdArray eids, bool preserve_nodes = false) const override;
/*!
* \brief Return the successor vector
* \param vid The vertex id.
* \return the successor vector
* @brief Return the successor vector
* @param vid The vertex id.
* @return the successor vector
*/
DGLIdIters SuccVec(dgl_id_t vid) const override {
auto data = adjlist_[vid].succ.data();
......@@ -302,9 +302,9 @@ class Graph : public GraphInterface {
}
/*!
* \brief Return the out edge id vector
* \param vid The vertex id.
* \return the out edge id vector
* @brief Return the out edge id vector
* @param vid The vertex id.
* @return the out edge id vector
*/
DGLIdIters OutEdgeVec(dgl_id_t vid) const override {
auto data = adjlist_[vid].edge_id.data();
......@@ -313,9 +313,9 @@ class Graph : public GraphInterface {
}
/*!
* \brief Return the predecessor vector
* \param vid The vertex id.
* \return the predecessor vector
* @brief Return the predecessor vector
* @param vid The vertex id.
* @return the predecessor vector
*/
DGLIdIters PredVec(dgl_id_t vid) const override {
auto data = reverse_adjlist_[vid].succ.data();
......@@ -324,9 +324,9 @@ class Graph : public GraphInterface {
}
/*!
* \brief Return the in edge id vector
* \param vid The vertex id.
* \return the in edge id vector
* @brief Return the in edge id vector
* @param vid The vertex id.
* @return the in edge id vector
*/
DGLIdIters InEdgeVec(dgl_id_t vid) const override {
auto data = reverse_adjlist_[vid].edge_id.data();
......@@ -335,21 +335,21 @@ class Graph : public GraphInterface {
}
/*!
* \brief Get the adjacency matrix of the graph.
* @brief Get the adjacency matrix of the graph.
*
* By default, a row of returned adjacency matrix represents the destination
* of an edge and the column represents the source.
* \param transpose A flag to transpose the returned adjacency matrix.
* \param fmt the format of the returned adjacency matrix.
* \return a vector of three IdArray.
* @param transpose A flag to transpose the returned adjacency matrix.
* @param fmt the format of the returned adjacency matrix.
* @return a vector of three IdArray.
*/
std::vector<IdArray> GetAdj(
bool transpose, const std::string& fmt) const override;
/*! \brief Create an empty graph */
/*! @brief Create an empty graph */
static MutableGraphPtr Create() { return std::make_shared<Graph>(); }
/*! \brief Create from coo */
/*! @brief Create from coo */
static MutableGraphPtr CreateFromCOO(
int64_t num_nodes, IdArray src_ids, IdArray dst_ids) {
return std::make_shared<Graph>(src_ids, dst_ids, num_nodes);
......@@ -357,29 +357,29 @@ class Graph : public GraphInterface {
protected:
friend class GraphOp;
/*! \brief Internal edge list type */
/*! @brief Internal edge list type */
struct EdgeList {
/*! \brief successor vertex list */
/*! @brief successor vertex list */
std::vector<dgl_id_t> succ;
/*! \brief out edge list */
/*! @brief out edge list */
std::vector<dgl_id_t> edge_id;
};
typedef std::vector<EdgeList> AdjacencyList;
/*! \brief adjacency list using vector storage */
/*! @brief adjacency list using vector storage */
AdjacencyList adjlist_;
/*! \brief reverse adjacency list using vector storage */
/*! @brief reverse adjacency list using vector storage */
AdjacencyList reverse_adjlist_;
/*! \brief all edges' src endpoints in their edge id order */
/*! @brief all edges' src endpoints in their edge id order */
std::vector<dgl_id_t> all_edges_src_;
/*! \brief all edges' dst endpoints in their edge id order */
/*! @brief all edges' dst endpoints in their edge id order */
std::vector<dgl_id_t> all_edges_dst_;
/*! \brief read only flag */
/*! @brief read only flag */
bool read_only_ = false;
/*! \brief number of edges */
/*! @brief number of edges */
uint64_t num_edges_ = 0;
};
......
include/dgl/graph_interface.h
View file @ 6c53f351
/*!
* Copyright (c) 2018 by Contributors
* \file dgl/graph_interface.h
* \brief DGL graph index class.
* @file dgl/graph_interface.h
* @brief DGL graph index class.
*/
#ifndef DGL_GRAPH_INTERFACE_H_
#define DGL_GRAPH_INTERFACE_H_
......@@ -20,7 +20,7 @@ namespace dgl {
const dgl_id_t DGL_INVALID_ID = static_cast<dgl_id_t>(-1);
/*!
* \brief This class references data in std::vector.
* @brief This class references data in std::vector.
*
* This isn't a STL-style iterator. It provides a STL data container interface.
* but it doesn't own data itself. instead, it only references data in
......@@ -45,7 +45,7 @@ class DGLIdIters {
};
/*!
* \brief int32 version for DGLIdIters
* @brief int32 version for DGLIdIters
*
*/
class DGLIdIters32 {
......@@ -66,9 +66,9 @@ class DGLIdIters32 {
const int32_t *begin_{nullptr}, *end_{nullptr};
};
/* \brief structure used to represent a list of edges */
/* @brief structure used to represent a list of edges */
typedef struct {
/* \brief the two endpoints and the id of the edge */
/* @brief the two endpoints and the id of the edge */
IdArray src, dst, id;
} EdgeArray;
......@@ -79,7 +79,7 @@ class GraphInterface;
typedef std::shared_ptr<GraphInterface> GraphPtr;
/*!
* \brief dgl graph index interface.
* @brief dgl graph index interface.
*
* DGL's graph is directed. Vertices are integers enumerated from zero.
*
......@@ -94,50 +94,50 @@ class GraphInterface : public runtime::Object {
virtual ~GraphInterface() = default;
/*!
* \brief Add vertices to the graph.
* \note Since vertices are integers enumerated from zero, only the number of
* @brief Add vertices to the graph.
* @note Since vertices are integers enumerated from zero, only the number of
* vertices to be added needs to be specified.
* \param num_vertices The number of vertices to be added.
* @param num_vertices The number of vertices to be added.
*/
virtual void AddVertices(uint64_t num_vertices) = 0;
/*!
* \brief Add one edge to the graph.
* \param src The source vertex.
* \param dst The destination vertex.
* @brief Add one edge to the graph.
* @param src The source vertex.
* @param dst The destination vertex.
*/
virtual void AddEdge(dgl_id_t src, dgl_id_t dst) = 0;
/*!
* \brief Add edges to the graph.
* \param src_ids The source vertex id array.
* \param dst_ids The destination vertex id array.
* @brief Add edges to the graph.
* @param src_ids The source vertex id array.
* @param dst_ids The destination vertex id array.
*/
virtual void AddEdges(IdArray src_ids, IdArray dst_ids) = 0;
/*!
* \brief Clear the graph. Remove all vertices/edges.
* @brief Clear the graph. Remove all vertices/edges.
*/
virtual void Clear() = 0;
/*!
* \brief Get the device context of this graph.
* @brief Get the device context of this graph.
*/
virtual DGLContext Context() const = 0;
/*!
* \brief Get the number of integer bits used to store node/edge ids
* @brief Get the number of integer bits used to store node/edge ids
* (32 or 64).
*/
virtual uint8_t NumBits() const = 0;
/*!
* \return whether the graph is a multigraph
* @return whether the graph is a multigraph
*/
virtual bool IsMultigraph() const = 0;
/*!
* \return whether the graph is unibipartite
* @return whether the graph is unibipartite
*/
virtual bool IsUniBipartite() const {
EdgeArray edges = Edges();
......@@ -168,7 +168,7 @@ class GraphInterface : public runtime::Object {
}
/*!
* \return whether the graph is read-only
* @return whether the graph is read-only
*/
virtual bool IsReadonly() const = 0;
......@@ -193,130 +193,130 @@ class GraphInterface : public runtime::Object {
virtual BoolArray HasEdgesBetween(IdArray src_ids, IdArray dst_ids) const = 0;
/*!
* \brief Find the predecessors of a vertex.
* \param vid The vertex id.
* \param radius The radius of the neighborhood. Default is immediate neighbor
* @brief Find the predecessors of a vertex.
* @param vid The vertex id.
* @param radius The radius of the neighborhood. Default is immediate neighbor
* (radius=1).
* \return the predecessor id array.
* @return the predecessor id array.
*/
virtual IdArray Predecessors(dgl_id_t vid, uint64_t radius = 1) const = 0;
/*!
* \brief Find the successors of a vertex.
* \param vid The vertex id.
* \param radius The radius of the neighborhood. Default is immediate neighbor
* @brief Find the successors of a vertex.
* @param vid The vertex id.
* @param radius The radius of the neighborhood. Default is immediate neighbor
* (radius=1).
* \return the successor id array.
* @return the successor id array.
*/
virtual IdArray Successors(dgl_id_t vid, uint64_t radius = 1) const = 0;
/*!
* \brief Get all edge ids between the two given endpoints
* \note Edges are associated with an integer id start from zero.
* @brief Get all edge ids between the two given endpoints
* @note Edges are associated with an integer id start from zero.
* The id is assigned when the edge is being added to the graph.
* \param src The source vertex.
* \param dst The destination vertex.
* \return the edge id array.
* @param src The source vertex.
* @param dst The destination vertex.
* @return the edge id array.
*/
virtual IdArray EdgeId(dgl_id_t src, dgl_id_t dst) const = 0;
/*!
* \brief Get all edge ids between the given endpoint pairs.
* \note Edges are associated with an integer id start from zero.
* @brief Get all edge ids between the given endpoint pairs.
* @note Edges are associated with an integer id start from zero.
* The id is assigned when the edge is being added to the graph.
* If duplicate pairs exist, the returned edge IDs will also duplicate.
* The order of returned edge IDs will follow the order of src-dst pairs
* first, and ties are broken by the order of edge ID.
* \return EdgeArray containing all edges between all pairs.
* @return EdgeArray containing all edges between all pairs.
*/
virtual EdgeArray EdgeIds(IdArray src, IdArray dst) const = 0;
/*!
* \brief Find the edge ID and return the pair of endpoints
* \param eid The edge ID
* \return a pair whose first element is the source and the second the
* @brief Find the edge ID and return the pair of endpoints
* @param eid The edge ID
* @return a pair whose first element is the source and the second the
* destination.
*/
virtual std::pair<dgl_id_t, dgl_id_t> FindEdge(dgl_id_t eid) const = 0;
/*!
* \brief Find the edge IDs and return their source and target node IDs.
* \param eids The edge ID array.
* \return EdgeArray containing all edges with id in eid. The order is
* @brief Find the edge IDs and return their source and target node IDs.
* @param eids The edge ID array.
* @return EdgeArray containing all edges with id in eid. The order is
* preserved.
*/
virtual EdgeArray FindEdges(IdArray eids) const = 0;
/*!
* \brief Get the in edges of the vertex.
* \note The returned dst id array is filled with vid.
* \param vid The vertex id.
* \return the edges
* @brief Get the in edges of the vertex.
* @note The returned dst id array is filled with vid.
* @param vid The vertex id.
* @return the edges
*/
virtual EdgeArray InEdges(dgl_id_t vid) const = 0;
/*!
* \brief Get the in edges of the vertices.
* \param vids The vertex id array.
* \return the id arrays of the two endpoints of the edges.
* @brief Get the in edges of the vertices.
* @param vids The vertex id array.
* @return the id arrays of the two endpoints of the edges.
*/
virtual EdgeArray InEdges(IdArray vids) const = 0;
/*!
* \brief Get the out edges of the vertex.
* \note The returned src id array is filled with vid.
* \param vid The vertex id.
* \return the id arrays of the two endpoints of the edges.
* @brief Get the out edges of the vertex.
* @note The returned src id array is filled with vid.
* @param vid The vertex id.
* @return the id arrays of the two endpoints of the edges.
*/
virtual EdgeArray OutEdges(dgl_id_t vid) const = 0;
/*!
* \brief Get the out edges of the vertices.
* \param vids The vertex id array.
* \return the id arrays of the two endpoints of the edges.
* @brief Get the out edges of the vertices.
* @param vids The vertex id array.
* @return the id arrays of the two endpoints of the edges.
*/
virtual EdgeArray OutEdges(IdArray vids) const = 0;
/*!
* \brief Get all the edges in the graph.
* \note If order is "srcdst", the returned edges list is sorted by their src
* @brief Get all the edges in the graph.
* @note If order is "srcdst", the returned edges list is sorted by their src
* and dst ids. If order is "eid", they are in their edge id order.
* Otherwise, in the arbitrary order.
* \param order The order of the returned edge list.
* \return the id arrays of the two endpoints of the edges.
* @param order The order of the returned edge list.
* @return the id arrays of the two endpoints of the edges.
*/
virtual EdgeArray Edges(const std::string &order = "") const = 0;
/*!
* \brief Get the in degree of the given vertex.
* \param vid The vertex id.
* \return the in degree
* @brief Get the in degree of the given vertex.
* @param vid The vertex id.
* @return the in degree
*/
virtual uint64_t InDegree(dgl_id_t vid) const = 0;
/*!
* \brief Get the in degrees of the given vertices.
* \param vid The vertex id array.
* \return the in degree array
* @brief Get the in degrees of the given vertices.
* @param vid The vertex id array.
* @return the in degree array
*/
virtual DegreeArray InDegrees(IdArray vids) const = 0;
/*!
* \brief Get the out degree of the given vertex.
* \param vid The vertex id.
* \return the out degree
* @brief Get the out degree of the given vertex.
* @param vid The vertex id.
* @return the out degree
*/
virtual uint64_t OutDegree(dgl_id_t vid) const = 0;
/*!
* \brief Get the out degrees of the given vertices.
* \param vid The vertex id array.
* \return the out degree array
* @brief Get the out degrees of the given vertices.
* @param vid The vertex id array.
* @return the out degree array
*/
virtual DegreeArray OutDegrees(IdArray vids) const = 0;
/*!
* \brief Construct the induced subgraph of the given vertices.
* @brief Construct the induced subgraph of the given vertices.
*
* The induced subgraph is a subgraph formed by specifying a set of vertices
* V' and then selecting all of the edges from the original graph that connect
......@@ -329,13 +329,13 @@ class GraphInterface : public runtime::Object {
*
* The result subgraph is read-only.
*
* \param vids The vertices in the subgraph.
* \return the induced subgraph
* @param vids The vertices in the subgraph.
* @return the induced subgraph
*/
virtual Subgraph VertexSubgraph(IdArray vids) const = 0;
/*!
* \brief Construct the induced edge subgraph of the given edges.
* @brief Construct the induced edge subgraph of the given edges.
*
* The induced edges subgraph is a subgraph formed by specifying a set of
* edges E' and then selecting all of the nodes from the original graph that
......@@ -348,44 +348,44 @@ class GraphInterface : public runtime::Object {
*
* The result subgraph is read-only.
*
* \param eids The edges in the subgraph.
* \param preserve_nodes If true, the vertices will not be relabeled, so some
* @param eids The edges in the subgraph.
* @param preserve_nodes If true, the vertices will not be relabeled, so some
* vertices may have no incident edges.
* \return the induced edge subgraph
* @return the induced edge subgraph
*/
virtual Subgraph EdgeSubgraph(
IdArray eids, bool preserve_nodes = false) const = 0;
/*!
* \brief Return the successor vector
* \param vid The vertex id.
* \return the successor vector iterator pair.
* @brief Return the successor vector
* @param vid The vertex id.
* @return the successor vector iterator pair.
*/
virtual DGLIdIters SuccVec(dgl_id_t vid) const = 0;
/*!
* \brief Return the out edge id vector
* \param vid The vertex id.
* \return the out edge id vector iterator pair.
* @brief Return the out edge id vector
* @param vid The vertex id.
* @return the out edge id vector iterator pair.
*/
virtual DGLIdIters OutEdgeVec(dgl_id_t vid) const = 0;
/*!
* \brief Return the predecessor vector
* \param vid The vertex id.
* \return the predecessor vector iterator pair.
* @brief Return the predecessor vector
* @param vid The vertex id.
* @return the predecessor vector iterator pair.
*/
virtual DGLIdIters PredVec(dgl_id_t vid) const = 0;
/*!
* \brief Return the in edge id vector
* \param vid The vertex id.
* \return the in edge id vector iterator pair.
* @brief Return the in edge id vector
* @param vid The vertex id.
* @return the in edge id vector iterator pair.
*/
virtual DGLIdIters InEdgeVec(dgl_id_t vid) const = 0;
/*!
* \brief Get the adjacency matrix of the graph.
* @brief Get the adjacency matrix of the graph.
*
* By default, a row of returned adjacency matrix represents the destination
* of an edge and the column represents the source.
......@@ -396,15 +396,15 @@ class GraphInterface : public runtime::Object {
* If the fmt is 'coo', the function should return one array of shape (2,
* nnz), representing a horitonzal stack of row and col indices.
*
* \param transpose A flag to transpose the returned adjacency matrix.
* \param fmt the format of the returned adjacency matrix.
* \return a vector of IdArrays.
* @param transpose A flag to transpose the returned adjacency matrix.
* @param fmt the format of the returned adjacency matrix.
* @return a vector of IdArrays.
*/
virtual std::vector<IdArray> GetAdj(
bool transpose, const std::string &fmt) const = 0;
/*!
* \brief Sort the columns in CSR.
* @brief Sort the columns in CSR.
*
* This sorts the columns in each row based on the column Ids.
* The edge ids should be sorted accordingly.
......@@ -418,19 +418,19 @@ class GraphInterface : public runtime::Object {
// Define GraphRef
DGL_DEFINE_OBJECT_REF(GraphRef, GraphInterface);
/*! \brief Subgraph data structure */
/*! @brief Subgraph data structure */
struct Subgraph : public runtime::Object {
/*! \brief The graph. */
/*! @brief The graph. */
GraphPtr graph;
/*!
* \brief The induced vertex ids.
* \note This is also a map from the new vertex id to the vertex id in the
* @brief The induced vertex ids.
* @note This is also a map from the new vertex id to the vertex id in the
* parent graph.
*/
IdArray induced_vertices;
/*!
* \brief The induced edge ids.
* \note This is also a map from the new edge id to the edge id in the parent
* @brief The induced edge ids.
* @note This is also a map from the new edge id to the edge id in the parent
* graph.
*/
IdArray induced_edges;
......@@ -439,21 +439,21 @@ struct Subgraph : public runtime::Object {
DGL_DECLARE_OBJECT_TYPE_INFO(Subgraph, runtime::Object);
};
/*! \brief Subgraph data structure for negative subgraph */
/*! @brief Subgraph data structure for negative subgraph */
struct NegSubgraph : public Subgraph {
/*! \brief The existence of the negative edges in the parent graph. */
/*! @brief The existence of the negative edges in the parent graph. */
IdArray exist;
/*! \brief The Ids of head nodes */
/*! @brief The Ids of head nodes */
IdArray head_nid;
/*! \brief The Ids of tail nodes */
/*! @brief The Ids of tail nodes */
IdArray tail_nid;
};
/*! \brief Subgraph data structure for halo subgraph */
/*! @brief Subgraph data structure for halo subgraph */
struct HaloSubgraph : public Subgraph {
/*! \brief Indicate if a node belongs to the partition. */
/*! @brief Indicate if a node belongs to the partition. */
IdArray inner_nodes;
};
......
include/dgl/graph_op.h
View file @ 6c53f351
/*!
* Copyright (c) 2018 by Contributors
* \file dgl/graph_op.h
* \brief Operations on graph index.
* @file dgl/graph_op.h
* @brief Operations on graph index.
*/
#ifndef DGL_GRAPH_OP_H_
#define DGL_GRAPH_OP_H_
......@@ -16,30 +16,30 @@ namespace dgl {
class GraphOp {
public:
/*!
* \brief Return a new graph with all the edges reversed.
* @brief Return a new graph with all the edges reversed.
*
* The returned graph preserves the vertex and edge index in the original
* graph.
*
* \return the reversed graph
* @return the reversed graph
*/
static GraphPtr Reverse(GraphPtr graph);
/*!
* \brief Return the line graph.
* @brief Return the line graph.
*
* If i~j and j~i are two edges in original graph G, then
* (i,j)~(j,i) and (j,i)~(i,j) are the "backtracking" edges on
* the line graph.
*
* \param graph The input graph.
* \param backtracking Whether the backtracking edges are included or not
* \return the line graph
* @param graph The input graph.
* @param backtracking Whether the backtracking edges are included or not
* @return the line graph
*/
static GraphPtr LineGraph(GraphPtr graph, bool backtracking);
/*!
* \brief Return a disjoint union of the input graphs.
* @brief Return a disjoint union of the input graphs.
*
* The new graph will include all the nodes/edges in the given graphs.
* Nodes/Edges will be relabled by adding the cumsum of the previous graph
......@@ -50,13 +50,13 @@ class GraphOp {
* The input list must be either ALL mutable graphs or ALL immutable graphs.
* The returned graph type is also determined by the input graph type.
*
* \param graphs A list of input graphs to be unioned.
* \return the disjoint union of the graphs
* @param graphs A list of input graphs to be unioned.
* @return the disjoint union of the graphs
*/
static GraphPtr DisjointUnion(std::vector<GraphPtr> graphs);
/*!
* \brief Partition the graph into several subgraphs.
* @brief Partition the graph into several subgraphs.
*
* This is a reverse operation of DisjointUnion. The graph will be partitioned
* into num graphs. This requires the given number of partitions to evenly
......@@ -65,15 +65,15 @@ class GraphOp {
* If the input graph is mutable, the result graphs are mutable.
* If the input graph is immutable, the result graphs are immutable.
*
* \param graph The graph to be partitioned.
* \param num The number of partitions.
* \return a list of partitioned graphs
* @param graph The graph to be partitioned.
* @param num The number of partitions.
* @return a list of partitioned graphs
*/
static std::vector<GraphPtr> DisjointPartitionByNum(
GraphPtr graph, int64_t num);
/*!
* \brief Partition the graph into several subgraphs.
* @brief Partition the graph into several subgraphs.
*
* This is a reverse operation of DisjointUnion. The graph will be partitioned
* based on the given sizes. This requires the sum of the given sizes is equal
......@@ -82,28 +82,28 @@ class GraphOp {
* If the input graph is mutable, the result graphs are mutable.
* If the input graph is immutable, the result graphs are immutable.
*
* \param graph The graph to be partitioned.
* \param sizes The number of partitions.
* \return a list of partitioned graphs
* @param graph The graph to be partitioned.
* @param sizes The number of partitions.
* @return a list of partitioned graphs
*/
static std::vector<GraphPtr> DisjointPartitionBySizes(
GraphPtr graph, IdArray sizes);
/*!
* \brief Map vids in the parent graph to the vids in the subgraph.
* @brief Map vids in the parent graph to the vids in the subgraph.
*
* If the Id doesn't exist in the subgraph, -1 will be used.
*
* \param parent_vid_map An array that maps the vids in the parent graph to
* @param parent_vid_map An array that maps the vids in the parent graph to
* the subgraph. The elements store the vertex Ids in the parent graph, and
* the indices indicate the vertex Ids in the subgraph.
* \param query The vertex Ids in the parent graph.
* \return an Id array that contains the subgraph node Ids.
* @param query The vertex Ids in the parent graph.
* @return an Id array that contains the subgraph node Ids.
*/
static IdArray MapParentIdToSubgraphId(IdArray parent_vid_map, IdArray query);
/*!
* \brief Expand an Id array based on the offset array.
* @brief Expand an Id array based on the offset array.
*
* For example,
* ids: [0, 1, 2, 3, 4],
......@@ -112,68 +112,68 @@ class GraphOp {
* The offset array has one more element than the ids array.
* (offset[i], offset[i+1]) shows the location of ids[i] in the result array.
*
* \param ids An array that contains the node or edge Ids.
* \param offset An array that contains the offset after expansion.
* \return a expanded Id array.
* @param ids An array that contains the node or edge Ids.
* @param offset An array that contains the offset after expansion.
* @return a expanded Id array.
*/
static IdArray ExpandIds(IdArray ids, IdArray offset);
/*!
* \brief Convert the graph to a simple graph.
* \param graph The input graph.
* \return a new immutable simple graph with no multi-edge.
* @brief Convert the graph to a simple graph.
* @param graph The input graph.
* @return a new immutable simple graph with no multi-edge.
*/
static GraphPtr ToSimpleGraph(GraphPtr graph);
/*!
* \brief Convert the graph to a mutable bidirected graph.
* @brief Convert the graph to a mutable bidirected graph.
*
* If the original graph has m edges for i -> j and n edges for
* j -> i, the new graph will have max(m, n) edges for both
* i -> j and j -> i.
*
* \param graph The input graph.
* \return a new mutable bidirected graph.
* @param graph The input graph.
* @return a new mutable bidirected graph.
*/
static GraphPtr ToBidirectedMutableGraph(GraphPtr graph);
/*!
* \brief Same as BidirectedMutableGraph except that the returned graph is
* @brief Same as BidirectedMutableGraph except that the returned graph is
* immutable.
* \param graph The input graph.
* \return a new immutable bidirected
* @param graph The input graph.
* @return a new immutable bidirected
* graph.
*/
static GraphPtr ToBidirectedImmutableGraph(GraphPtr graph);
/*!
* \brief Same as BidirectedMutableGraph except that the returned graph is
* @brief Same as BidirectedMutableGraph except that the returned graph is
* immutable and call gk_csr_MakeSymmetric in GKlib. This is more efficient
* than ToBidirectedImmutableGraph. It return a null pointer if the conversion
* fails.
*
* \param graph The input graph.
* \return a new immutable bidirected graph.
* @param graph The input graph.
* @return a new immutable bidirected graph.
*/
static GraphPtr ToBidirectedSimpleImmutableGraph(ImmutableGraphPtr ig);
/*!
* \brief Get a induced subgraph with HALO nodes.
* @brief Get a induced subgraph with HALO nodes.
* The HALO nodes are the ones that can be reached from `nodes` within
* `num_hops`.
* \param graph The input graph.
* \param nodes The input nodes that form the core of the induced subgraph.
* \param num_hops The number of hops to reach.
* \return the induced subgraph with HALO nodes.
* @param graph The input graph.
* @param nodes The input nodes that form the core of the induced subgraph.
* @param num_hops The number of hops to reach.
* @return the induced subgraph with HALO nodes.
*/
static HaloSubgraph GetSubgraphWithHalo(
GraphPtr graph, IdArray nodes, int num_hops);
/*!
* \brief Reorder the nodes in the immutable graph.
* \param graph The input graph.
* \param new_order The node Ids in the new graph. The index in `new_order` is
* @brief Reorder the nodes in the immutable graph.
* @param graph The input graph.
* @param new_order The node Ids in the new graph. The index in `new_order` is
* old node Ids.
* \return the graph with reordered node Ids
* @return the graph with reordered node Ids
*/
static GraphPtr ReorderImmutableGraph(
ImmutableGraphPtr ig, IdArray new_order);
......
include/dgl/graph_traversal.h
View file @ 6c53f351
/*!
* Copyright (c) 2020 by Contributors
* \file dgl/graph_traversal.h
* \brief common graph traversal operations
* @file dgl/graph_traversal.h
* @brief common graph traversal operations
*/
#ifndef DGL_GRAPH_TRAVERSAL_H_
#define DGL_GRAPH_TRAVERSAL_H_
......@@ -13,7 +13,7 @@ namespace dgl {
///////////////////////// Graph Traverse routines //////////////////////////
/*!
* \brief Class for representing frontiers.
* @brief Class for representing frontiers.
*
* Each frontier is a list of nodes/edges (specified by their ids).
* An optional tag can be specified on each node/edge (represented by an int
......@@ -24,7 +24,7 @@ struct Frontiers {
IdArray ids;
/*!
* \brief a vector store for node/edge tags. Dtype is int64.
* @brief a vector store for node/edge tags. Dtype is int64.
* Empty if no tags are requested
*/
IdArray tags;
......@@ -36,43 +36,43 @@ struct Frontiers {
namespace aten {
/*!
* \brief Traverse the graph in a breadth-first-search (BFS) order.
* @brief Traverse the graph in a breadth-first-search (BFS) order.
*
* \param csr The input csr matrix.
* \param sources Source nodes.
* \return A Frontiers object containing the search result
* @param csr The input csr matrix.
* @param sources Source nodes.
* @return A Frontiers object containing the search result
*/
Frontiers BFSNodesFrontiers(const CSRMatrix& csr, IdArray source);
/*!
* \brief Traverse the graph in a breadth-first-search (BFS) order, returning
* @brief Traverse the graph in a breadth-first-search (BFS) order, returning
* the edges of the BFS tree.
*
* \param csr The input csr matrix.
* \param sources Source nodes.
* \return A Frontiers object containing the search result
* @param csr The input csr matrix.
* @param sources Source nodes.
* @return A Frontiers object containing the search result
*/
Frontiers BFSEdgesFrontiers(const CSRMatrix& csr, IdArray source);
/*!
* \brief Traverse the graph in topological order.
* @brief Traverse the graph in topological order.
*
* \param csr The input csr matrix.
* \return A Frontiers object containing the search result
* @param csr The input csr matrix.
* @return A Frontiers object containing the search result
*/
Frontiers TopologicalNodesFrontiers(const CSRMatrix& csr);
/*!
* \brief Traverse the graph in a depth-first-search (DFS) order.
* @brief Traverse the graph in a depth-first-search (DFS) order.
*
* \param csr The input csr matrix.
* \param sources Source nodes.
* \return A Frontiers object containing the search result
* @param csr The input csr matrix.
* @param sources Source nodes.
* @return A Frontiers object containing the search result
*/
Frontiers DGLDFSEdges(const CSRMatrix& csr, IdArray source);
/*!
* \brief Traverse the graph in a depth-first-search (DFS) order and return the
* @brief Traverse the graph in a depth-first-search (DFS) order and return the
* recorded edge tag if return_labels is specified.
*
* The traversal visit edges in its DFS order. Edges have three tags:
......@@ -84,12 +84,12 @@ Frontiers DGLDFSEdges(const CSRMatrix& csr, IdArray source);
* A NONTREE edge is one in which both `u` and `v` have been visisted but the
* edge is NOT in the DFS tree.
*
* \param csr The input csr matrix.
* \param sources Source nodes.
* \param has_reverse_edge If true, REVERSE edges are included
* \param has_nontree_edge If true, NONTREE edges are included
* \param return_labels If true, return the recorded edge tags.
* \return A Frontiers object containing the search result
* @param csr The input csr matrix.
* @param sources Source nodes.
* @param has_reverse_edge If true, REVERSE edges are included
* @param has_nontree_edge If true, NONTREE edges are included
* @param return_labels If true, return the recorded edge tags.
* @return A Frontiers object containing the search result
*/
Frontiers DGLDFSLabeledEdges(
const CSRMatrix& csr, IdArray source, const bool has_reverse_edge,
......
include/dgl/immutable_graph.h
View file @ 6c53f351
/*!
* Copyright (c) 2018 by Contributors
* \file dgl/immutable_graph.h
* \brief DGL immutable graph index class.
* @file dgl/immutable_graph.h
* @brief DGL immutable graph index class.
*/
#ifndef DGL_IMMUTABLE_GRAPH_H_
#define DGL_IMMUTABLE_GRAPH_H_
......@@ -30,7 +30,7 @@ class ImmutableGraph;
typedef std::shared_ptr<ImmutableGraph> ImmutableGraphPtr;
/*!
* \brief Graph class stored using CSR structure.
* @brief Graph class stored using CSR structure.
*/
class CSR : public GraphInterface {
public:
......@@ -180,40 +180,40 @@ class CSR : public GraphInterface {
return {adj_.indptr, adj_.indices, adj_.data};
}
/*! \brief Indicate whether this uses shared memory. */
/*! @brief Indicate whether this uses shared memory. */
bool IsSharedMem() const { return !shared_mem_name_.empty(); }
/*! \brief Return the reverse of this CSR graph (i.e, a CSC graph) */
/*! @brief Return the reverse of this CSR graph (i.e, a CSC graph) */
CSRPtr Transpose() const;
/*! \brief Convert this CSR to COO */
/*! @brief Convert this CSR to COO */
COOPtr ToCOO() const;
/*!
* \return the csr matrix that represents this graph.
* \note The csr matrix shares the storage with this graph.
* @return the csr matrix that represents this graph.
* @note The csr matrix shares the storage with this graph.
* The data field of the CSR matrix stores the edge ids.
*/
aten::CSRMatrix ToCSRMatrix() const { return adj_; }
/*!
* \brief Copy the data to another context.
* \param ctx The target context.
* \return The graph under another context.
* @brief Copy the data to another context.
* @param ctx The target context.
* @return The graph under another context.
*/
CSR CopyTo(const DGLContext &ctx) const;
/*!
* \brief Copy data to shared memory.
* \param name The name of the shared memory.
* \return The graph in the shared memory
* @brief Copy data to shared memory.
* @param name The name of the shared memory.
* @return The graph in the shared memory
*/
CSR CopyToSharedMem(const std::string &name) const;
/*!
* \brief Convert the graph to use the given number of bits for storage.
* \param bits The new number of integer bits (32 or 64).
* \return The graph with new bit size storage.
* @brief Convert the graph to use the given number of bits for storage.
* @param bits The new number of integer bits (32 or 64).
* @return The graph with new bit size storage.
*/
CSR AsNumBits(uint8_t bits) const;
......@@ -239,7 +239,7 @@ class CSR : public GraphInterface {
private:
friend class Serializer;
/*! \brief private default constructor */
/*! @brief private default constructor */
CSR() { adj_.sorted = false; }
// The internal CSR adjacency matrix.
// The data field stores edge ids.
......@@ -424,43 +424,43 @@ class COO : public GraphInterface {
}
}
/*! \brief Return the transpose of this COO */
/*! @brief Return the transpose of this COO */
COOPtr Transpose() const {
return COOPtr(new COO(adj_.num_rows, adj_.col, adj_.row));
}
/*! \brief Convert this COO to CSR */
/*! @brief Convert this COO to CSR */
CSRPtr ToCSR() const;
/*!
* \brief Get the coo matrix that represents this graph.
* \note The coo matrix shares the storage with this graph.
* @brief Get the coo matrix that represents this graph.
* @note The coo matrix shares the storage with this graph.
* The data field of the coo matrix is none.
*/
aten::COOMatrix ToCOOMatrix() const { return adj_; }
/*!
* \brief Copy the data to another context.
* \param ctx The target context.
* \return The graph under another context.
* @brief Copy the data to another context.
* @param ctx The target context.
* @return The graph under another context.
*/
COO CopyTo(const DGLContext &ctx) const;
/*!
* \brief Copy data to shared memory.
* \param name The name of the shared memory.
* \return The graph in the shared memory
* @brief Copy data to shared memory.
* @param name The name of the shared memory.
* @return The graph in the shared memory
*/
COO CopyToSharedMem(const std::string &name) const;
/*!
* \brief Convert the graph to use the given number of bits for storage.
* \param bits The new number of integer bits (32 or 64).
* \return The graph with new bit size storage.
* @brief Convert the graph to use the given number of bits for storage.
* @param bits The new number of integer bits (32 or 64).
* @return The graph with new bit size storage.
*/
COO AsNumBits(uint8_t bits) const;
/*! \brief Indicate whether this uses shared memory. */
/*! @brief Indicate whether this uses shared memory. */
bool IsSharedMem() const { return false; }
// member getters
......@@ -479,17 +479,17 @@ class COO : public GraphInterface {
};
/*!
* \brief DGL immutable graph index class.
* @brief DGL immutable graph index class.
*
* DGL's graph is directed. Vertices are integers enumerated from zero.
*/
class ImmutableGraph : public GraphInterface {
public:
/*! \brief Construct an immutable graph from the COO format. */
/*! @brief Construct an immutable graph from the COO format. */
explicit ImmutableGraph(COOPtr coo) : coo_(coo) {}
/*!
* \brief Construct an immutable graph from the CSR format.
* @brief Construct an immutable graph from the CSR format.
*
* For a single graph, we need two CSRs, one stores the in-edges of vertices
* and the other stores the out-edges of vertices. These two CSRs stores the
......@@ -506,14 +506,14 @@ class ImmutableGraph : public GraphInterface {
CHECK(in_csr_ || out_csr_) << "Both CSR are missing.";
}
/*! \brief Construct an immutable graph from one CSR. */
/*! @brief Construct an immutable graph from one CSR. */
explicit ImmutableGraph(CSRPtr csr) : out_csr_(csr) {}
/*! \brief default copy constructor */
/*! @brief default copy constructor */
ImmutableGraph(const ImmutableGraph &other) = default;
#ifndef _MSC_VER
/*! \brief default move constructor */
/*! @brief default move constructor */
ImmutableGraph(ImmutableGraph &&other) = default;
#else
ImmutableGraph(ImmutableGraph &&other) {
......@@ -526,10 +526,10 @@ class ImmutableGraph : public GraphInterface {
}
#endif // _MSC_VER
/*! \brief default assign constructor */
/*! @brief default assign constructor */
ImmutableGraph &operator=(const ImmutableGraph &other) = default;
/*! \brief default destructor */
/*! @brief default destructor */
~ImmutableGraph() = default;
void AddVertices(uint64_t num_vertices) override {
......@@ -553,18 +553,18 @@ class ImmutableGraph : public GraphInterface {
uint8_t NumBits() const override { return AnyGraph()->NumBits(); }
/*!
* \note not const since we have caches
* \return whether the graph is a multigraph
* @note not const since we have caches
* @return whether the graph is a multigraph
*/
bool IsMultigraph() const override { return AnyGraph()->IsMultigraph(); }
/*!
* \return whether the graph is read-only
* @return whether the graph is read-only
*/
bool IsReadonly() const override { return true; }
/**
* \brief Check if the graph is unibipartite.
* @brief Check if the graph is unibipartite.
*
* @return True if the graph is unibipartite.
*/
......@@ -606,34 +606,34 @@ class ImmutableGraph : public GraphInterface {
}
/*!
* \brief Find the predecessors of a vertex.
* \param vid The vertex id.
* \param radius The radius of the neighborhood. Default is immediate neighbor
* @brief Find the predecessors of a vertex.
* @param vid The vertex id.
* @param radius The radius of the neighborhood. Default is immediate neighbor
* (radius=1).
* \return the predecessor id array.
* @return the predecessor id array.
*/
IdArray Predecessors(dgl_id_t vid, uint64_t radius = 1) const override {
return GetInCSR()->Successors(vid, radius);
}
/*!
* \brief Find the successors of a vertex.
* \param vid The vertex id.
* \param radius The radius of the neighborhood. Default is immediate neighbor
* @brief Find the successors of a vertex.
* @param vid The vertex id.
* @param radius The radius of the neighborhood. Default is immediate neighbor
* (radius=1).
* \return the successor id array.
* @return the successor id array.
*/
IdArray Successors(dgl_id_t vid, uint64_t radius = 1) const override {
return GetOutCSR()->Successors(vid, radius);
}
/*!
* \brief Get all edge ids between the two given endpoints
* \note Edges are associated with an integer id start from zero.
* @brief Get all edge ids between the two given endpoints
* @note Edges are associated with an integer id start from zero.
* The id is assigned when the edge is being added to the graph.
* \param src The source vertex.
* \param dst The destination vertex.
* \return the edge id array.
* @param src The source vertex.
* @param dst The destination vertex.
* @return the edge id array.
*/
IdArray EdgeId(dgl_id_t src, dgl_id_t dst) const override {
if (in_csr_) {
......@@ -644,13 +644,13 @@ class ImmutableGraph : public GraphInterface {
}
/*!
* \brief Get all edge ids between the given endpoint pairs.
* \note Edges are associated with an integer id start from zero.
* @brief Get all edge ids between the given endpoint pairs.
* @note Edges are associated with an integer id start from zero.
* The id is assigned when the edge is being added to the graph.
* If duplicate pairs exist, the returned edge IDs will also duplicate.
* The order of returned edge IDs will follow the order of src-dst pairs
* first, and ties are broken by the order of edge ID.
* \return EdgeArray containing all edges between all pairs.
* @return EdgeArray containing all edges between all pairs.
*/
EdgeArray EdgeIds(IdArray src, IdArray dst) const override {
if (in_csr_) {
......@@ -662,9 +662,9 @@ class ImmutableGraph : public GraphInterface {
}
/*!
* \brief Find the edge ID and return the pair of endpoints
* \param eid The edge ID
* \return a pair whose first element is the source and the second the
* @brief Find the edge ID and return the pair of endpoints
* @param eid The edge ID
* @return a pair whose first element is the source and the second the
* destination.
*/
std::pair<dgl_id_t, dgl_id_t> FindEdge(dgl_id_t eid) const override {
......@@ -672,9 +672,9 @@ class ImmutableGraph : public GraphInterface {
}
/*!
* \brief Find the edge IDs and return their source and target node IDs.
* \param eids The edge ID array.
* \return EdgeArray containing all edges with id in eid. The order is
* @brief Find the edge IDs and return their source and target node IDs.
* @param eids The edge ID array.
* @return EdgeArray containing all edges with id in eid. The order is
* preserved.
*/
EdgeArray FindEdges(IdArray eids) const override {
......@@ -682,10 +682,10 @@ class ImmutableGraph : public GraphInterface {
}
/*!
* \brief Get the in edges of the vertex.
* \note The returned dst id array is filled with vid.
* \param vid The vertex id.
* \return the edges
* @brief Get the in edges of the vertex.
* @note The returned dst id array is filled with vid.
* @param vid The vertex id.
* @return the edges
*/
EdgeArray InEdges(dgl_id_t vid) const override {
const EdgeArray &ret = GetInCSR()->OutEdges(vid);
......@@ -693,9 +693,9 @@ class ImmutableGraph : public GraphInterface {
}
/*!
* \brief Get the in edges of the vertices.
* \param vids The vertex id array.
* \return the id arrays of the two endpoints of the edges.
* @brief Get the in edges of the vertices.
* @param vids The vertex id array.
* @return the id arrays of the two endpoints of the edges.
*/
EdgeArray InEdges(IdArray vids) const override {
const EdgeArray &ret = GetInCSR()->OutEdges(vids);
......@@ -703,72 +703,72 @@ class ImmutableGraph : public GraphInterface {
}
/*!
* \brief Get the out edges of the vertex.
* \note The returned src id array is filled with vid.
* \param vid The vertex id.
* \return the id arrays of the two endpoints of the edges.
* @brief Get the out edges of the vertex.
* @note The returned src id array is filled with vid.
* @param vid The vertex id.
* @return the id arrays of the two endpoints of the edges.
*/
EdgeArray OutEdges(dgl_id_t vid) const override {
return GetOutCSR()->OutEdges(vid);
}
/*!
* \brief Get the out edges of the vertices.
* \param vids The vertex id array.
* \return the id arrays of the two endpoints of the edges.
* @brief Get the out edges of the vertices.
* @param vids The vertex id array.
* @return the id arrays of the two endpoints of the edges.
*/
EdgeArray OutEdges(IdArray vids) const override {
return GetOutCSR()->OutEdges(vids);
}
/*!
* \brief Get all the edges in the graph.
* \note If sorted is true, the returned edges list is sorted by their src and
* @brief Get all the edges in the graph.
* @note If sorted is true, the returned edges list is sorted by their src and
* dst ids. Otherwise, they are in their edge id order.
* \param sorted Whether the returned edge list is sorted by their src and dst
* @param sorted Whether the returned edge list is sorted by their src and dst
* ids.
* \return the id arrays of the two endpoints of the edges.
* @return the id arrays of the two endpoints of the edges.
*/
EdgeArray Edges(const std::string &order = "") const override;
/*!
* \brief Get the in degree of the given vertex.
* \param vid The vertex id.
* \return the in degree
* @brief Get the in degree of the given vertex.
* @param vid The vertex id.
* @return the in degree
*/
uint64_t InDegree(dgl_id_t vid) const override {
return GetInCSR()->OutDegree(vid);
}
/*!
* \brief Get the in degrees of the given vertices.
* \param vid The vertex id array.
* \return the in degree array
* @brief Get the in degrees of the given vertices.
* @param vid The vertex id array.
* @return the in degree array
*/
DegreeArray InDegrees(IdArray vids) const override {
return GetInCSR()->OutDegrees(vids);
}
/*!
* \brief Get the out degree of the given vertex.
* \param vid The vertex id.
* \return the out degree
* @brief Get the out degree of the given vertex.
* @param vid The vertex id.
* @return the out degree
*/
uint64_t OutDegree(dgl_id_t vid) const override {
return GetOutCSR()->OutDegree(vid);
}
/*!
* \brief Get the out degrees of the given vertices.
* \param vid The vertex id array.
* \return the out degree array
* @brief Get the out degrees of the given vertices.
* @param vid The vertex id array.
* @return the out degree array
*/
DegreeArray OutDegrees(IdArray vids) const override {
return GetOutCSR()->OutDegrees(vids);
}
/*!
* \brief Construct the induced subgraph of the given vertices.
* @brief Construct the induced subgraph of the given vertices.
*
* The induced subgraph is a subgraph formed by specifying a set of vertices
* V' and then selecting all of the edges from the original graph that connect
......@@ -781,13 +781,13 @@ class ImmutableGraph : public GraphInterface {
*
* The result subgraph is read-only.
*
* \param vids The vertices in the subgraph.
* \return the induced subgraph
* @param vids The vertices in the subgraph.
* @return the induced subgraph
*/
Subgraph VertexSubgraph(IdArray vids) const override;
/*!
* \brief Construct the induced edge subgraph of the given edges.
* @brief Construct the induced edge subgraph of the given edges.
*
* The induced edges subgraph is a subgraph formed by specifying a set of
* edges E' and then selecting all of the nodes from the original graph that
......@@ -800,56 +800,56 @@ class ImmutableGraph : public GraphInterface {
*
* The result subgraph is read-only.
*
* \param eids The edges in the subgraph.
* \return the induced edge subgraph
* @param eids The edges in the subgraph.
* @return the induced edge subgraph
*/
Subgraph EdgeSubgraph(
IdArray eids, bool preserve_nodes = false) const override;
/*!
* \brief Return the successor vector
* \param vid The vertex id.
* \return the successor vector
* @brief Return the successor vector
* @param vid The vertex id.
* @return the successor vector
*/
DGLIdIters SuccVec(dgl_id_t vid) const override {
return GetOutCSR()->SuccVec(vid);
}
/*!
* \brief Return the out edge id vector
* \param vid The vertex id.
* \return the out edge id vector
* @brief Return the out edge id vector
* @param vid The vertex id.
* @return the out edge id vector
*/
DGLIdIters OutEdgeVec(dgl_id_t vid) const override {
return GetOutCSR()->OutEdgeVec(vid);
}
/*!
* \brief Return the predecessor vector
* \param vid The vertex id.
* \return the predecessor vector
* @brief Return the predecessor vector
* @param vid The vertex id.
* @return the predecessor vector
*/
DGLIdIters PredVec(dgl_id_t vid) const override {
return GetInCSR()->SuccVec(vid);
}
/*!
* \brief Return the in edge id vector
* \param vid The vertex id.
* \return the in edge id vector
* @brief Return the in edge id vector
* @param vid The vertex id.
* @return the in edge id vector
*/
DGLIdIters InEdgeVec(dgl_id_t vid) const override {
return GetInCSR()->OutEdgeVec(vid);
}
/*!
* \brief Get the adjacency matrix of the graph.
* @brief Get the adjacency matrix of the graph.
*
* By default, a row of returned adjacency matrix represents the destination
* of an edge and the column represents the source.
* \param transpose A flag to transpose the returned adjacency matrix.
* \param fmt the format of the returned adjacency matrix.
* \return a vector of three IdArray.
* @param transpose A flag to transpose the returned adjacency matrix.
* @param fmt the format of the returned adjacency matrix.
* @return a vector of three IdArray.
*/
std::vector<IdArray> GetAdj(
bool transpose, const std::string &fmt) const override;
......@@ -863,58 +863,58 @@ class ImmutableGraph : public GraphInterface {
/* !\brief Return coo. If not exist, create from csr.*/
COOPtr GetCOO() const;
/*! \brief Create an immutable graph from CSR. */
/*! @brief Create an immutable graph from CSR. */
static ImmutableGraphPtr CreateFromCSR(
IdArray indptr, IdArray indices, IdArray edge_ids,
const std::string &edge_dir);
static ImmutableGraphPtr CreateFromCSR(const std::string &shared_mem_name);
/*! \brief Create an immutable graph from COO. */
/*! @brief Create an immutable graph from COO. */
static ImmutableGraphPtr CreateFromCOO(
int64_t num_vertices, IdArray src, IdArray dst, bool row_osrted = false,
bool col_sorted = false);
/*!
* \brief Convert the given graph to an immutable graph.
* @brief Convert the given graph to an immutable graph.
*
* If the graph is already an immutable graph. The result graph will share
* the storage with the given one.
*
* \param graph The input graph.
* \return an immutable graph object.
* @param graph The input graph.
* @return an immutable graph object.
*/
static ImmutableGraphPtr ToImmutable(GraphPtr graph);
/*!
* \brief Copy the data to another context.
* \param ctx The target context.
* \return The graph under another context.
* @brief Copy the data to another context.
* @param ctx The target context.
* @return The graph under another context.
*/
static ImmutableGraphPtr CopyTo(ImmutableGraphPtr g, const DGLContext &ctx);
/*!
* \brief Copy data to shared memory.
* \param name The name of the shared memory.
* \return The graph in the shared memory
* @brief Copy data to shared memory.
* @param name The name of the shared memory.
* @return The graph in the shared memory
*/
static ImmutableGraphPtr CopyToSharedMem(
ImmutableGraphPtr g, const std::string &name);
/*!
* \brief Convert the graph to use the given number of bits for storage.
* \param bits The new number of integer bits (32 or 64).
* \return The graph with new bit size storage.
* @brief Convert the graph to use the given number of bits for storage.
* @param bits The new number of integer bits (32 or 64).
* @return The graph with new bit size storage.
*/
static ImmutableGraphPtr AsNumBits(ImmutableGraphPtr g, uint8_t bits);
/*!
* \brief Return a new graph with all the edges reversed.
* @brief Return a new graph with all the edges reversed.
*
* The returned graph preserves the vertex and edge index in the original
* graph.
*
* \return the reversed graph
* @return the reversed graph
*/
ImmutableGraphPtr Reverse() const;
......@@ -933,7 +933,7 @@ class ImmutableGraph : public GraphInterface {
bool HasOutCSR() const { return out_csr_ != NULL; }
/*! \brief Cast this graph to a heterograph */
/*! @brief Cast this graph to a heterograph */
HeteroGraphPtr AsHeteroGraph() const;
protected:
......
include/dgl/kernel.h
View file @ 6c53f351
/*!
* Copyright (c) 2020 by Contributors
* \file dgl/aten/kernel.h
* \brief Sparse matrix operators.
* @file dgl/aten/kernel.h
* @brief Sparse matrix operators.
*/
#ifndef DGL_KERNEL_H_
#define DGL_KERNEL_H_
......@@ -18,15 +18,15 @@ namespace dgl {
namespace aten {
/*!
* \brief Generalized Sparse Matrix-Matrix Multiplication.
* \param op The binary operator, could be `add`, `sub', `mul`, 'div',
* @brief Generalized Sparse Matrix-Matrix Multiplication.
* @param op The binary operator, could be `add`, `sub', `mul`, 'div',
* `copy_u`, `copy_e'.
* \param op The reduce operator, could be `sum`, `min`, `max'.
* \param graph The graph we apply SpMM on.
* \param ufeat The source node feature.
* \param efeat The edge feature.
* \param out The output feature on destination nodes.
* \param out_aux A list of NDArray's that contains auxiliary information such
* @param op The reduce operator, could be `sum`, `min`, `max'.
* @param graph The graph we apply SpMM on.
* @param ufeat The source node feature.
* @param efeat The edge feature.
* @param out The output feature on destination nodes.
* @param out_aux A list of NDArray's that contains auxiliary information such
* as the argmax on source nodes and edges for reduce operators such as
* `min` and `max`.
*/
......@@ -35,20 +35,20 @@ void SpMM(
NDArray ufeat, NDArray efeat, NDArray out, std::vector<NDArray> out_aux);
/*!
* \brief Generalized Sampled Dense-Dense Matrix Multiplication.
* \param op The binary operator, could be `add`, `sub', `mul`, 'div',
* @brief Generalized Sampled Dense-Dense Matrix Multiplication.
* @param op The binary operator, could be `add`, `sub', `mul`, 'div',
* `dot`, `copy_u`, `copy_e'.
* \param graph The graph we apply SpMM on.
* \param ufeat The source node feature.
* \param vfeat The destination node feature.
* \param out The output feature on edge.
* @param graph The graph we apply SpMM on.
* @param ufeat The source node feature.
* @param vfeat The destination node feature.
* @param out The output feature on edge.
*/
void SDDMM(
const std::string& op, HeteroGraphPtr graph, NDArray ufeat, NDArray efeat,
NDArray out);
/*!
* \brief Sparse-sparse matrix multiplication.
* @brief Sparse-sparse matrix multiplication.
*
* The sparse matrices must have scalar weights (i.e. \a A_weights and \a
* B_weights are 1D vectors.)
......@@ -57,7 +57,7 @@ std::pair<CSRMatrix, NDArray> CSRMM(
CSRMatrix A, NDArray A_weights, CSRMatrix B, NDArray B_weights);
/*!
* \brief Summing up a list of sparse matrices.
* @brief Summing up a list of sparse matrices.
*
* The sparse matrices must have scalar weights (i.e. the arrays in \a A_weights
* are 1D vectors.)
......
include/dgl/lazy.h
View file @ 6c53f351
/*!
* Copyright (c) 2019 by Contributors
* \file dgl/lazy.h
* \brief Lazy object that will be materialized only when being queried.
* @file dgl/lazy.h
* @brief Lazy object that will be materialized only when being queried.
*/
#ifndef DGL_LAZY_H_
#define DGL_LAZY_H_
......@@ -11,7 +11,7 @@
namespace dgl {
/*!
* \brief Lazy object that will be materialized only when being queried.
* @brief Lazy object that will be materialized only when being queried.
*
* The object should be immutable -- no mutation once materialized.
* The object is currently not threaad safe.
......@@ -23,7 +23,7 @@ class Lazy {
Lazy() {}
/*!
* \brief constructor to construct an object with given value (non-lazy case)
* @brief constructor to construct an object with given value (non-lazy case)
*/
explicit Lazy(const T& val) : ptr_(new T(val)) {}
......@@ -31,10 +31,10 @@ class Lazy {
~Lazy() = default;
/*!
* \brief Get the value of this object. If the object has not been
* @brief Get the value of this object. If the object has not been
* instantiated, using the provided function to create it.
* \param fn The creator function.
* \return the object value.
* @param fn The creator function.
* @return the object value.
*/
template <typename Fn>
const T& Get(Fn fn) {
......
include/dgl/nodeflow.h
View file @ 6c53f351
/*!
* Copyright (c) 2019 by Contributors
* \file dgl/nodeflow.h
* \brief DGL NodeFlow class.
* @file dgl/nodeflow.h
* @brief DGL NodeFlow class.
*/
#ifndef DGL_NODEFLOW_H_
#define DGL_NODEFLOW_H_
......@@ -18,7 +18,7 @@ namespace dgl {
class ImmutableGraph;
/*!
* \brief A NodeFlow graph stores the sampling results for a sampler that
* @brief A NodeFlow graph stores the sampling results for a sampler that
* samples nodes/edges in layers.
*
* We store multiple layers of the sampling results in a single graph, which
......@@ -26,22 +26,22 @@ class ImmutableGraph;
* node and edge mapping from the NodeFlow graph to the parent graph.
*/
struct NodeFlowObject : public runtime::Object {
/*! \brief The graph. */
/*! @brief The graph. */
GraphPtr graph;
/*!
* \brief the offsets of each layer.
* @brief the offsets of each layer.
*/
IdArray layer_offsets;
/*!
* \brief the offsets of each flow.
* @brief the offsets of each flow.
*/
IdArray flow_offsets;
/*!
* \brief The node mapping from the NodeFlow graph to the parent graph.
* @brief The node mapping from the NodeFlow graph to the parent graph.
*/
IdArray node_mapping;
/*!
* \brief The edge mapping from the NodeFlow graph to the parent graph.
* @brief The edge mapping from the NodeFlow graph to the parent graph.
*/
IdArray edge_mapping;
......@@ -54,14 +54,14 @@ class NodeFlow : public runtime::ObjectRef {
public:
DGL_DEFINE_OBJECT_REF_METHODS(NodeFlow, runtime::ObjectRef, NodeFlowObject);
/*! \brief create a new nodeflow reference */
/*! @brief create a new nodeflow reference */
static NodeFlow Create() {
return NodeFlow(std::make_shared<NodeFlowObject>());
}
};
/*!
* \brief Get a slice on a graph that represents a NodeFlow.
* @brief Get a slice on a graph that represents a NodeFlow.
*
* The entire block has to be taken as a slice. Users have to specify the
* correct starting and ending location of a layer.
......@@ -83,14 +83,14 @@ class NodeFlow : public runtime::ObjectRef {
* If fmt == "coo", the function returns two arrays: idx, eid. Here, the idx
* array is the concatenation of src and dst node id arrays.
*
* \param graph An immutable graph.
* \param fmt the format of the returned adjacency matrix.
* \param layer0_size the size of the first layer in the block.
* \param layer1_start the location where the second layer starts.
* \param layer1_end the location where the secnd layer ends.
* \param remap Indicates to remap all vertex ids and edge Ids to local Id
* @param graph An immutable graph.
* @param fmt the format of the returned adjacency matrix.
* @param layer0_size the size of the first layer in the block.
* @param layer1_start the location where the second layer starts.
* @param layer1_end the location where the secnd layer ends.
* @param remap Indicates to remap all vertex ids and edge Ids to local Id
* space.
* \return a vector of IdArrays.
* @return a vector of IdArrays.
*/
std::vector<IdArray> GetNodeFlowSlice(
const ImmutableGraph &graph, const std::string &fmt, size_t layer0_size,
......
include/dgl/packed_func_ext.h
View file @ 6c53f351
/*!
* Copyright (c) 2019 by Contributors
* \file packed_func_ext.h
* \brief Extension package to PackedFunc
* @file packed_func_ext.h
* @brief Extension package to PackedFunc
* This enables pass ObjectRef types into/from PackedFunc.
*/
#ifndef DGL_PACKED_FUNC_EXT_H_
......@@ -19,8 +19,8 @@
namespace dgl {
namespace runtime {
/*!
* \brief Runtime type checker for node type.
* \tparam T the type to be checked.
* @brief Runtime type checker for node type.
* @tparam T the type to be checked.
*/
template <typename T>
struct ObjectTypeChecker {
......
include/dgl/random.h
View file @ 6c53f351
/*!
* Copyright (c) 2017 by Contributors
* \file dgl/random.h
* \brief Random number generators
* @file dgl/random.h
* @brief Random number generators
*/
#ifndef DGL_RANDOM_H_
......@@ -36,36 +36,36 @@ inline uint32_t GetThreadId() {
}; // namespace
/*!
* \brief Thread-local Random Number Generator class
* @brief Thread-local Random Number Generator class
*/
class RandomEngine {
public:
/*! \brief Constructor with default seed */
/*! @brief Constructor with default seed */
RandomEngine() {
std::random_device rd;
SetSeed(rd());
}
/*! \brief Constructor with given seed */
/*! @brief Constructor with given seed */
explicit RandomEngine(uint32_t seed) { SetSeed(seed); }
/*! \brief Get the thread-local random number generator instance */
/*! @brief Get the thread-local random number generator instance */
static RandomEngine* ThreadLocal() {
return dmlc::ThreadLocalStore<RandomEngine>::Get();
}
/*!
* \brief Set the seed of this random number generator
* @brief Set the seed of this random number generator
*/
void SetSeed(uint32_t seed) { rng_.seed(seed + GetThreadId()); }
/*!
* \brief Generate an arbitrary random 32-bit integer.
* @brief Generate an arbitrary random 32-bit integer.
*/
int32_t RandInt32() { return static_cast<int32_t>(rng_()); }
/*!
* \brief Generate a uniform random integer in [0, upper)
* @brief Generate a uniform random integer in [0, upper)
*/
template <typename T>
T RandInt(T upper) {
......@@ -73,7 +73,7 @@ class RandomEngine {
}
/*!
* \brief Generate a uniform random integer in [lower, upper)
* @brief Generate a uniform random integer in [lower, upper)
*/
template <typename T>
T RandInt(T lower, T upper) {
......@@ -83,7 +83,7 @@ class RandomEngine {
}
/*!
* \brief Generate a uniform random float in [0, 1)
* @brief Generate a uniform random float in [0, 1)
*/
template <typename T>
T Uniform() {
......@@ -91,7 +91,7 @@ class RandomEngine {
}
/*!
* \brief Generate a uniform random float in [lower, upper)
* @brief Generate a uniform random float in [lower, upper)
*/
template <typename T>
T Uniform(T lower, T upper) {
......@@ -103,46 +103,46 @@ class RandomEngine {
}
/*!
* \brief Pick a random integer between 0 to N-1 according to given
* @brief Pick a random integer between 0 to N-1 according to given
* probabilities.
* \tparam IdxType Return integer type.
* \param prob Array of N unnormalized probability of each element. Must be
* @tparam IdxType Return integer type.
* @param prob Array of N unnormalized probability of each element. Must be
* non-negative.
* \return An integer randomly picked from 0 to N-1.
* @return An integer randomly picked from 0 to N-1.
*/
template <typename IdxType>
IdxType Choice(FloatArray prob);
/*!
* \brief Pick random integers between 0 to N-1 according to given
* @brief Pick random integers between 0 to N-1 according to given
* probabilities
*
* If replace is false, the number of picked integers must not larger than N.
*
* \tparam IdxType Id type
* \tparam FloatType Probability value type
* \param num Number of integers to choose
* \param prob Array of N unnormalized probability of each element. Must be
* @tparam IdxType Id type
* @tparam FloatType Probability value type
* @param num Number of integers to choose
* @param prob Array of N unnormalized probability of each element. Must be
* non-negative.
* \param out The output buffer to write selected indices.
* \param replace If true, choose with replacement.
* @param out The output buffer to write selected indices.
* @param replace If true, choose with replacement.
*/
template <typename IdxType, typename FloatType>
void Choice(IdxType num, FloatArray prob, IdxType* out, bool replace = true);
/*!
* \brief Pick random integers between 0 to N-1 according to given
* @brief Pick random integers between 0 to N-1 according to given
* probabilities
*
* If replace is false, the number of picked integers must not larger than N.
*
* \tparam IdxType Id type
* \tparam FloatType Probability value type
* \param num Number of integers to choose
* \param prob Array of N unnormalized probability of each element. Must be
* @tparam IdxType Id type
* @tparam FloatType Probability value type
* @param num Number of integers to choose
* @param prob Array of N unnormalized probability of each element. Must be
* non-negative.
* \param replace If true, choose with replacement.
* \return Picked indices
* @param replace If true, choose with replacement.
* @return Picked indices
*/
template <typename IdxType, typename FloatType>
IdArray Choice(IdxType num, FloatArray prob, bool replace = true) {
......@@ -154,30 +154,30 @@ class RandomEngine {
}
/*!
* \brief Pick random integers from population by uniform distribution.
* @brief Pick random integers from population by uniform distribution.
*
* If replace is false, num must not be larger than population.
*
* \tparam IdxType Return integer type
* \param num Number of integers to choose
* \param population Total number of elements to choose from.
* \param out The output buffer to write selected indices.
* \param replace If true, choose with replacement.
* @tparam IdxType Return integer type
* @param num Number of integers to choose
* @param population Total number of elements to choose from.
* @param out The output buffer to write selected indices.
* @param replace If true, choose with replacement.
*/
template <typename IdxType>
void UniformChoice(
IdxType num, IdxType population, IdxType* out, bool replace = true);
/*!
* \brief Pick random integers from population by uniform distribution.
* @brief Pick random integers from population by uniform distribution.
*
* If replace is false, num must not be larger than population.
*
* \tparam IdxType Return integer type
* \param num Number of integers to choose
* \param population Total number of elements to choose from.
* \param replace If true, choose with replacement.
* \return Picked indices
* @tparam IdxType Return integer type
* @param num Number of integers to choose
* @param population Total number of elements to choose from.
* @param replace If true, choose with replacement.
* @return Picked indices
*/
template <typename IdxType>
IdArray UniformChoice(IdxType num, IdxType population, bool replace = true) {
......@@ -190,7 +190,7 @@ class RandomEngine {
}
/*!
* \brief Pick random integers with different probability for different
* @brief Pick random integers with different probability for different
* segments.
*
* For example, if split=[0, 4, 10] and bias=[1.5, 1], it means to pick some
......@@ -210,13 +210,13 @@ class RandomEngine {
*
* If replace is false, num must not be larger than population.
*
* \tparam IdxType Return integer type
* \param num Number of integers to choose
* \param split Array of T+1 split positions of different segments(including
* @tparam IdxType Return integer type
* @param num Number of integers to choose
* @param split Array of T+1 split positions of different segments(including
* start and end)
* \param bias Array of T weight of each segments.
* \param out The output buffer to write selected indices.
* \param replace If true, choose with replacement.
* @param bias Array of T weight of each segments.
* @param out The output buffer to write selected indices.
* @param replace If true, choose with replacement.
*/
template <typename IdxType, typename FloatType>
void BiasedChoice(
......@@ -224,16 +224,16 @@ class RandomEngine {
bool replace = true);
/*!
* \brief Pick random integers with different probability for different
* @brief Pick random integers with different probability for different
* segments.
*
* If replace is false, num must not be larger than population.
*
* \tparam IdxType Return integer type
* \param num Number of integers to choose
* \param split Split positions of different segments
* \param bias Weights of different segments
* \param replace If true, choose with replacement.
* @tparam IdxType Return integer type
* @param num Number of integers to choose
* @param split Split positions of different segments
* @param bias Weights of different segments
* @param replace If true, choose with replacement.
*/
template <typename IdxType, typename FloatType>
IdArray BiasedChoice(
......
include/dgl/runtime/c_backend_api.h
View file @ 6c53f351
/*!
* Copyright (c) 2017 by Contributors
* \file dgl/runtime/c_backend_api.h
* \brief DGL runtime backend API.
* @file dgl/runtime/c_backend_api.h
* @brief DGL runtime backend API.
*
* The functions defined in this header are intended to be
* used by compiled dgl operators, usually user do not need to use these
......@@ -18,109 +18,109 @@ extern "C" {
// Backend related functions.
/*!
* \brief Backend function for modules to get function
* @brief Backend function for modules to get function
* from its environment mod_node (its imports and global function).
* The user do should not call DGLFuncFree on func.
*
* \param mod_node The module handle.
* \param func_name The name of the function.
* \param out The result function.
* \return 0 when no error is thrown, -1 when failure happens
* @param mod_node The module handle.
* @param func_name The name of the function.
* @param out The result function.
* @return 0 when no error is thrown, -1 when failure happens
*/
DGL_DLL int DGLBackendGetFuncFromEnv(
void* mod_node, const char* func_name, DGLFunctionHandle* out);
/*!
* \brief Backend function to register system-wide library symbol.
* @brief Backend function to register system-wide library symbol.
*
* \param name The name of the symbol
* \param ptr The symbol address.
* \return 0 when no error is thrown, -1 when failure happens
* @param name The name of the symbol
* @param ptr The symbol address.
* @return 0 when no error is thrown, -1 when failure happens
*/
DGL_DLL int DGLBackendRegisterSystemLibSymbol(const char* name, void* ptr);
/*!
* \brief Backend function to allocate temporal workspace.
* @brief Backend function to allocate temporal workspace.
*
* \note The result allocate spaced is ensured to be aligned to
* @note The result allocate spaced is ensured to be aligned to
* kTempAllocaAlignment.
*
* \param nbytes The size of the space requested.
* \param device_type The device type which the space will be allocated.
* \param device_id The device id which the space will be allocated.
* \param dtype_code_hint The type code of the array elements. Only used in
* @param nbytes The size of the space requested.
* @param device_type The device type which the space will be allocated.
* @param device_id The device id which the space will be allocated.
* @param dtype_code_hint The type code of the array elements. Only used in
* certain backends such as OpenGL.
* \param dtype_bits_hint The type bits of the array elements. Only used in
* @param dtype_bits_hint The type bits of the array elements. Only used in
* certain backends such as OpenGL.
* \return nullptr when error is thrown, a valid ptr if success
* @return nullptr when error is thrown, a valid ptr if success
*/
DGL_DLL void* DGLBackendAllocWorkspace(
int device_type, int device_id, uint64_t nbytes, int dtype_code_hint,
int dtype_bits_hint);
/*!
* \brief Backend function to free temporal workspace.
* @brief Backend function to free temporal workspace.
*
* \param ptr The result allocated space pointer.
* \param device_type The device type which the space will be allocated.
* \param device_id The device id which the space will be allocated.
* \return 0 when no error is thrown, -1 when failure happens
* @param ptr The result allocated space pointer.
* @param device_type The device type which the space will be allocated.
* @param device_id The device id which the space will be allocated.
* @return 0 when no error is thrown, -1 when failure happens
*
* \sa DGLBackendAllocWorkspace
*/
DGL_DLL int DGLBackendFreeWorkspace(int device_type, int device_id, void* ptr);
/*!
* \brief Environment for DGL parallel task.
* @brief Environment for DGL parallel task.
*/
typedef struct {
/*!
* \brief Auxiliary used for synchronization
* @brief Auxiliary used for synchronization
*/
void* sync_handle;
/*! \brief total amount of task */
/*! @brief total amount of task */
int32_t num_task;
} DGLParallelGroupEnv;
/*!
* \brief The callback function to execute a parallel lambda
* \param task_id the task id of the function.
* \param penv The parallel environment backs the execution.
* \param cdata The supporting closure data.
* @brief The callback function to execute a parallel lambda
* @param task_id the task id of the function.
* @param penv The parallel environment backs the execution.
* @param cdata The supporting closure data.
*/
typedef int (*FDGLParallelLambda)(
int task_id, DGLParallelGroupEnv* penv, void* cdata);
/*!
* \brief Backend function for running parallel jobs.
* @brief Backend function for running parallel jobs.
*
* \param flambda The parallel function to be launched.
* \param cdata The closure data.
* \param num_task Number of tasks to launch, can be 0, means launch
* @param flambda The parallel function to be launched.
* @param cdata The closure data.
* @param num_task Number of tasks to launch, can be 0, means launch
* with all available threads.
*
* \return 0 when no error is thrown, -1 when failure happens
* @return 0 when no error is thrown, -1 when failure happens
*/
DGL_DLL int DGLBackendParallelLaunch(
FDGLParallelLambda flambda, void* cdata, int num_task);
/*!
* \brief BSP barrrier between parallel threads
* \param task_id the task id of the function.
* \param penv The parallel environment backs the execution.
* \return 0 when no error is thrown, -1 when failure happens
* @brief BSP barrrier between parallel threads
* @param task_id the task id of the function.
* @param penv The parallel environment backs the execution.
* @return 0 when no error is thrown, -1 when failure happens
*/
DGL_DLL int DGLBackendParallelBarrier(int task_id, DGLParallelGroupEnv* penv);
/*!
* \brief Simple static initialization fucntion.
* @brief Simple static initialization fucntion.
* Run f once and set handle to be not null.
* This function is mainly used for test purpose.
*
* \param handle An global address to indicate f
* \param f The function to be ran
* \param cdata The closure data to pass to the function.
* \param nbytes Number of bytes in the closure data.
* \return 0 when no error is thrown, -1 when failure happens
* @param handle An global address to indicate f
* @param f The function to be ran
* @param cdata The closure data to pass to the function.
* @param nbytes Number of bytes in the closure data.
* @return 0 when no error is thrown, -1 when failure happens
*/
DGL_DLL int DGLBackendRunOnce(
void** handle, int (*f)(void*), void* cdata, int nbytes);
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment