Merge pull request #15 from gismo/doc

Documentation for tutorials

doc/gsPreCICE.dox

@@ -0,0 +1,33 @@
+/*
+    This file is part of the G+Smo library.
+
+    This Source Code Form is subject to the terms of the Mozilla Public
+    License, v. 2.0. If a copy of the MPL was not distributed with this
+    file, You can obtain one at http://mozilla.org/MPL/2.0/.
+*/
+
+namespace gismo
+{
+
+/** \defgroup gsPreCICE preCICE interface
+\ingroup Modules
+
+The \ref gsPreCICE module provides an interface to the <a href="https://precice.org">preCICE</a> library. The gsPreCICE module can be used to couple \gismo to any other preCICe-compatible solver for multi-physics problems.
+
+The gsPreCICE module implements the following classes:
+- <b>\ref gsPreCICE</b>: class to declare the preCICE setup, e.g., to declare mesh points, data objects and to advance the time steps marched by preCICE
+- <b>\ref gsPreCICEFunction</b>: a class derived from a \ref gsFunction, intiated using \ref gsPreCICE. It calls preCICE upon every call of \ref eval_into
+- <b>\ref gsLookupFunction</b>: a class derived from a \ref gsFunction initiated using a matrix of parametric points and a matrix of values. This can be filled using the data from \ref gsPreCICE.
+
+In addition, the module provides several utilities to make data exchange between \gismo and other solvers more easy:
+- <b>\ref knotsToMatrix</b> and <b>\ref knotsToVector</b> : Converts a set of knot vectors to a plain matrix, to be sent to preCICE
+- <b>\ref knotMatrixToBasis</b>: Converts a knotMatrix from preCICE to a tensor basis
+- <b>\ref packMultiPatch</b>: Packs a \ref gsMultiPatch into a data structure that can be sent via preCICE
+- <b>\ref unpackMultiPatch</b>: Unpacks a a multi-patch data structure from preCICE to a \ref gsMultiPatch
+
+
+For more information about the preCICE interface, we refer to the module's <a href="https://github.com/gismo/gsPreCICE/blob/main/README.md">the README file</a>.
+
+*/
+
+}

examples/perpendicular-flap-vertex-gismo.cpp

@@ -158,6 +158,7 @@ int main(int argc, char *argv[])
     gsElasticityAssembler<real_t> assembler(patches,bases,bcInfo,g);
     assembler.options().setReal("YoungsModulus",E);
     assembler.options().setReal("PoissonsRatio",nu);
+    assembler.options().setInt("MaterialLaw",material_law::saint_venant_kirchhoff);
     assembler.assemble();
 
     gsMatrix<real_t> Minv;
@@ -235,7 +236,7 @@ int main(int argc, char *argv[])
 
     real_t time = 0;
 
