From 6f65647f8eda5bacdee6c751127cfde514e3deba Mon Sep 17 00:00:00 2001
From: kliegeois <kimliegeois@ymail.com>
Date: Sun, 29 Mar 2020 16:31:31 +0200
Subject: [PATCH] Katropton: update dox
---
katropton/src/Algebraic.h | 2 +-
katropton/src/Algebraic.hpp | 12 ++++++++----
katropton/src/ContactsList.cpp | 13 +++++++++++++
katropton/src/DirichletList.hpp | 8 +++++++-
katropton/src/DiscreteProblem.hpp | 10 ++++++++--
katropton/src/Domain.h | 2 ++
katropton/src/ElementsList.cpp | 6 ++++++
katropton/src/Graph.cpp | 2 ++
katropton/src/Loads.h | 2 ++
katropton/src/Map.cpp | 2 ++
katropton/src/Material.h | 2 ++
katropton/src/MaterialsList.h | 2 ++
katropton/src/Matrices.h | 6 +++---
katropton/src/NeumannList.h | 6 ++++++
katropton/src/NodesList.cpp | 2 ++
katropton/src/PreloadList.h | 2 ++
katropton/src/SourcesList.h | 6 ++++++
katropton/src/WeightsList.h | 31 ++++++++++++++++---------------
katropton/src/wSpectralApproach.h | 10 +++++++---
19 files changed, 97 insertions(+), 29 deletions(-)
diff --git a/katropton/src/Algebraic.h b/katropton/src/Algebraic.h
index 400ded85..2af7565a 100644
--- a/katropton/src/Algebraic.h
+++ b/katropton/src/Algebraic.h
@@ -39,7 +39,7 @@ public:
Teuchos::RCP<Matrices<scalar>> matrices;
Teuchos::RCP<Vectors<scalar>> vectors;
- Algebraic(Teuchos::RCP<Map> map, Teuchos::RCP<Domain<scalar>> domain, Teuchos::RCP<Loads<scalar>> loads);
+ Algebraic(Teuchos::RCP<Map> map, Teuchos::RCP<Domain<scalar>> domain);
Teuchos::RCP<Tpetra::Vector<scalar, local_ordinal_type, global_ordinal_type>> readVectorFromFile(std::string &name, size_t myRank);
};
diff --git a/katropton/src/Algebraic.hpp b/katropton/src/Algebraic.hpp
index b904ee5b..6b31d150 100644
--- a/katropton/src/Algebraic.hpp
+++ b/katropton/src/Algebraic.hpp
@@ -2,17 +2,21 @@ namespace katropton
{
/**
- * @brief Algebraic constructor.
+ * @brief Algebraic constructor
*
+ * This contrusctor calls the constructor of the katropton::Graph, katropton::Matrices, and katropton::Vectors classes.
+ * To do so, we need information regarding the distributions of the nodes and elements over the MPI processes (information
+ * included in the katropton::Map class) and information regarding the connectivity between the degrees of freedom (or,
+ * equivalently, between the nodes) (information included in katropton::Domain::elementsList).
+ *
* Arguments:
* <ul>
* <li> map: an RCP to a Map object,
- * <li> domain: an RCP to a Domain object,
- * <li> loads: an RCP to a Loads object.
+ * <li> domain: an RCP to a Domain object.
* </ul>
*/
template <typename scalar>
-Algebraic<scalar>::Algebraic(Teuchos::RCP<Map> _map, Teuchos::RCP<Domain<scalar>> domain, Teuchos::RCP<Loads<scalar>> loads)
+Algebraic<scalar>::Algebraic(Teuchos::RCP<Map> _map, Teuchos::RCP<Domain<scalar>> domain)
{
map = _map;
diff --git a/katropton/src/ContactsList.cpp b/katropton/src/ContactsList.cpp
index 4ddf35b3..7ca5068e 100644
--- a/katropton/src/ContactsList.cpp
+++ b/katropton/src/ContactsList.cpp
@@ -17,6 +17,19 @@ using namespace tbox;
/**
* @brief ContactsList constructor
*
+ * This constructor allocates 11 Kokkos::View which store all the required information related to each contact interface, including:
+ * <ul>
+ * <li> all the slaves and master nodes and elements IDs,
+ * <li> all the normal of the surfaces,
+ * <li> type of Lagrange multiplier shape functions,
+ * <li> type of the interface (contact, Signorini, sticking contact, mesh tying),
+ * <li> initial status of the Lagrange multipliers and whether they should be updated.
+ * </ul>
+ *
+ * To do so, we need the information regarding the contact interfaces (stored into the katropton::Problem object), the information on the
+ * distribution of the nodes (stored into the katropton::Map object), and the information on the nodes and elements (stored into the
+ * katropton::NodesList and katropton::ElementList objects).
+ *
* Arguments:
* <ul>
* <li> pbl: a Problem object,
diff --git a/katropton/src/DirichletList.hpp b/katropton/src/DirichletList.hpp
index db260c1b..2b3c0ce6 100644
--- a/katropton/src/DirichletList.hpp
+++ b/katropton/src/DirichletList.hpp
@@ -3,7 +3,13 @@ namespace katropton
/**
* @brief DirichletList constructor
- *
+ *
+ * This constructor allocates 2 Kokkos::View which store all the required information related to each Dirichlet BC, including:
+ * <ul>
+ * <li> all the Dirichlet nodes,
+ * <li> all the values of the Dirichlet BC.
+ * </ul>
+ *
* Arguments:
* <ul>
* <li> pbl: a Problem object,
diff --git a/katropton/src/DiscreteProblem.hpp b/katropton/src/DiscreteProblem.hpp
index a45b0592..98f65c39 100644
--- a/katropton/src/DiscreteProblem.hpp
+++ b/katropton/src/DiscreteProblem.hpp
@@ -8,9 +8,15 @@
namespace katropton
{
+
/**
* @brief DiscreteProblem constructor
*
+ * This constructor constructs a katropton::Map, a katropton::Domain, a katropton::Loads, and a katropton::Algebraic.
+ * The last three objects are stored as member data of the katropton::DiscreteProblem object and include all
+ * the information related to the problem to solve. See the documentation of the member data for more information on
+ * the purpose of each class.
+ *
* Arguments:
* <ul>
* <li> A problem object,
@@ -34,12 +40,12 @@ DiscreteProblem<scalar>::DiscreteProblem(Problem &pbl, size_t _numPrimalDPN,
LinearSolver::getTimers()["loads"].start();
loads = Teuchos::rcp(new Loads<scalar>(pbl, map, domain));
LinearSolver::getTimers()["loads"].stop();
- algebraic = Teuchos::rcp(new Algebraic<scalar>(map, domain, loads));
+ algebraic = Teuchos::rcp(new Algebraic<scalar>(map, domain));
}
/**
* @brief Update the activity of the Lagrange multipliers
- * and returns a Mask which stores true for the converged samples.
+ * and return a Mask which stores true for the converged samples.
*
* Argument:
* <ul>
diff --git a/katropton/src/Domain.h b/katropton/src/Domain.h
index 272877f5..80ea045b 100644
--- a/katropton/src/Domain.h
+++ b/katropton/src/Domain.h
@@ -46,6 +46,8 @@ public:
/**
* @brief Domain constructor
*
+ * This constructor initializes the lists of elements, nodes, materials, contact interfaces, and random fields.
+ *
* Arguments:
* <ul>
* <li> A problem object,
diff --git a/katropton/src/ElementsList.cpp b/katropton/src/ElementsList.cpp
index aea0e247..1a43f50d 100644
--- a/katropton/src/ElementsList.cpp
+++ b/katropton/src/ElementsList.cpp
@@ -12,6 +12,12 @@ using namespace katropton;
/**
* @brief ElementsList constructor
*
+ * This constructor allocates 1 Kokkos::View which stores all the required information related to the elements, including:
+ * <ul>
+ * <li> all their local node IDs,
+ * <li> their size, type, and material (at most one material per element).
+ * </ul>
+ *
* Arguments:
* <ul>
* <li> pbl: a Problem object,
diff --git a/katropton/src/Graph.cpp b/katropton/src/Graph.cpp
index 8e845585..30e3bb59 100644
--- a/katropton/src/Graph.cpp
+++ b/katropton/src/Graph.cpp
@@ -29,6 +29,8 @@ int max(int a, int b)
/**
* @brief Graph constructor
+ *
+ * This constructor computes the sparsity pattern of the primal matrix.
*
* Arguments:
* <ul>
diff --git a/katropton/src/Loads.h b/katropton/src/Loads.h
index 0ba4d4df..cd48e728 100644
--- a/katropton/src/Loads.h
+++ b/katropton/src/Loads.h
@@ -34,6 +34,8 @@ public:
/**
* @brief Loads constructor
*
+ * This constructor initializes the lists of Dirichlet BC, Neumann BC, sources, preloads, and weights.
+ *
* Arguments:
* <ul>
* <li> pbl: A Problem object,
diff --git a/katropton/src/Map.cpp b/katropton/src/Map.cpp
index 3777c489..4c0672e9 100644
--- a/katropton/src/Map.cpp
+++ b/katropton/src/Map.cpp
@@ -30,6 +30,8 @@ void std_vector_intersection(std::vector<Map::global_ordinal_type> vec1,
/**
* @brief Map constructor
*
+ * This constructor initializes the maps used to describe the distributed matrices and vectors.
+ *
* Arguments:
* <ul>
* <li> pbl: A Problem object,
diff --git a/katropton/src/Material.h b/katropton/src/Material.h
index af8dfff9..b0444949 100644
--- a/katropton/src/Material.h
+++ b/katropton/src/Material.h
@@ -58,6 +58,8 @@ public:
/**
* @brief Material constructor
*
+ * This constructor creates a new katropton::Material which store the constitutive parameters.
+ *
* Arguments:
* <ul>
* <li> _E: the Young modulus \f$E\f$,
diff --git a/katropton/src/MaterialsList.h b/katropton/src/MaterialsList.h
index 39856952..1ca885a7 100644
--- a/katropton/src/MaterialsList.h
+++ b/katropton/src/MaterialsList.h
@@ -55,6 +55,8 @@ public:
/**
* @brief MaterialsList constructor
*
+ * This constructor allocates 1 Kokkos::View which stores all the constitutive parameters of each material.
+ *
* Arguments:
* <ul>
* <li> pbl: A Problem object,
diff --git a/katropton/src/Matrices.h b/katropton/src/Matrices.h
index f4c6c881..b3842d42 100644
--- a/katropton/src/Matrices.h
+++ b/katropton/src/Matrices.h
@@ -89,13 +89,13 @@ public:
/**
* @brief Matrices constructor
*
+ * This constructor allocates the memory for the matrix \f$\boldsymbol{A}\f$.
+ * The other matrices and the filling of the entries are done later.
+ *
* Argument:
* <ul>
* <li> graph: an RCP to a Graph object.
* </ul>
- *
- * This constructor only allocate the memory for the matrix \f$\boldsymbol{A}\f$.
- * The other matrices and the filling of the entries are treated later.
*/
template <typename scalar>
Matrices<scalar>::Matrices(Teuchos::RCP<Graph> graph)
diff --git a/katropton/src/NeumannList.h b/katropton/src/NeumannList.h
index 78fcd853..2d80faf0 100644
--- a/katropton/src/NeumannList.h
+++ b/katropton/src/NeumannList.h
@@ -109,6 +109,12 @@ public:
/**
* @brief NeumannList constructor
*
+ * This constructor allocates 2 Kokkos::View which store all the required information related to each Neumann BC, including:
+ * <ul>
+ * <li> all the Neumann elements,
+ * <li> all the values of the Neumann BC.
+ * </ul>
+ *
* Arguments:
* <ul>
* <li> pbl: a Problem object,
diff --git a/katropton/src/NodesList.cpp b/katropton/src/NodesList.cpp
index f2418a22..b9fab26d 100644
--- a/katropton/src/NodesList.cpp
+++ b/katropton/src/NodesList.cpp
@@ -9,6 +9,8 @@ using namespace katropton;
/**
* @brief NodesList constructor
*
+ * This constructor allocates 1 Kokkos::View which stores all the nodes positions.
+ *
* Arguments:
* <ul>
* <li> pbl: a Problem object,
diff --git a/katropton/src/PreloadList.h b/katropton/src/PreloadList.h
index f3dd4562..0f08e7a3 100644
--- a/katropton/src/PreloadList.h
+++ b/katropton/src/PreloadList.h
@@ -50,6 +50,8 @@ public:
/**
* @brief NeumannList constructor
*
+ * This constructor allocates 1 Kokkos::View which stores all the preload related to each contact interface.
+ *
* Arguments:
* <ul>
* <li> pbl: a Problem object,
diff --git a/katropton/src/SourcesList.h b/katropton/src/SourcesList.h
index 4910b7a7..320c44c3 100644
--- a/katropton/src/SourcesList.h
+++ b/katropton/src/SourcesList.h
@@ -90,6 +90,12 @@ public:
/**
* @brief SourcesList constructor
*
+ * This constructor allocates 2 Kokkos::View which store all the required information related to source, including:
+ * <ul>
+ * <li> all the source elements,
+ * <li> all the values of the heat source.
+ * </ul>
+ *
* Arguments:
* <ul>
* <li> pbl: a Problem object,
diff --git a/katropton/src/WeightsList.h b/katropton/src/WeightsList.h
index c3f15b69..dd1cf79f 100644
--- a/katropton/src/WeightsList.h
+++ b/katropton/src/WeightsList.h
@@ -41,7 +41,6 @@ private:
local_ordinal_type weights_values;
public:
- WeightsList();
WeightsList(Problem &pbl, Teuchos::RCP<Map> map, Teuchos::RCP<ElementsList> elementsList);
/**
@@ -112,20 +111,22 @@ public:
}
};
-template <typename scalar>
-WeightsList<scalar>::WeightsList()
-{
- weights_number = 0;
- weights_size = 0;
- weights_nodes = 0;
-
- weights_dofs = 0;
- weights_values = 0;
-
- weights_nodesList = Kokkos::View<int **, Kokkos::LayoutRight>("R", weights_number, 0);
- weights_values_list = Kokkos::View<scalar **, Kokkos::LayoutRight>("R", weights_number, 0);
-}
-
+/**
+ * @brief WeightsList constructor
+ *
+ * This constructor allocates 2 Kokkos::View which store all the required information related to each weighted region, including:
+ * <ul>
+ * <li> all the weighted nodes,
+ * <li> all the values of the weights.
+ * </ul>
+ *
+ * Arguments:
+ * <ul>
+ * <li> pbl: a Problem object,
+ * <li> map: an RCP to a Map object,
+ * <li> elementsList: an RCP to an ElementList object.
+ * </ul>
+ */
template <typename scalar>
WeightsList<scalar>::WeightsList(Problem &pbl, Teuchos::RCP<Map> map, Teuchos::RCP<ElementsList> elementsList)
{
diff --git a/katropton/src/wSpectralApproach.h b/katropton/src/wSpectralApproach.h
index dec7efb2..e52ddb20 100644
--- a/katropton/src/wSpectralApproach.h
+++ b/katropton/src/wSpectralApproach.h
@@ -6,7 +6,9 @@
#include <random>
/**
- * @brief A function which computes the random matrix Z starting at a given seed.
+ * @brief A function which computes a random matrix \f$\boldsymbol{Z}\f$ starting at a given seed.
+ *
+ * This matrix is used to generate a random field based on the spectral approach
*/
template <typename Scalar, typename Device>
Kokkos::View<Scalar **, Kokkos::LayoutLeft, Device> construct_Z(size_t muw, unsigned long seed_Z, size_t wait = 0)
@@ -29,7 +31,9 @@ Kokkos::View<Scalar **, Kokkos::LayoutLeft, Device> construct_Z(size_t muw, unsi
}
/**
- * @brief A function which computes the random matrix Phi starting at a given seed.
+ * @brief A function which computes a random matrix \f$\boldsymbol{\Phi}\f$ starting at a given seed.
+ *
+ * This matrix is used to generate a random field based on the spectral approach
*/
template <typename Scalar, typename Device>
Kokkos::View<Scalar **, Kokkos::LayoutLeft, Device> construct_Phi(size_t muw, unsigned long seed_Phi, size_t wait = 0)
@@ -52,7 +56,7 @@ Kokkos::View<Scalar **, Kokkos::LayoutLeft, Device> construct_Phi(size_t muw, un
}
/**
- * @brief A class that constructs realization of Gaussian or exponential
+ * @brief A class that constructs realization(s) of Gaussian or exponential
* scalar random field based on the spectral approach.
*/
template <typename Scalar, typename Device>
--
GitLab