From 5d2cc117a30b49c167a2c1021f160d3523588191 Mon Sep 17 00:00:00 2001
From: Nick <nicolo.antonelli@studenti.unipd.it>
Date: Wed, 18 Dec 2024 09:46:45 +0100
Subject: [PATCH] detailed comments on sbm cases

---
 kratos/geometries/brep_curve_on_surface.h     |  7 ++++
 kratos/geometries/brep_surface.h              | 12 +++++++
 .../nurbs_curve_on_surface_geometry.h         | 35 +++++++++++++++----
 3 files changed, 47 insertions(+), 7 deletions(-)

diff --git a/kratos/geometries/brep_curve_on_surface.h b/kratos/geometries/brep_curve_on_surface.h
index b1847e005b4..ddb9bfae36f 100644
--- a/kratos/geometries/brep_curve_on_surface.h
+++ b/kratos/geometries/brep_curve_on_surface.h
@@ -37,6 +37,7 @@ namespace Kratos
  * @class BrepCurveOnSurface
  * @ingroup KratosCore
  * @brief The BrepCurveOnSurface acts as topology for curves on surfaces.
+ * @tparam TShiftedBoundary Boolean flag indicating whether is defined with shifted boundary conditions.
  */
 template<class TContainerPointType, bool TShiftedBoundary, class TContainerPointEmbeddedType = TContainerPointType >
 class BrepCurveOnSurface
