diff --git a/docs/conf.py b/docs/conf.py index efb406329b..59377e4f11 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,11 +18,11 @@ # -- Project information ----------------------------------------------------- project = 'Kokkos Kernels' -copyright = '2021, Evan Harvey' -author = 'Evan Harvey' +copyright = '2022, Kokkos Development Team' +author = 'Kokkos Team' # The full version, including alpha/beta/rc tags -release = 'v3.4.1' +release = 'latest' # -- General configuration --------------------------------------------------- diff --git a/docs/developer/apidocs.rst b/docs/developer/apidocs.rst new file mode 100644 index 0000000000..82797c5801 --- /dev/null +++ b/docs/developer/apidocs.rst @@ -0,0 +1,14 @@ +Source Code Documentation +========================= + +The source documentation is extracted from the C++ files using Doxygen. + +.. toctree:: + :maxdepth: 4 + + apidocs/blas1 + apidocs/blas2 + apidocs/blas3 + apidocs/sparse + apidocs/batched_dense + apidocs/batched_sparse \ No newline at end of file diff --git a/docs/developer/apidocs/batched_dense.rst b/docs/developer/apidocs/batched_dense.rst new file mode 100644 index 0000000000..1d65842061 --- /dev/null +++ b/docs/developer/apidocs/batched_dense.rst @@ -0,0 +1,257 @@ +BATCHED -- KokkosKernels batched functor-level interfaces +========================================================= + +innerlu +------- +CodeCleanup-TODO: Move Decl file to dense/impl/KokkosBatched_InnerLU_Internal.hpp + +applypivot +---------- +.. doxygenstruct:: KokkosBatched::TeamVectorApplyPivot + :members: + +qr_withcolumnpivoting +--------------------- +.. doxygenstruct:: KokkosBatched::TeamVectorQR_WithColumnPivoting + :members: + +addradial +--------- +.. doxygenstruct:: KokkosBatched::SerialAddRadial + :members: +.. doxygenstruct:: KokkosBatched::TeamAddRadial + :members: + +householder +----------- +.. doxygenstruct:: KokkosBatched::SerialHouseholder + :members: +.. doxygenstruct:: KokkosBatched::TeamVectorHouseholder + :members: + +set +--- +.. doxygenstruct:: KokkosBatched::SerialSet + :members: +.. doxygenstruct:: KokkosBatched::TeamSet + :members: +.. doxygenstruct:: KokkosBatched::TeamVectorSet + :members: + +scale +----- +.. doxygenstruct:: KokkosBatched::SerialScale + :members: +.. doxygenstruct:: KokkosBatched::TeamScale + :members: +.. doxygenstruct:: KokkosBatched::TeamVectorScale + :members: + +setidentity +----------- +.. doxygenstruct:: KokkosBatched::SerialSetIdentity + :members: +.. doxygenstruct:: KokkosBatched::TeamSetIdentity + :members: +.. doxygenstruct:: KokkosBatched::SetIdentity + :members: + +applyhouseholder +---------------- +.. doxygenstruct:: KokkosBatched::SerialApplyHouseholder + :members: +.. doxygenstruct:: KokkosBatched::TeamVectorApplyHouseholder + :members: + +innermultipledotproduct +----------------------- +CodeCleanup-TODO: Move Decl file to dense/impl/KokkosBatched_InnerMultipleDotProduct_Internal.hpp + +lu +-- +.. doxygenstruct:: KokkosBatched::SerialLU + :members: +.. doxygenstruct:: KokkosBatched::TeamLU + :members: +.. doxygenstruct:: KokkosBatched::LU + :members: + +solveutv +-------- +.. doxygenstruct:: KokkosBatched::TeamVectorSolveUTV + :members: + +utv +--- +.. doxygenstruct:: KokkosBatched::TeamVectorUTV + :members: + +inverselu +--------- +CodeCleanup-TODO: Move Decl file to dense/impl/KokkosBatched_InverseLU_Internal.hpp + +svd +--- +.. doxygenstruct:: KokkosBatched::SerialSVD + :members: + +eigendecomposition +------------------ +.. doxygenstruct:: KokkosBatched::SerialEigendecomposition + :members: +.. doxygenstruct:: KokkosBatched::TeamVectorEigendecomposition + :members: + +trtri +----- +.. doxygenstruct:: KokkosBatched::SerialTrtri + :members: + +qr +-- +.. doxygenstruct:: KokkosBatched::SerialQR + :members: +.. doxygenstruct:: KokkosBatched::TeamQR + :members: +.. doxygenstruct:: KokkosBatched::TeamVectorQR + :members: +.. doxygenstruct:: KokkosBatched::QR + :members: + +trmm +---- +.. doxygenstruct:: KokkosBatched::SerialTrmm + :members: + +trsm +---- +.. doxygenstruct:: KokkosBatched::SerialTrsm + :members: +.. doxygenstruct:: KokkosBatched::TeamTrsm + :members: +.. doxygenstruct:: KokkosBatched::TeamVectorTrsm + :members: +.. doxygenstruct:: KokkosBatched::Trsm + :members: + +innergemmfixa +------------- +CodeCleanup-TODO: Move Decl file to dense/impl/KokkosBatched_InnerGemmFixA_Internal.hpp + +innergemmfixb +------------- +CodeCleanup-TODO: Move Decl file to dense/impl/KokkosBatched_InnerGemmFixB_Internal.hpp + +innergemmfixc +------------- +CodeCleanup-TODO: Move Decl file to dense/impl/KokkosBatched_InnerGemmFixC_Internal.hpp + +applyq +------ +.. doxygenstruct:: KokkosBatched::SerialApplyQ + :members: +.. doxygenstruct:: KokkosBatched::TeamApplyQ + :members: +.. doxygenstruct:: KokkosBatched::TeamVectorApplyQ + :members: +.. doxygenstruct:: KokkosBatched::ApplyQ + :members: + +copy +---- +.. doxygenstruct:: KokkosBatched::SerialCopy + :members: +.. doxygenstruct:: KokkosBatched::TeamCopy + :members: +.. doxygenstruct:: KokkosBatched::TeamVectorCopy + :members: +.. doxygenstruct:: KokkosBatched::Copy + :members: + +innertrsm +--------- +CodeCleanup-TODO: Move Decl file to dense/impl/KokkosBatched_InnerTrsm_Internal.hpp + +solvelu +------- +.. doxygenstruct:: KokkosBatched::SerialSolveLU + :members: +.. doxygenstruct:: KokkosBatched::TeamSolveLU + :members: +.. doxygenstruct:: KokkosBatched::SolveLU + :members: + +xpay +---- +.. doxygenstruct:: KokkosBatched::SerialXpay + :members: +.. doxygenstruct:: KokkosBatched::TeamXpay + :members: +.. doxygenstruct:: KokkosBatched::TeamVectorXpay + :members: + +axpy +---- +.. doxygenstruct:: KokkosBatched::SerialAxpy + :members: +.. doxygenstruct:: KokkosBatched::TeamAxpy + :members: +.. doxygenstruct:: KokkosBatched::TeamVectorAxpy + :members: + +gemv +---- +.. doxygenstruct:: KokkosBatched::SerialGemv + :members: +.. doxygenstruct:: KokkosBatched::TeamGemv + :members: +.. doxygenstruct:: KokkosBatched::TeamVectorGemv + :members: +.. doxygenstruct:: KokkosBatched::Gemv + :members: + +dot +--- +.. doxygenstruct:: KokkosBatched::SerialDot + :members: +.. doxygenstruct:: KokkosBatched::TeamDot + :members: +.. doxygenstruct:: KokkosBatched::TeamVectorDot + :members: + +hadamardproduct +--------------- +.. doxygenstruct:: KokkosBatched::SerialHadamardProduct + :members: +.. doxygenstruct:: KokkosBatched::TeamHadamardProduct + :members: +.. doxygenstruct:: KokkosBatched::TeamVectorHadamardProduct + :members: +.. doxygenstruct:: KokkosBatched::HadamardProduct + :members: + +vector +------ +CodeCleanup-TODO: Move Decl file to dense/impl/ + +trsv +---- +.. doxygenstruct:: KokkosBatched::SerialTrsv + :members: +.. doxygenstruct:: KokkosBatched::TeamTrsv + :members: +.. doxygenstruct:: KokkosBatched::TeamVectorTrsv + :members: +.. doxygenstruct:: KokkosBatched::Trsv + :members: + +gemm +---- +.. doxygenstruct:: KokkosBatched::SerialGemm + :members: +.. doxygenstruct:: KokkosBatched::TeamGemm + :members: +.. doxygenstruct:: KokkosBatched::TeamVectorGemm + :members: +.. doxygenstruct:: KokkosBatched::Gemm + :members: \ No newline at end of file diff --git a/docs/developer/apidocs/batched_sparse.rst b/docs/developer/apidocs/batched_sparse.rst new file mode 100644 index 0000000000..48031bc550 --- /dev/null +++ b/docs/developer/apidocs/batched_sparse.rst @@ -0,0 +1,43 @@ +SPARSE BATCHED -- KokkosKernels sparse batched functor-level interfaces +======================================================================= + +cg +-- +.. doxygenstruct:: KokkosBatched::CG + :members: + +crsmatrix +--------- +.. doxygenclass:: KokkosBatched::CrsMatrix + :members: + +gmres +----- +.. doxygenstruct:: KokkosBatched::GMRES + :members: + +identity +-------- +.. doxygenclass:: KokkosBatched::Identity + :members: + +jacobiprec +---------- +.. doxygenclass:: KokkosBatched::JacobiPrec + :members: + +krylovhandle +------------ +.. doxygenclass:: KokkosBatched::KrylovHandle + :members: + +spmv +---- +.. doxygenstruct:: KokkosBatched::SerialSpmv + :members: +.. doxygenstruct:: KokkosBatched::TeamSpmv + :members: +.. doxygenstruct:: KokkosBatched::TeamVectorSpmv + :members: +.. doxygenstruct:: KokkosBatched::Spmv + :members: \ No newline at end of file diff --git a/docs/developer/apidocs/blas1.rst b/docs/developer/apidocs/blas1.rst new file mode 100644 index 0000000000..bfeb7fd1bb --- /dev/null +++ b/docs/developer/apidocs/blas1.rst @@ -0,0 +1,55 @@ +BLAS1 -- KokkosKernels blas1 interfaces +======================================= + +axpby +----- +.. doxygenfunction:: KokkosBlas::axpby + +dot +--- +.. doxygenfunction:: KokkosBlas::dot(const RV &, const XMV &, const YMV &, typename std::enable_if::value, int>::type = 0) +.. doxygenfunction:: KokkosBlas::dot(const XVector &, const YVector &) + +fill +---- +.. doxygenfunction:: KokkosBlas::fill + +mult +---- +.. doxygenfunction:: KokkosBlas::mult + +nrm1 +---- +.. doxygenfunction:: KokkosBlas::nrm1(const RV &, const XMV &, typename std::enable_if::value, int>::type = 0) +.. doxygenfunction:: KokkosBlas::nrm1(const XVector &) + +nrm2 +---- +.. doxygenfunction:: KokkosBlas::nrm2(const RV &R, const XMV &X, typename std::enable_if::value, int>::type = 0) +.. doxygenfunction:: KokkosBlas::nrm2(const XVector &x) + +nrm2w +----- +.. doxygenfunction:: KokkosBlas::nrm2w(const RV &R, const XMV &X, const XMV &W, typename std::enable_if::value, int>::type = 0) +.. doxygenfunction:: KokkosBlas::nrm2w(const XVector &x, const XVector &w) + +nrminf +------ +.. doxygenfunction:: KokkosBlas::nrminf(const RV &R, const XMV &X, typename std::enable_if::value, int>::type = 0) +.. doxygenfunction:: KokkosBlas::nrminf(const XVector &x) + +reciprocal +---------- +.. doxygenfunction:: KokkosBlas::reciprocal + +scal +---- +.. doxygenfunction:: KokkosBlas::scal + +sum +--- +.. doxygenfunction:: KokkosBlas::sum(const RV &R, const XMV &X, typename std::enable_if::value, int>::type = 0) + +update +------ +.. doxygenfunction:: KokkosBlas::update diff --git a/docs/developer/apidocs/blas2.rst b/docs/developer/apidocs/blas2.rst new file mode 100644 index 0000000000..1d9a3f3fa7 --- /dev/null +++ b/docs/developer/apidocs/blas2.rst @@ -0,0 +1,7 @@ +BLAS2 -- KokkosKernels blas2 interfaces +======================================= + +gemv +---- +.. doxygenfunction:: KokkosBlas::gemv(const char trans[], typename AViewType::const_value_type &alpha, const AViewType &A, const XViewType &x, typename YViewType::const_value_type &beta, const YViewType &y) +.. doxygenfunction:: KokkosBlas::gemv(const typename AViewType::execution_space &space, const char trans[], typename AViewType::const_value_type &alpha, const AViewType &A, const XViewType &x, typename YViewType::const_value_type &beta, const YViewType &y) diff --git a/docs/developer/apidocs/blas3.rst b/docs/developer/apidocs/blas3.rst new file mode 100644 index 0000000000..810b28a5a3 --- /dev/null +++ b/docs/developer/apidocs/blas3.rst @@ -0,0 +1,8 @@ +BLAS3 -- KokkosKernels blas3 interfaces +======================================= + +gemm +---- +.. doxygenfunction:: KokkosBlas::gemm(const char transA, const char transB, AMat::const_value_type alpha, const AMat &a, const BMat &b, CMat::const_value_type beta, const CMat &c) +.. doxygenfunction:: KokkosBlas::gemm(const char transA[], const char transB[], typename AViewType::const_value_type &alpha, const AViewType &A, const BViewType &B, typename CViewType::const_value_type &beta, const CViewType &C) +.. doxygenfunction:: KokkosBlas::gemm(const typename CViewType::execution_space &space, const char transA[], const char transB[], typename AViewType::const_value_type &alpha, const AViewType &A, const BViewType &B, typename CViewType::const_value_type &beta, const CViewType &C) diff --git a/docs/developer/apidocs/sparse.rst b/docs/developer/apidocs/sparse.rst new file mode 100644 index 0000000000..84ec48a519 --- /dev/null +++ b/docs/developer/apidocs/sparse.rst @@ -0,0 +1,27 @@ +SPARSE -- KokkosKernels sparse interfaces +========================================= + +crsmatrix +--------- +.. doxygenclass:: KokkosSparse::CrsMatrix + :members: + +spmv +---- +.. doxygenfunction:: KokkosSparse::spmv(KokkosKernels::Experimental::Controls, const char[], const AlphaType&, const AMatrix&, const XVector&, const BetaType&, const YVector&) +.. doxygenfunction:: KokkosSparse::spmv(KokkosKernels::Experimental::Controls, const char mode[], const AlphaType &alpha, const AMatrix &A, const XVector &x, const BetaType &beta, const YVector &y) +.. doxygenfunction:: KokkosSparse::spmv(KokkosKernels::Experimental::Controls controls, const char mode[], const AlphaType &alpha, const AMatrix &A, const XVector &x, const BetaType &beta, const YVector &y, const RANK_ONE) +.. doxygenfunction:: KokkosSparse::spmv(KokkosKernels::Experimental::Controls, const char mode[], const AlphaType &alpha, const AMatrix &A, const XVector &x, const BetaType &beta, const YVector &y, const RANK_TWO) +.. doxygenfunction:: KokkosSparse::spmv(const char mode[], const AlphaType &alpha, const AMatrix &A, const XVector &x, const BetaType &beta, const YVector &y) + +trsv +---- +.. doxygenfunction:: KokkosSparse::trsv + +spgemm +------ +.. doxygenfunction:: KokkosSparse::spgemm + +gauss +----- +.. doxygenfunction:: KokkosSparse::gauss diff --git a/docs/developer/build_doc.rst b/docs/developer/build_doc.rst new file mode 100644 index 0000000000..dd3d357286 --- /dev/null +++ b/docs/developer/build_doc.rst @@ -0,0 +1,18 @@ +Building Developer Documentation +================================ + +.. code-block:: + :caption: Installing dependencies on MacOS + + brew install doxygen + pip install sphinx + pip install breathe + pip install sphinx-rtd-theme + +.. code-block:: + :caption: How to build developer documentation + + cmake -DKokkosKernels_ENABLE_DOCS:BOOL=ON /path/to/kokkos-kernels + make Doxygen + make Sphinx + open build/docs/docs/sphinx/index.html \ No newline at end of file diff --git a/docs/developer/contrib.rst b/docs/developer/contrib.rst new file mode 100644 index 0000000000..0b02ebf190 --- /dev/null +++ b/docs/developer/contrib.rst @@ -0,0 +1,46 @@ +Contributing +============ + +Comment Style +------------- +We follow doxygen style comments for both external (API) and internal members. See https://www.doxygen.nl/manual/docblocks.html for details. +Our documentation can be generated using the `-DKokkosKernels_ENABLE_DOCS:BOOL=ON` cmake flag; see `Building the Documentation`. + +In general, we prefer that the prototype has the doxygen style comment rather than the definition. If there is no prototype, then the definition should have the doxygen style comment. + +.. code-block:: + :caption: API Doxygen Style Example + + /// \brief Blocking wrapper for accessing a Kokkos View. + /// \tparam ViewValueType The value type (Scalar or Vector) of each view element + /// \tparam ViewType The view type + /// \param v The view handle + /// \param m The requested row index of v + /// \param n The requested col index of v + /// \return If m and n are within the extents of v, a valid element of v; + /// otherwise, the last element of v. + /// + template + KOKKOS_INLINE_FUNCTION ViewValueType + access_view_bounds_check(ViewType v, int m, int n, const BoundsCheck::Yes &); + +Library policies +---------------- + +System-specific functions +------------------------- +For portability, any system-specific function that is not in the C++ standard should not be invoked from kokkos-kernels. + +Upcasting and downcasting +------------------------- +TODO + +Blocking and non-blocking interfaces +------------------------------------ +All the APIs are non-blocking unless: +1. A TPL is enabled +2. The result vector resides on the host and work is offloaded to a device + +When a TPL is enabled, we follow the blocking semantics of the TPL interface. + +If no TPLs are enabled, callers can avoid blocking calls by using any overload which accepts a result vector type as a template argument. \ No newline at end of file diff --git a/docs/developer/index.rst b/docs/developer/index.rst new file mode 100644 index 0000000000..7ee05f98ae --- /dev/null +++ b/docs/developer/index.rst @@ -0,0 +1,10 @@ +Developer Manual +================ + +.. toctree:: + :maxdepth: 1 + + Source Code Documentation + Building the Documentation + Code Style Guide + Contributing \ No newline at end of file diff --git a/docs/developer/style.rst b/docs/developer/style.rst new file mode 100644 index 0000000000..ddd9ce5197 --- /dev/null +++ b/docs/developer/style.rst @@ -0,0 +1,34 @@ +Style Guide +=========== + +We follow google's c++ coding style. See https://google.github.io/styleguide/cppguide.html and https://github.com/kokkos/kokkos-kernels/blob/master/.clang-format for details. + +.. code-block:: + :caption: Automate coding style via a pre-commit hook + + cat kokkos-kernels/.git/hooks/pre-commit + for FILE in $(git diff --cached --name-only | egrep '.*\.cpp$|.*\.hpp$|.*\.h$') + do + if [ -e $file ]; then + clang-format-8 -i -style=file $FILE + git add $FILEA + fi + done + chmod +x kokkos-kernels/.git/hooks/pre-commit + +.. code-block:: + :caption: Conditionally enable or disable formatting + + // clang-format off + cpp code here + // clang-format on + +.. code-block:: + :caption: Instal clang-format on MacOS + + brew install clang-format-8 + +.. code-block:: + :caption: Instal clang-format on Ubuntu + + apt install clang-format-8 \ No newline at end of file diff --git a/docs/developer/write_developer_doc.rst b/docs/developer/write_developer_doc.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/developer/write_user_doc.rst b/docs/developer/write_user_doc.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/index.rst b/docs/index.rst index 06240595bf..e0c5ea9a98 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,33 +1,8 @@ -.. Kokkos Kernels documentation master file, created by - sphinx-quickstart on Fri Sep 24 13:19:45 2021. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to Kokkos Kernels's documentation! +Kokkos Kernels documentation ========================================== - .. toctree:: :maxdepth: 2 - :caption: Contents: - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - -Docs -==== -.. doxygennamespace:: KokkosBlas - :project: KokkosKernels - :members: -.. doxygennamespace:: KokkosSparse - :project: KokkosKernels - :members: -.. doxygennamespace:: KokkosBatched - :project: KokkosKernels - :members: \ No newline at end of file + KokkosKernels GitHub Homepage + User Manual + Developer Docs