tensorOps changes (#205)

* Add new tensorOps methods

* Remove explicit mentions of R1Tensor

* Fix and document gdb-printers

* Add tests for new tensorOps functions

Author: klevzoff

docs/sphinx/developmentAids.rst

@@ -2,9 +2,85 @@
 Development Aids (Coming soon)
 ###############################################################################
 
-Comming soon: documentation for
+Coming soon: documentation for
 
   - ``LvArray::arrayManipulation``
   - ``LvArray::sortedArrayManipulation``
   - ``LvArray::bufferManipulation``
   - Creating a new buffer type
+
+Debugging helpers
+=================
+
+TotalView
+---------
+
+GDB
+---
+
+``LvArray`` comes with a collection of custom `GDB pretty printers <https://sourceware.org/gdb/onlinedocs/gdb/Pretty-Printing.html>`_
+for buffer and array classes that simplify inspection of data in a debug session by adding extra member(s) to the object display
+that "views" the data in a convenient format recognizable by GDB and IDEs. This eliminates the need for users of these classes
+to understand the particular class structure and spend time obtaining and casting the actual data pointer to the right type.
+
+.. note::
+
+   In order to allow GDB to load the pretty printer script (``scripts/gdb-printers.py``), the following lines must be added to ``.gdbinit``
+   (with the proper path substituted):
+
+   .. code-block:: none
+
+      add-auto-load-safe-path /path/to/LvArray/
+      directory /path/to/LvArray/
+
+   The first line allows GDB to load python scripts located under ``LvArray`` source tree.
+   The second line adds ``LvArray`` source tree to the source path used by GDB to lookup file names, which allows it to find the
+   pretty printer script by relative path (which is how it is referenced from the compiled binary).
+   The ``.gdbinit`` file may be located under the user's home directory or current working directory where GDB is invoked.
+
+The following pretty printers are available:
+
+  - For buffer types (``StackBuffer``, ``MallocBuffer`` and ``ChaiBuffer``) the extra member ``gdb_view`` is a C-array of the appropriate type
+    and size equal to the buffer size.
+  - For multidimensional arrays and slices (``ArraySlice``, ``ArrayView`` and ``Array``) the extra member ``gdb_view`` is a multidimensional
+    C-array with the sizes equal to current runtime size of the array or slice. This only works correctly for arrays with default
+    (unpermuted) layout.
+  - For ``ArrayOfArrays`` (and consequently all of its descendants) each contained sub-array is added as a separate child that is
+    again a C-array of size equal to that of the sub-array.
+
+Example below demonstrates the difference between pretty printer output and raw output:
+
+.. code-block:: none
+
+   (gdb) p dofNumber
+   $1 = const geosx::arrayView1d & of size [10] = {gdb_view = {0, 5, 10, 15, 20, 25, 30, 35, 40, 45}}
+   (gdb) p /r dofNumber
+   $2 = (const geosx::arrayView1d &) @0x7ffcda2a8ab0: {static NDIM = 1, static USD = 0, m_dims = {data = {10}}, m_strides = {data = {1}}, m_dataBuffer = {static hasShallowCopy = <optimized out>, m_pointer = 0x55bec1de4860, m_capacity = 10, m_pointerRecord = 0x55bec1dfa5c0}, m_singleParameterResizeIndex = 0}
+
+This is how the variable is viewed in a debugging session in CLion IDE:
+
+.. code-block:: none
+
+   dofNumber = {const geosx::arrayView1d &}
+    gdb_view = {const long long [10]}
+     [0] = {const long long} 0
+     [1] = {const long long} 5
+     [2] = {const long long} 10
+     [3] = {const long long} 15
+     [4] = {const long long} 20
+     [5] = {const long long} 25
+     [6] = {const long long} 30
+     [7] = {const long long} 35
+     [8] = {const long long} 40
+     [9] = {const long long} 45
+    NDIM = {const int} 1
+    USD = {const int} 0
+    m_dims = {LvArray::typeManipulation::CArray<long, 1>}
+    m_strides = {LvArray::typeManipulation::CArray<long, 1>}
+    m_dataBuffer = {LvArray::ChaiBuffer<long long const>}
+    m_singleParameterResizeIndex = {int} 0
+
+.. warning::
+
+   GDB printers are for host-only data. Attempting to display an array or buffer whose active pointer is a device pointer may have
+   a range of outcomes, from incorrect data being displayed, to debugger crashes. The printer script is yet to be tested with ``cuda-gdb``.

scripts/gdb-printers.py

@@ -10,7 +10,7 @@ def format_array(arr):
     return '[' + ']['.join([str(arr[i]) for i in range(array_length(arr))]) + ']'
 
 
-class CxxUtilsPrinter(gdb.printing.PrettyPrinter):
+class LvArrayPrinter(gdb.printing.PrettyPrinter):
     """Base printer for LvArray classes"""
 
     def __init__(self, val):
@@ -20,14 +20,14 @@ def real_type(self):
         return self.val.type.strip_typedefs()
 
     def to_string(self):
-        return self.real_type().name
+        return str(self.real_type())
 
     def children(self):
         return [(f.name, self.val.cast(f.type)) for f in self.real_type().fields() if f.is_base_class] \
              + [(f.name, self.val[f.name]) for f in self.real_type().fields() if not f.is_base_class]
 
 
-class BufferPrinter(CxxUtilsPrinter):
+class BufferPrinter(LvArrayPrinter):
     """Base class for printing buffer contents"""
 
     def size(self):
@@ -46,15 +46,15 @@ def __setitem__(self, key, value):
         self.data()[key] = value
 
     def to_string(self):
-        return '%s of size %d' % (self.real_type().name, self.size())
+        return '%s of size %d' % (self.real_type(), self.size())
 
     def children(self):
         if self.data() != 0:
             array_type = self.value_type().array(self.size()-1)
             arr = self.data().dereference().cast(array_type)
         else:
             arr = self.data()
-        return [('gdb_view', arr)] + CxxUtilsPrinter.children(self)
+        return [('gdb_view', arr)] + LvArrayPrinter.children(self)
 
 
 class StackBufferPrinter(BufferPrinter):
@@ -77,10 +77,21 @@ def data(self):
         return self.val['m_pointer']
 
 
+class MallocBufferPrinter(BufferPrinter):
+    """Pretty-print a MallocBuffer"""
+
+    def size(self):
+        return self.val['m_capacity']
+
+    def data(self):
+        return self.val['m_data']
+
+
 def build_buffer_printer():
     pp = gdb.printing.RegexpCollectionPrettyPrinter("LvArray-buffers")
     pp.add_printer('LvArray::StackBuffer', 'LvArray::StackBuffer<.*>', StackBufferPrinter)
     pp.add_printer('LvArray::ChaiBuffer', 'LvArray::ChaiBuffer<.*>', ChaiBufferPrinter)
+    pp.add_printer('LvArray::MallocBuffer', 'LvArray::MallocBuffer<.*>', MallocBufferPrinter)
     return pp
 
 
@@ -92,7 +103,7 @@ def build_buffer_printer():
     pass
 
 
-class ArraySlicePrinter(CxxUtilsPrinter):
+class ArraySlicePrinter(LvArrayPrinter):
     """Pretty-print an ArraySlice"""
 
     def value_type(self):
@@ -111,16 +122,16 @@ def data(self):
         return self.val['m_data']
 
     def to_string(self):
-        return '%s of size %s' % (self.real_type().name, format_array(self.dims()))
+        return '%s of size %s' % (self.real_type(), format_array(self.dims()))
 
     def children(self):
         array_type = self.value_type()
         for i in range(self.ndim()):
             array_type = array_type.array(self.dims()[self.ndim() - i - 1] - 1)
-        return [('gdb_view', self.data().dereference().cast(array_type))] + CxxUtilsPrinter.children(self)
+        return [('gdb_view', self.data().dereference().cast(array_type))] + LvArrayPrinter.children(self)
 
 
-class ArrayViewPrinter(CxxUtilsPrinter):
+class ArrayViewPrinter(LvArrayPrinter):
     """Pretty-print an ArrayView"""
 
     def value_type(self):
@@ -130,25 +141,25 @@ def ndim(self):
         return self.val.type.template_argument(1)
 
     def dims(self):
-        return self.val['m_dims']
+        return self.val['m_dims']['data']
 
     def strides(self):
-        return self.val['m_strides']
+        return self.val['m_strides']['data']
 
     def data(self):
         return buffer_printer(self.val['m_dataBuffer']).data()
 
     def to_string(self):
-        return '%s of size %s' % (self.real_type().name, format_array(self.dims()))
+        return '%s of size %s' % (self.real_type(), format_array(self.dims()))
 
     def children(self):
         array_type = self.value_type()
         for i in range(self.ndim()):
             array_type = array_type.array(self.dims()[self.ndim() - i - 1] - 1)
-        return [('gdb_view', self.data().dereference().cast(array_type))] + CxxUtilsPrinter.children(self)
+        return [('gdb_view', self.data().dereference().cast(array_type))] + LvArrayPrinter.children(self)
 
 
-class ArrayOfArraysViewPrinter(CxxUtilsPrinter):
+class ArrayOfArraysViewPrinter(LvArrayPrinter):
     """Pretty-print an ArrayOfArraysView"""
 
     def value_type(self):
@@ -158,7 +169,7 @@ def data(self):
         return buffer_printer(self.val['m_values']).data()
 
     def size(self):
-        return buffer_printer(self.val['m_sizes']).size()
+        return self.val['m_numArrays']
 
     def size_of_array(self, i):
         return buffer_printer(self.val['m_sizes'])[i]
@@ -173,14 +184,14 @@ def get_array(self, i):
         return self.ptr_to_array(i).dereference().cast(self.value_type().array(self.size_of_array(i)-1))
 
     def to_string(self):
-        return '%s of size %d' % (self.real_type().name, self.size())
+        return '%s of size %d' % (self.real_type(), self.size())
 
     def child_arrays(self):
         for i in range(self.size()):
             yield str(i), self.get_array(i)
 
     def children(self):
-        return itertools.chain(CxxUtilsPrinter.children(self), self.child_arrays())
+        return itertools.chain(LvArrayPrinter.children(self), self.child_arrays())
 
 
 def build_array_printer():

src/genericTensorOps.hpp

@@ -16,13 +16,6 @@
 #include "ArraySlice.hpp"
 #include "math.hpp"
 
-/**
- * @brief Forward declaration of R1Tensor for compatability with GEOSX.
- * @note Will be removed shortly.
- */
-template< int T_dim >
-class R1TensorT;
-
 /**
  * @name Initialization and assignment macros.
  * @brief Macros that aid in to initializng and assigning to common vector and matrix sizes.
@@ -156,18 +149,25 @@ namespace tensorOps
 namespace internal
 {
 
+HAS_STATIC_MEMBER( SIZE );
+HAS_STATIC_MEMBER( NDIM );
+
 /**
- * @brief Verify at compile time that the size of the R1Tensor is as expected.
- * @tparam PROVIDED_SIZE The size the R1Tensor should be.
- * @tparam INFERRED_SIZE The size of the R1Tensor.
- * TODO: Remove this.
+ * @brief Verify at compile time that the size of a user-provided type is as expected.
+ * @tparam ISIZE The size the array should be.
+ * @tparam T The provided type.
+ * @param src The value to check.
+ * @note This overload is enabled for user-defined types that expose a compile-time size
+ *       parameter through a public static integral member variable SIZE
  */
-template< std::ptrdiff_t PROVIDED_SIZE, int INFERRED_SIZE >
+template< std::ptrdiff_t ISIZE, typename T >
 LVARRAY_HOST_DEVICE inline constexpr
-void checkSizes( R1TensorT< INFERRED_SIZE > const & )
+std::enable_if_t< HasStaticMember_SIZE< T > >
+checkSizes( T const & src )
 {
-  static_assert( PROVIDED_SIZE == INFERRED_SIZE,
-                 "Expected the first dimension of size PROVIDED_N, got an array of size INFERRED_N." );
+  static_assert( ISIZE == T::SIZE,
+                 "Expected the first dimension of size ISIZE, got an type of size T::SIZE." );
+  LVARRAY_UNUSED_VARIABLE( src );
 }
 
 /**
@@ -216,7 +216,8 @@ void checkSizes( T const ( &src )[ INFERRED_M ][ INFERRED_N ] )
  */
 template< std::ptrdiff_t ISIZE, typename ARRAY >
 LVARRAY_HOST_DEVICE inline CONSTEXPR_WITHOUT_BOUNDS_CHECK
-void checkSizes( ARRAY const & array )
+std::enable_if_t< HasStaticMember_NDIM< ARRAY > >
+checkSizes( ARRAY const & array )
 {
   static_assert( ARRAY::NDIM == 1, "Must be a 1D array." );
   #ifdef LVARRAY_BOUNDS_CHECK
@@ -235,7 +236,8 @@ void checkSizes( ARRAY const & array )
  */
 template< std::ptrdiff_t ISIZE, std::ptrdiff_t JSIZE, typename ARRAY >
 LVARRAY_HOST_DEVICE inline CONSTEXPR_WITHOUT_BOUNDS_CHECK
-void checkSizes( ARRAY const & array )
+std::enable_if_t< HasStaticMember_NDIM< ARRAY > >
+checkSizes( ARRAY const & array )
 {
   static_assert( ARRAY::NDIM == 2, "Must be a 1D array." );
 #ifdef LVARRAY_BOUNDS_CHECK
@@ -486,6 +488,28 @@ void scaledCopy( DST_MATRIX && LVARRAY_RESTRICT_REF dstMatrix,
   }
 }
 
+/**
+ * @brief Add @p value to @p dstVector.
+ * @tparam M The length of @p dstVector.
+ * @tparam DST_VECTOR The type of @p dstVector.
+ * @param dstVector The destination vector, of length M.
+ * @param value The value to add.
+ * @details Performs the operation @code dstVector[ i ] += value @endcode
+ */
+template< std::ptrdiff_t M, typename DST_VECTOR >
+LVARRAY_HOST_DEVICE CONSTEXPR_WITHOUT_BOUNDS_CHECK inline
+void addScalar( DST_VECTOR && LVARRAY_RESTRICT_REF dstVector,
+                std::remove_reference_t< decltype( dstVector[0] ) > const value )
+{
+  static_assert( M > 0, "M must be greater than zero." );
+  internal::checkSizes< M >( dstVector );
+
+  for( std::ptrdiff_t i = 0; i < M; ++i )
+  {
+    dstVector[ i ] += value;
+  }
+}
+
 /**
  * @brief Add @p srcVector to @p dstVector.
  * @tparam ISIZE The length of @p dstVector and @p srcVector.
@@ -772,6 +796,33 @@ void Rij_eq_AiBj( DST_MATRIX && LVARRAY_RESTRICT_REF dstMatrix,
   }
 }
 
+/**
+ * @brief Perform the outer product of @p vectorA with itself writing the result to @p dstMatrix.
+ * @tparam M The size of both dimensions of @p dstMatrix and the length of @p vectorA.
+ * @tparam DST_MATRIX The type of @p dstMatrix.
+ * @tparam VECTOR_A The type of @p vectorA.
+ * @param dstMatrix The matrix the result is written to, of size M x N.
+ * @param vectorA The first vector in the outer product, of length M.
+ * @details Performs the operations @code dstMatrix[ i ][ j ] = vectorA[ i ] * vectorA[ j ] @endcode
+ */
+template< std::ptrdiff_t M, typename DST_MATRIX, typename VECTOR_A >
+LVARRAY_HOST_DEVICE CONSTEXPR_WITHOUT_BOUNDS_CHECK inline
+void Rij_eq_AiAj( DST_MATRIX && LVARRAY_RESTRICT_REF dstMatrix,
+                  VECTOR_A const & LVARRAY_RESTRICT_REF vectorA )
+{
+  static_assert( M > 0, "M must be greater than zero." );
+  internal::checkSizes< M, M >( dstMatrix );
+  internal::checkSizes< M >( vectorA );
+
+  for( std::ptrdiff_t i = 0; i < M; ++i )
+  {
+    for( std::ptrdiff_t j = 0; j < M; ++j )
+    {
+      dstMatrix[ i ][ j ] = vectorA[ i ] * vectorA[ j ];
+    }
+  }
+}
+
 /**
  * @brief Perform the outer product of @p vectorA and @p vectorB adding the result to @p dstMatrix.
  * @tparam ISIZE The size of the first dimension of @p dstMatrix and the length of @p vectorA.

src/typeManipulation.hpp

@@ -79,6 +79,24 @@ public: \
 #define HAS_MEMBER_FUNCTION_NO_RTYPE( NAME, ... ) \
   IS_VALID_EXPRESSION( HasMemberFunction_ ## NAME, CLASS, std::declval< CLASS & >().NAME( __VA_ARGS__ ) )
 
+/**
+ * @brief Macro that expands to a static constexpr bool templated on a type that is only true when
+ *        the type has a nested type (or type alias) called @p NAME.
+ *        The name of the boolean variable is HasMemberType_ ## @p NAME.
+ * @param NAME The name of the type to look for.
+ */
+#define HAS_MEMBER_TYPE( NAME ) \
+  IS_VALID_EXPRESSION( HasMemberType_ ## NAME, CLASS, std::declval< typename CLASS::NAME >() )
+
+/**
+ * @brief Macro that expands to a static constexpr bool templated on a type that is only true when
+ *        the type has a static member called @p NAME.
+ *        The name of the boolean variable is HasStaticMember_ ## @p NAME.
+ * @param NAME The name of the variable to look for.
+ */
+#define HAS_STATIC_MEMBER( NAME ) \
+  IS_VALID_EXPRESSION( HasStaticMember_ ## NAME, CLASS, std::enable_if_t< !std::is_member_pointer< decltype( &CLASS::NAME ) >::value, bool >{} )
+
 namespace LvArray
 {