@@ -324,6 +325,10 @@ class BrepCurveOnSurface
      */
     void SpansLocalSpace(std::vector<double>& rSpans, IndexType DirectionIndex = 0) const override
     {
+        /* When the `TShiftedBoundary` template parameter is true, the spans are computed using 
+        *  the shifted boundary method by invoking `SpansLocalSpaceSBM`.
+        *  Otherwise, the spans are computed using the standard method by invoking `SpansLocalSpace`
+        */
         if constexpr (TShiftedBoundary) {
             mpCurveOnSurface->SpansLocalSpaceSBM(rSpans,
                 mCurveNurbsInterval.GetT0(), mCurveNurbsInterval.GetT1());
@@ -565,6 +570,8 @@ class BrepCurveOnSurface
         const IntegrationPointsArrayType& rIntegrationPoints,
         IntegrationInfo& rIntegrationInfo) override
     {
+        // If `TShiftedBoundary` is true, the method `CreateQuadraturePointGeometriesSBM` is called.
+        // Otherwise, the method `CreateQuadraturePointGeometries` is used for standard processing.
         if constexpr (TShiftedBoundary) {
             mpCurveOnSurface->CreateQuadraturePointGeometriesSBM(
                 rResultGeometries, NumberOfShapeFunctionDerivatives, rIntegrationPoints, rIntegrationInfo);
diff --git a/kratos/geometries/brep_surface.h b/kratos/geometries/brep_surface.h
index 8b44d016889..aa565da88d3 100644
--- a/kratos/geometries/brep_surface.h
+++ b/kratos/geometries/brep_surface.h
@@ -38,6 +38,8 @@ namespace Kratos
  * @ingroup KratosCore
  * @brief The BrepSurface acts as topology for faces. Those
  *        can be enclosed by a certain set of brep face curves.
+ * @tparam TShiftedBoundary Boolean flag indicating whether is 
+ *        defined with shifted boundary conditions.
  */
 template<class TContainerPointType, bool TShiftedBoundary, class TContainerPointEmbeddedType = TContainerPointType>
 class BrepSurface
@@ -428,6 +430,16 @@ class BrepSurface
     ///@{
 
     /* Creates integration points on the nurbs surface of this geometry.
+     * Accounting for whether the surface is trimmed or untrimmed, and whether shifted 
+     * boundary conditions are used
+     * 
+     * - **Untrimmed Surface**: -> Non-cutting case
+     *   - If `TShiftedBoundary` is true, the method prepares for the shifted boundary method (SBM) 
+     *   - Otherwise, it directly uses `CreateIntegrationPoints` from the underlying NURBS surface.
+     * - **Trimmed Surface**: -> Cutting case
+     *   - It calls `BrepTrimmingUtilities::CreateBrepSurfaceTrimmingIntegrationPoints` 
+     *     to generate integration points that conform to the trimming curve.
+     * 
      * @param return integration points.
      */
     void CreateIntegrationPoints(
diff --git a/kratos/geometries/nurbs_curve_on_surface_geometry.h b/kratos/geometries/nurbs_curve_on_surface_geometry.h
index 443966d631b..25582a30add 100644
--- a/kratos/geometries/nurbs_curve_on_surface_geometry.h
+++ b/kratos/geometries/nurbs_curve_on_surface_geometry.h
@@ -306,8 +306,20 @@ class NurbsCurveOnSurfaceGeometry : public Geometry<typename TSurfaceContainerPo
     }
     
      /**
-     * @brief 
-     * SBM case: compute only knot spans intersections
+     * @brief Computes the knot span intersections for the shifted boundary method (SBM) case.
+     * This function calculates the intersections between a NURBS curve segment and the knot spans
+     * of a surface in the local parameter space, specifically for SBM-based geometries. The computed
+     * intersections are returned in the `rSpans` vector.
+     * 
+     * * @details 
+     * The function operates as follows:
+     * - Computes the physical coordinates of the start (`Start`) and end (`End`) points of the curve segment.
+     * - Determines the segment's orientation (horizontal or vertical) based on the difference in coordinates.
+     * - For each direction (U or V):
+     *   - Calculates the relevant knot interval.
+     *   - Iterates over the surface spans in the corresponding direction, identifying intersections within the interval.
+     *   - Maps the intersection values back to the curve's parameter space and stores them in `rSpans`.
+     * 
      * @param rSpans 
      * @param Start 
      * @param End 
@@ -343,7 +355,7 @@ class NurbsCurveOnSurfaceGeometry : public Geometry<typename TSurfaceContainerPo
         const double tolerance_orientation = 1e-10;
         const double tolerance_intersection = 1e-15;
         
-        // Scale factor between volume coordinate and surface one
+        // Scale factor between surface coordinate and curve one
         double physical_length_segment = norm_2(physical_coord_1-physical_coord_2);
         double parameter_length_segment = norm_2(local_coord_1-local_coord_2);
         double scale_factor = parameter_length_segment/physical_length_segment;
@@ -359,7 +371,7 @@ class NurbsCurveOnSurfaceGeometry : public Geometry<typename TSurfaceContainerPo
 
             knot_interval[0] -= tolerance_intersection; 
             knot_interval[1] += tolerance_intersection;
-            // Compare with volume_spans_u
+            // Compare with surface_spans_u
             for (IndexType i = 0; i < surface_spans_u.size(); i++) {
                 double curr_knot_value = surface_spans_u[i];
                 if (curr_knot_value < knot_interval[0]) {continue;}
@@ -372,14 +384,14 @@ class NurbsCurveOnSurfaceGeometry : public Geometry<typename TSurfaceContainerPo
             }
             
         } else if (std::abs(physical_coord_1[1]-physical_coord_2[1]) > tolerance_orientation) {
-        // vertical case
+            // vertical case
             knot_interval[0] = physical_coord_1[1]; 
             knot_interval[1] = physical_coord_2[1];
             std::sort(knot_interval.begin(), knot_interval.end());
 
             knot_interval[0] -= tolerance_intersection; 
             knot_interval[1] += tolerance_intersection;
-            // Compare with volume_spans_v
+            // Compare with surface_spans_v
             for (IndexType i = 0; i < surface_spans_v.size(); i++) {
                 double curr_knot_value = surface_spans_v[i];
                 if (curr_knot_value < knot_interval[0]) {continue;}
@@ -649,6 +661,15 @@ class NurbsCurveOnSurfaceGeometry : public Geometry<typename TSurfaceContainerPo
      * @brief This method creates a list of quadrature point geometries
      *        from a list of integration points in the SBM case.
      *
+     * * @details
+     * 1. Checks whether the BRep is internal (aligned with specific knot spans) or external.
+     *    - Internal boundaries are associated with a fixed span (knot span edge) in the U and V directions.
+     *    - External boundaries are associated with body-fitted cases.
+     * 2. Iterates over each integration point:
+     *    - Computes global space derivatives for the NURBS curve at the integration point.
+     *    - Gathers nonzero control points and associated shape function values.
+     * 3. Creates a geometry shape function container and assigns it to the result geometries array.
+     * 
      * @param rResultGeometries list of quadrature point geometries.
      * @param rIntegrationPoints list of integration points.
      * @param NumberOfShapeFunctionDerivatives the number provided
@@ -753,7 +774,7 @@ class NurbsCurveOnSurfaceGeometry : public Geometry<typename TSurfaceContainerPo
                         global_space_derivatives[0][1]);
                 }
                 else {
-                    // Trimming case or external brep
+                    // SBM case on external brep
                     shape_function_container.ComputeBSplineShapeFunctionValues(
                         mpNurbsSurface->KnotsU(), mpNurbsSurface->KnotsV(),
                         global_space_derivatives[0][0], global_space_derivatives[0][1]);