documents API files and some doxygen updates

ShadenSmith · May 10, 2016 · a5d4ac0e9f28a1f6c26b484992a5a37dba9b3d7d · a5d4ac0
1 parent e7a84ef
commit a5d4ac0e9f28a1f6c26b484992a5a37dba9b3d7d
diff --git a/doxygen/40api.dox b/doxygen/40api.dox
@@ -49,7 +49,9 @@ array of type `double` to set various options.
 <!-- ----------------------------------------------------------------------------- -->
 \section api-data Data Structures
 
-\subpage api_struct_list
+\subpage api_csf_list
+
+\subpage api_kruskal_list
 
 
 <!-- ----------------------------------------------------------------------------- -->
@@ -58,8 +60,8 @@ array of type `double` to set various options.
 \subpage api_fact_list
 
 <!-- ----------------------------------------------------------------------------- -->
-\section api-ops Tensor Operations
+\section api-ops Tensor Kernels
 
-\subpage api_op_list
+\subpage api_kernel_list
 
 */
diff --git a/doxygen/50mpi.dox b/doxygen/50mpi.dox
@@ -61,7 +61,7 @@ number of OpenMP threads should be throttled with the `-t <nthreads>` flag.
 
 \subsection mpidist Selecting the Decomposition Dimensions
 By default, \splatt uses a medium-grained decomposition of the tensor which
-is formed by intersecting 1D partitions of each tensor mode \cite smith2015dms.
+is formed by intersecting 1D partitions of each tensor mode \cite smith2016dms.
 \splatt will attempt to find an assignment of ranks that leads to a small
 communication volume. If you wish to use a custom decomposition dimension, we
 provide a `-d` flag.

diff --git a/doxygen/80cite.dox b/doxygen/80cite.dox
@@ -7,6 +7,6 @@ If you have used \splatt in any of your
 
 \cite smith2015splatt
 \cite smith2015csf
-\cite smith2015dms
+\cite smith2016dms
 
 */
diff --git a/doxygen/Doxyfile b/doxygen/Doxyfile
@@ -38,7 +38,7 @@ PROJECT_NAME           = "SPLATT - The Surprisingly ParalleL spArse Tensor Toolk
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = "Release 1.0"
+PROJECT_NUMBER         = "Release 2.0"
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
@@ -766,7 +766,8 @@ WARN_LOGFILE           =
 # Note: If this tag is empty the current directory is searched.
 
 INPUT                  = ./ \
-                         ../include/splatt.h
+                         ../include/splatt.h \
+                         ../include/splatt/
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

diff --git a/doxygen/splatt.bib b/doxygen/splatt.bib
@@ -15,10 +15,9 @@ @inproceedings{smith2015csf
   year={2015}
 }
 
