adding docstrings to nn source functions and inlining to_fe_element_type to remove the use_basis_adapter_for helper function

Author: zasexton

Code/Source/solver/nn.cpp

@@ -71,7 +71,9 @@ std::string solver_element_name(consts::ElementType eType)
 /// choice of basis family and polynomial order for each element type
 /// (basis_factory::default_basis_request). The switch deliberately has no
 /// default case so that compilers building with -Wswitch flag any newly added
-/// solver element type that is missing a mapping here.
+/// solver element type that is missing a mapping here. Returns std::nullopt for
+/// element types the FE Basis does not implement (NA/PNT/NRB); callers test FE
+/// Basis support with has_value().
 std::optional<fe::ElementType> to_fe_element_type(consts::ElementType eType)
 {
   switch (eType) {
@@ -99,11 +101,12 @@ std::optional<fe::ElementType> to_fe_element_type(consts::ElementType eType)
   return std::nullopt;
 }
 
-bool use_basis_adapter_for(consts::ElementType eType)
-{
-  return to_fe_element_type(eType).has_value();
-}
-
+/// Whether the FE Basis face adapter can evaluate face shape functions for
+/// eType. An element face is always a point, line, or surface topology, so the
+/// switch restricts support to those types (a volume element never appears as a
+/// face); it then defers to to_fe_element_type to confirm the FE Basis library
+/// actually provides a mapping for that face type. The face get_gnn uses this
+/// to choose between the FE Basis path and the explicit paths.
 bool supports_face_basis_adapter_for(consts::ElementType eType)
 {
   switch (eType) {
@@ -114,7 +117,7 @@ bool supports_face_basis_adapter_for(consts::ElementType eType)
     case consts::ElementType::QUD4:
     case consts::ElementType::QUD8:
     case consts::ElementType::QUD9:
-      return use_basis_adapter_for(eType);
+      return to_fe_element_type(eType).has_value();
     default:
       return false;
   }
@@ -145,6 +148,17 @@ const febasis::BasisFunction& basis_for_solver_element(consts::ElementType eType
   return *it->second;
 }
 
+/// Permutation from a solver element's local node ordering to the FE Basis
+/// ReferenceNodeLayout ordering, indexed by the solver-local node number:
+/// map[solver_node] is the matching FE Basis node. The solver and the FE Basis
+/// library number element nodes with different conventions, so this table
+/// reconciles them at the adapter boundary. An empty span means the two
+/// orderings already coincide (identity) and no permutation is applied, which
+/// holds for every element type not listed below (lines, Quad4/8/9, Hex8/20).
+/// Wedge6 (WDG) reuses the Triangle6 table: its two triangular node triples are
+/// reordered exactly like a 6-node triangle.
+/// \note These tables must stay consistent with the FE Basis lattice ordering;
+/// a mismatch would silently assign shape functions to the wrong nodes.
 std::span<const std::size_t> solver_to_basis_node_map(consts::ElementType eType)
 {
   static constexpr std::array<std::size_t, 3> tri3{1, 2, 0};
@@ -173,6 +187,10 @@ std::span<const std::size_t> solver_to_basis_node_map(consts::ElementType eType)
   }
 }
 
+/// Map a single solver-local node index to its FE Basis node index for eType by
+/// applying solver_to_basis_node_map (identity when no permutation is
+/// registered). Throws BasisNodeOrderingException when solver_node is negative
+/// or falls outside the element's node map.
 std::size_t basis_index_for_solver_node(consts::ElementType eType, const int solver_node)
 {
   if (solver_node < 0) {
@@ -194,6 +212,10 @@ std::size_t basis_index_for_solver_node(consts::ElementType eType, const int sol
           " is outside node map for " + solver_element_name(eType));
 }
 
+/// Build a 3-component FE Basis reference coordinate from column g of the solver
+/// xi array, zero-filling the trailing components that are inactive for
+/// lower-dimensional elements. Throws BasisConfigurationException when xi has
+/// fewer rows than the basis reference dimension.
 fe::math::Vector<fe::Real, 3> make_basis_point(const febasis::BasisFunction& basis,
                                                const int g,
                                                const Array<double>& xi)
@@ -214,6 +236,10 @@ fe::math::Vector<fe::Real, 3> make_basis_point(const febasis::BasisFunction& bas
   return point;
 }
 
+/// Scatter FE Basis values and gradients (in ReferenceNodeLayout order) into the
+/// solver N and Nx arrays at Gauss point g, permuting into solver node order via
+/// basis_index_for_solver_node. Validates the value and gradient counts against
+/// eNoN and zeroes unused gradient rows.
 void copy_basis_values_to_solver_arrays(consts::ElementType eType,
                                         const int eNoN,
                                         const int g,
@@ -254,6 +280,9 @@ void copy_basis_values_to_solver_arrays(consts::ElementType eType,
   }
 }
 
+/// Evaluate the cached FE Basis for eType at Gauss point g and write the solver
+/// N and Nx arrays. Nx holds reference-space gradients only; physical-coordinate
+/// derivatives are formed later by the solver from the mapping Jacobian.
 void evaluate_basis_values_and_gradients(const int insd,
                                          consts::ElementType eType,
                                          const int eNoN,
@@ -279,6 +308,8 @@ void evaluate_basis_values_and_gradients(const int insd,
   copy_basis_values_to_solver_arrays(eType, eNoN, g, values, gradients, N, Nx);
 }
 
+/// evaluate_basis_values_and_gradients specialized to a faceType, using the
+/// face's own reference dimension (xi rows) and N/Nx storage.
 void evaluate_face_basis_values_and_gradients(const int gaus_pt, faceType& face)
 {
   evaluate_basis_values_and_gradients(
@@ -291,6 +322,9 @@ void evaluate_face_basis_values_and_gradients(const int gaus_pt, faceType& face)
       face.Nx);
 }
 
+/// Number of packed second-derivative components the solver Nxx stores for a
+/// given reference dimension: 1 in 1D, 3 in 2D, 6 in 3D. Throws
+/// BasisConfigurationException for any other dimension.
 int required_nxx_components_for_dimension(const int dimension)
 {
   switch (dimension) {
@@ -306,6 +340,10 @@ int required_nxx_components_for_dimension(const int dimension)
   }
 }
 
+/// Scatter FE Basis Hessians (in ReferenceNodeLayout order) into the packed
+/// solver Nxx array at Gauss point g, permuting into solver node order. Packing
+/// is [dxx, dyy, dxy] in 2D and [dxx, dyy, dzz, dxy, dyz, dxz] in 3D. Validates
+/// the Hessian count against eNoN and the Nxx row count against the dimension.
 void copy_basis_hessians_to_solver_nxx(consts::ElementType eType,
                                        const int eNoN,
                                        const int g,
@@ -354,6 +392,9 @@ void copy_basis_hessians_to_solver_nxx(consts::ElementType eType,
   }
 }
 
+/// Evaluate the cached FE Basis Hessians for eType at Gauss point gaus_pt and
+/// write the packed solver Nxx array. Validates insd and ind2 against the basis
+/// reference dimension and the required packed-component count.
 void evaluate_basis_hessians(const int insd,
                              const int ind2,
                              consts::ElementType eType,
@@ -384,6 +425,8 @@ void evaluate_basis_hessians(const int insd,
   copy_basis_hessians_to_solver_nxx(eType, eNoN, gaus_pt, basis.dimension(), hessians, Nxx);
 }
 
+/// Shape data for a point (0-D) face: a single unit basis value with zero
+/// derivatives. Used for the PNT face case, which has no FE Basis evaluator.
 void set_point_face_shape_data(const int gaus_pt, faceType& face)
 {
   face.N(0, gaus_pt) = 1.0;
@@ -438,7 +481,7 @@ void get_gip(Simulation* simulation, faceType& face)
 void get_gnn(const int insd, consts::ElementType eType, const int eNoN, const int g, Array<double>& xi, 
     Array<double>& N, Array3<double>& Nx)
 {
-  if (!use_basis_adapter_for(eType)) {
+  if (!to_fe_element_type(eType).has_value()) {
     fe::raise<febasis::BasisElementCompatibilityException>(SVMP_HERE,
         "[get_gnn] FE Basis does not support solver element " + solver_element_name(eType));
   }
@@ -505,7 +548,7 @@ void get_gn_nxx(const int insd, const int ind2, consts::ElementType eType, const
     return;
   }
 
-  if (!use_basis_adapter_for(eType)) {
+  if (!to_fe_element_type(eType).has_value()) {
     fe::raise<febasis::BasisElementCompatibilityException>(SVMP_HERE,
         "[get_gn_nxx] FE Basis Hessian evaluation does not support solver element " +
             solver_element_name(eType));