-    // Plot initial solution 
+    // Plot initial solution
     if (plot)
     {
         gsMultiPatch<> solution;

examples/perpendicular-flap/precice-config.xml

@@ -7,7 +7,7 @@
       enabled="true" />
   </log>
 
-  <data:vector name="Force" />
+  <data:vector name="Stress" />
   <data:vector name="Displacement" />
 
   <mesh name="Fluid-Mesh" dimensions="2">
@@ -23,7 +23,7 @@
   <participant name="Fluid">
     <provide-mesh name="Fluid-Mesh" />
     <receive-mesh name="Solid-Mesh" from="Solid" />
-    <write-data name="Force" mesh="Fluid-Mesh" />
+    <write-data name="Stress" mesh="Fluid-Mesh" />
     <read-data name="Displacement" mesh="Fluid-Mesh" />
     <mapping:rbf direction="write" from="Fluid-Mesh" to="Solid-Mesh" constraint="conservative">
       <basis-function:compact-polynomial-c6 support-radius="1." />
@@ -36,7 +36,7 @@
   <participant name="Solid">
     <provide-mesh name="Solid-Mesh" />
     <write-data name="Displacement" mesh="Solid-Mesh" />
-    <read-data name="Force" mesh="Solid-Mesh" />
+    <read-data name="Stress" mesh="Solid-Mesh" />
     <watch-point mesh="Solid-Mesh" name="Flap-Tip" coordinate="0.0;1" />
   </participant>
 
@@ -46,14 +46,14 @@
     <time-window-size value="0.01" />
     <max-time value="5" />
     <participants first="Fluid" second="Solid" />
-    <exchange data="Force" mesh="Solid-Mesh" from="Fluid" to="Solid" />
+    <exchange data="Stress" mesh="Solid-Mesh" from="Fluid" to="Solid" />
     <exchange data="Displacement" mesh="Solid-Mesh" from="Solid" to="Fluid" />
     <max-iterations value="50" />
     <relative-convergence-measure limit="5e-3" data="Displacement" mesh="Solid-Mesh" />
-    <relative-convergence-measure limit="5e-3" data="Force" mesh="Solid-Mesh" />
+    <relative-convergence-measure limit="5e-3" data="Stress" mesh="Solid-Mesh" />
     <acceleration:IQN-ILS>
       <data name="Displacement" mesh="Solid-Mesh" />
-      <data name="Force" mesh="Solid-Mesh" />
+      <data name="Stress" mesh="Solid-Mesh" />
       <preconditioner type="residual-sum" />
       <filter type="QR2" limit="1e-2" />
       <initial-relaxation value="0.5" />

gsPreCICEUtils.h

@@ -1,6 +1,6 @@
-/** @file gsPreCICE.h
+/** @file gsPreCICEUtils.h
 
-    @brief Header file for using gsPreCICE extension
+    @brief Utilities file for using gsPreCICE extension
 
     This file is part of the G+Smo library.
 
@@ -18,6 +18,16 @@
 
 namespace gismo {
 
+/**
+ * @brief      Gets a vector of knot vectors from a basis
+ *
+ * @param[in]  source      The source basis
+ * @param      tensorKnots  The knots in a vector
+ *
+ * @tparam     DIM         Dimension
+ * @tparam     T           Real type
+ * @tparam     basis_type  Basis type
+ */
 template <short_t DIM, class T, template<short_t _DIM, class _T> class basis_type>
 inline void getKnots(const gsBasis<T> & source, std::vector<gsKnotVector<T>> & tensorKnots)
 {
@@ -27,7 +37,7 @@ inline void getKnots(const gsBasis<T> & source, std::vector<gsKnotVector<T>> & t
 }
 
 /**
- * @brief      { function_description }
+ * @brief      Puts all the knots in a vector (for 1D bases only)
  *
  *  Make a matrix with the knot vectors
  *  [[x1_1, x1_2, ..., nan , nan ,..., nan , nan , ...]
@@ -36,9 +46,9 @@ inline void getKnots(const gsBasis<T> & source, std::vector<gsKnotVector<T>> & t
  *
  * @param[in]  basis  The basis
  *
- * @tparam     T      { description }
+ * @tparam     T      Real type
  *
- * @return     { description_of_the_return_value }
+ * @note @hverhelst, @Crazy-Rich-Meghan is this needed?
  */
 
 template<class T>
@@ -67,6 +77,17 @@ gsVector<T> knotsToVector(const gsBasis<T> & basis)
     return knots;
 }
 
+/** @brief      Puts all the knots in a matrix (for n-D bases)
+ *
+ *  Make a matrix with the knot vectors
+ *  [[x1_1, x1_2, ..., nan , nan ,..., nan , nan , ...]
+ *   [nan , nan , ..., x2_1, x2_2,..., nan , nan , ...]
+ *   [nan , nan , ..., nan , nan ,..., x2_1, x2_2, ...]]
+ *
+ * @param[in]  basis  The basis
+ *
+ * @tparam     T      Real type
+ */
 template<class T>
 gsMatrix<T> knotsToMatrix(const gsBasis<T> & basis)
 {
@@ -108,6 +129,9 @@ gsMatrix<T> knotsToMatrix(const gsBasis<T> & basis)
     return knots;
 }
 
+/**
+ * @todo @hverhelst, @Crazy-Rich-Meghan
+ */
 template<class T>
 gsMatrix<T> knotVectorUnpack(const gsMatrix<T> & knots, index_t numBoundaries)
 {
@@ -182,7 +206,7 @@ gsMatrix<T> knotVectorUnpack(const gsMatrix<T> & knots, index_t numBoundaries)
  */
 
 template <class T>
-std::tuple<gsMatrix<T>, gsMatrix<T>, std::vector<index_t>, std::vector<index_t>> packMultiPatch(const gsMultiPatch<T> &mp) 
+std::tuple<gsMatrix<T>, gsMatrix<T>, std::vector<index_t>, std::vector<index_t>> packMultiPatch(const gsMultiPatch<T> &mp)
 {
     std::vector<gsMatrix<T>> knotMatrices;
     knotMatrices.reserve(mp.nPatches());
@@ -238,7 +262,7 @@ std::tuple<gsMatrix<T>, gsMatrix<T>, std::vector<index_t>, std::vector<index_t>>
 
 
 /**
- * @brief      Convert the packed matrices into back into a gsMultiPatch<T> object. 
+ * @brief      Convert the packed matrices into back into a gsMultiPatch<T> object.
  *
  * @param[in]  knotMatrices  The knot matrices
  * @param[in]  coefMatrices  The ratio matrices
@@ -261,7 +285,7 @@ gsMultiPatch<T> unpackMultiPatch(const gsMatrix<T> &knotMatrix, const gsMatrix<T
 
         // Create the gsBasis object from the knot matrix
         std::shared_ptr<gsBasis<T>> KnotBasis = knotMatrixToBasis(km);
-        
+
         // Create the gsGeometry object
         auto geom = KnotBasis->makeGeometry(cm);
 
@@ -306,23 +330,23 @@ gsMatrix<T> unPackControlPoints(const gsMatrix<T> & controlPoints, const gsMatri
 
 
     // Simplified copying of control points (just a placeholder)
-    for (index_t i = 0; i < controlPoints.rows(); ++i) 
+    for (index_t i = 0; i < controlPoints.rows(); ++i)
     {
         index_t diff = counter - cp_index;
         index_t startIndex = cp_index - diff + 1;  // Calculate the start index
-        for (size_t j = 0; j < diff; ++j) 
+        for (size_t j = 0; j < diff; ++j)
         {
             unpackedCps(i,j) = controlPoints(i,j + startIndex);
         }
     }
     return unpackedCps;
 }
 
-/** 
+/**
  * @brief      Convert a matrix of knot vectors into a gsBasis object.
- * 
+ *
  * @param[in]  knots  The matrix of knot vectors
- * 
+ *
  * @return     A shared pointer to the gsBasis object.
  */