-@techreport{smith2015dms,
-  title={{DMS}: Distributed Sparse Tensor Factorization with Alternating Least Squares},
-  author={Smith, Shaden and Karypis, George},
-  school={University of Minnesota, Department of Computer Science \& Engineering},
-  year={2015}
+@article{smith2016dms,
+	title={A Medium-Grained Algorithm for Distributed Sparse Tensor Factorization},
+  author={\textbf{Shaden Smith} and Karypis, George},
+  journal={30th IEEE International Parallel \& Distributed Processing Symposium},
+  year={2016}
 }
-
diff --git a/include/splatt.h b/include/splatt.h
@@ -1,3 +1,13 @@
+/**
+* @file splatt.h
+* @brief Entry point and main include of SPLATT API.
+* @author Shaden Smith <shaden@cs.umn.edu>
+* @version 2.0.0
+* @date 2016-05-10
+*/
+
+
+
 #ifndef SPLATT_SPLATT_H
 #define SPLATT_SPLATT_H
 
@@ -15,23 +25,13 @@
 #endif
 
 
-/******************************************************************************
- * VERSION
- *****************************************************************************/
-#define SPLATT_VER_MAJOR     1
-#define SPLATT_VER_MINOR     1
-#define SPLATT_VER_SUBMINOR  1
-
-
 
 
 
 /******************************************************************************
- * SPLATT MODULES
+ * TYPES & MACROS
  *****************************************************************************/
 
-
-/* types & structures */
 #include "splatt/types.h"
 #include "splatt/constants.h"
 #include "splatt/structs.h"

diff --git a/include/splatt/api_csf.h b/include/splatt/api_csf.h
@@ -1,3 +1,13 @@
+/**
+* @file api_csf.h
+* @brief Functions for manipulating tensors stored in CSF form.
+* @author Shaden Smith <shaden@cs.umn.edu>
+* @version 2.0.0
+* @date 2016-05-10
+*/
+
+
+
 #ifndef SPLATT_SPLATT_CSF_H
 #define SPLATT_SPLATT_CSF_H
 
@@ -64,8 +74,8 @@ int splatt_csf_convert(
 /**
 * @brief Free all memory allocated for a tensor in CSF form.
 *
-* @param csf The tensor(s) to free.
-* @param opts opts[SPLATT_OPTION_CSF_ALLOC] tells us how many tensors are
+* @param tensors The tensor(s) to free.
+* @param options opts[SPLATT_OPTION_CSF_ALLOC] tells us how many tensors are
 *             allocated.
 */
 void splatt_free_csf(

diff --git a/include/splatt/api_factorization.h b/include/splatt/api_factorization.h
@@ -1,3 +1,13 @@
+/**
+* @file api_factorization.h
+* @brief Functinos for performing tensor factorizations.
+* @author Shaden Smith <shaden@cs.umn.edu>
+* @version 2.0.0
+* @date 2016-05-10
+*/
+
+
+
 #ifndef SPLATT_SPLATT_FACTORIZATION_H
 #define SPLATT_SPLATT_FACTORIZATION_H
 
@@ -21,10 +31,8 @@ extern "C" {
 /**
 * @brief Compute the CPD using alternating least squares.
 *
-* @param nfactors The rank of the decomposition to perform.
-* @param nmodes The number of modes in the tensor. Optimizations are currently
-*               only present for nmodes=3.
 * @param tensors An array of splatt_csf created by SPLATT.
+* @param nfactors The rank of the decomposition to perform.
 * @param options Options array for SPLATT.
 * @param[out] factored The factored tensor in Kruskal format.
 *

diff --git a/include/splatt/api_kernels.h b/include/splatt/api_kernels.h
@@ -1,3 +1,13 @@
+/**
+* @file api_kernels.h
+* @brief Functions for performing tensor kernels (e.g., norm, MTTKRP, TTMc).
+* @author Shaden Smith <shaden@cs.umn.edu>
+* @version 2.0.0
+* @date 2016-05-10
+*/
+
+
+
 #ifndef SPLATT_SPLATT_KERNELS_H
 #define SPLATT_SPLATT_KERNELS_H
 
@@ -13,7 +23,7 @@ extern "C" {
 
 
 /**
-\defgroup api_op_list List of functions for tensor operations.
+\defgroup api_kernel_list List of functions for tensor kernels.
 @{
 */
 
@@ -23,7 +33,7 @@ extern "C" {
 *
 * @param mode Which mode we are operating on.
 * @param ncolumns How many columns each matrix has ('nfactors').
-* @param tensor The CSF tensor to multipy with.
+* @param tensors The CSF tensor to multipy with.
 * @param matrices The row-major dense matrices to multiply with.
 * @param[out] matout The output matrix.
 * @param options SPLATT options array.

diff --git a/include/splatt/api_kruskal.h b/include/splatt/api_kruskal.h
@@ -1,3 +1,13 @@
+/**
+* @file api_kruskal.h
+* @brief Functions for manipulating tensors stored in Kruskal form (after CPD).
+* @author Shaden Smith <shaden@cs.umn.edu>
+* @version 2.0.0
+* @date 2016-05-10
+*/
+
+
+
 #ifndef SPLATT_SPLATT_KRUSKAL_H
 #define SPLATT_SPLATT_KRUSKAL_H
 

diff --git a/include/splatt/api_mpi.h b/include/splatt/api_mpi.h
@@ -1,3 +1,13 @@
+/**
+* @file api_mpi.h
+* @brief Functions for distributed-memory SPLATT (MPI).
+* @author Shaden Smith <shaden@cs.umn.edu>
+* @version 2.0.0
+* @date 2016-05-10
+*/
+
+
+
 #ifndef SPLATT_SPLATT_MPI_H
 #define SPLATT_SPLATT_MPI_H
 

diff --git a/include/splatt/api_options.h b/include/splatt/api_options.h
@@ -1,3 +1,13 @@
+/**
+* @file api_options.h
+* @brief Functions for supplying optional parameters to the SPLATT API.
+* @author Shaden Smith <shaden@cs.umn.edu>
+* @version 2.0.0
+* @date 2016-05-10
+*/
+
+
+
 #ifndef SPLATT_SPLATT_OPTION_H
 #define SPLATT_SPLATT_OPTION_H
 

diff --git a/include/splatt/api_version.h b/include/splatt/api_version.h
@@ -1,12 +1,33 @@
+/**
+* @file api_version.h
+* @brief Functions and macros for querying SPLATT version information.
+* @author Shaden Smith <shaden@cs.umn.edu>
+* @version 2.0.0
+* @date 2016-05-10
+*/
+
 #ifndef SPLATT_SPLATT_VERSION_H
 #define SPLATT_SPLATT_VERSION_H
 
 
-/*
- * VERSION API
- */
 
 
+/******************************************************************************
+ * MACROS
+ *****************************************************************************/
+#define SPLATT_VER_MAJOR     2
+#define SPLATT_VER_MINOR     0
+#define SPLATT_VER_SUBMINOR  0
+
+
+
+
+
+
+/******************************************************************************
+ * API - useful for shared libraries
+ *****************************************************************************/
+
 
 #ifdef __cplusplus
 extern "C" {

diff --git a/include/splatt/constants.h b/include/splatt/constants.h
@@ -1,3 +1,13 @@
+/**
+* @file constants.h
+* @brief Constants and macros used in SPLATT.
+* @author Shaden Smith <shaden@cs.umn.edu>
+* @version 2.0.0
+* @date 2016-05-10
+*/
+
+
+
 #ifndef SPLATT_SPLATT_CONSTANTS_H
 #define SPLATT_SPLATT_CONSTANTS_H
 

diff --git a/include/splatt/structs.h b/include/splatt/structs.h
@@ -1,3 +1,13 @@
+/**
+* @file structs.h
+* @brief Structures used by SPLATT.
+* @author Shaden Smith <shaden@cs.umn.edu>
+* @version 2.0.0
+* @date 2016-05-10
+*/
+
+
+
 #ifndef SPLATT_SPLATT_STRUCTS_H
 #define SPLATT_SPLATT_STRUCTS_H
 

diff --git a/include/splatt/types.h b/include/splatt/types.h
@@ -1,3 +1,13 @@
+/**
+* @file types.h
+* @brief Primitive data types used by SPLATT.
+* @author Shaden Smith <shaden@cs.umn.edu>
+* @version 2.0.0
+* @date 2016-05-10
+*/
+
+
+
 #ifndef SPLATT_SPLATT_TYPES_H
 #define SPLATT_SPLATT_TYPES_H