# This is a combination of 75 commits.

# This is the 1st commit message:

Issue #303: framework for reference_dense added

This commit comes from a split of the original commit whose details are as follows:
SHA1 ID: a7c1db0
Author: Albert-Jan Yzelman <yzelman@linux.fritz.box>  2022-01-14 15:52:26
Committer: Albert-Jan Yzelman <yzelman@linux.fritz.box>  2022-01-30 13:48:35

The reason for splitting is to separate the changes irrelevant to the branch 303 into a separate branch.
The split produced 3 separate commits.
This commit is number 1.
This commit in particular is relevant to 303 and will remain in it.

# This is the commit message #2:

Issue #303: unify script argument similar to --no-reference

# This is the commit message #3:

Issue #303: complete implementation of Vector< reference_dense >, modulo output iteration.

# This is the commit message #4:

Issue #303: modified vector implementation according to option 3 in handling dense container construction.

# This is the commit message #5:

Issue #303: vectors now have an iterator for the user to extract data from.

# This is the commit message #6:

Issue #303, fixed silly oops: the difference between two iterators should be an integer

# This is the commit message #7:

Issue #303: containers are now uninitialized on construction. Iteration over uninitialized containers returns nothing.

# This is the commit message #8:

Issue #303: configure and cmake now properly do make install with reference_dense

# This is the commit message #9:

Issue #303: cmake infra has updated-- make dense_reference additions compatible to it

# This is the commit message #10:

Drafting structured matrix interface using reference_dense backend

# This is the commit message #11:

Issue #303: Copy test mxm.cpp to dense_mxm.cpp as a starting point

# This is the commit message #12:

Issue #303: Add partial first version of Matrix interface for denseref

# This is the commit message #13:

Issue #303: WIP: dense mxm test

# This is the commit message #14:

Issue #303: Add dense mxm test to CMakeLists

# This is the commit message #15:

Issue #303: Separate reference and reference_dense includes

# This is the commit message #16:

Issue #303: Fix grb include name mismatch

# This is the commit message #17:

Issue #303: Add src files for reference dense backend

# This is the commit message #18:

Issue #303: Add project related option for dense backend

# This is the commit message #19:

Issue #303: Remove dense_reference-related code from reference cmake

# This is the commit message #20:

Keeping a clean separate denseref backend when building with cmake.

# This is the commit message #21:

Fix cmake option name

# This is the commit message #22:

Use a proper data container for a denseref matrix

# This is the commit message #23:

Change PRIVATE to INTERFACE for denseref backend

# This is the commit message #24:

fix cmake config for building backend

# This is the commit message #25:

Add friend functions for accessing matrix dimensions and raw data

# This is the commit message #26:

Add first version of blas3 mxm for reference dense backend

# This is the commit message #27:

Add temporary code for matrix data initialization

# This is the commit message #28:

Complete first working dense mxm unit test

# This is the commit message #29:

Added structured matrix test including draft static views and references

# This is the commit message #30:

Convert spaces to tabs

# This is the commit message #31:

Make use of operators and monoid provided to mxm

# This is the commit message #32:

Add friend getter/setter for field 'initialized' of denseref matrix

# This is the commit message #33:

Revert "Add temporary code for matrix data initialization"

This reverts commit 676cb4d.

# This is the commit message #34:

Add temporary way for allocating data of a denseref matrix

# This is the commit message #35:

Add functions to initialize matrix data from provided forward iterator

# This is the commit message #36:

Make getters const

# This is the commit message #37:

Exploit new features in mxm unit test

New features are building a matrix from an iterator and handling of
uninitialized matrices.

# This is the commit message #38:

added get/remove_ref type traits for StructuredMatrix types

# This is the commit message #39:

Temporary switch to pointers to target matrices to enable empty init.

# This is the commit message #40:

First draft of index mapping functions

# This is the commit message #41:

Cleaned up StructuredMatrix-related doxygen drafts

# This is the commit message #42:

Added to the spec draft

# This is the commit message #43:

Add alloc primitives for denseref

Currently they are a copy of the same primitives for reference backend.
Think whether it makes sense to group the alloc functions for these two
backends.

# This is the commit message #44:

Handle memory allocation failure. Implement destructor.

# This is the commit message #45:

WIP: Add data size calculator depending on Storage scheme and structure.

Also add a simple test to showcase the usage of this feature.

# This is the commit message #46:

Add buildMatrix for general full StructuredMatrix

# This is the commit message #47:

Add a check for size mismatch in buildMatrix

# This is the commit message #48:

Add mxm for dense Structured Matrices

# This is the commit message #49:

Introducing grb::get_view<> draft

# This is the commit message #50:

Add UpperTriangular StructuredMatrix (container and view)

# This is the commit message #51:

Implement polymorphic comparison of IMFs

# This is the commit message #52:

Add to structures a compatibility check from source structure and IMF functions

This is to be used when creating a view over a source matrix using
provided IMF functions. The compatibility of TargetStructure depends on
the SourceStructure and provided IMF functions. This is a runtime check.

# This is the commit message #53:

Add constructor taking two IMFs to reference SM with general structure

# This is the commit message #54:

Implement gather through view with provided TargetStructure and IMFs

# This is the commit message #55:

Add test for gathers on StructuredMatrix using views with IMFs

# This is the commit message #56:

Basic VectorView definition based on grb::vector container

# This is the commit message #57:

Draft of diagonal (vector) view of a matrix

# This is the commit message #58:

Initial get_view for VectorViews

# This is the commit message #59:

Add a stub for Storage Mapping Functions

# This is the commit message #60:

Define interface for dense StructuredMatrices and scalars

# This is the commit message #61:

Add test showcasing eWiseApply operations on Structured Matrices

# This is the commit message #62:

Minor changes for dense reference vector

# This is the commit message #63:

Add outer product of two vectors for reference_dense backend

# This is the commit message #64:

Expand the gather via IMF to general view of general Storage Matrix

# This is the commit message #65:

Add more Structures for StructuredMatrix

# This is the commit message #66:

Add dot product and norm2 in blas1 for dense reference backend

Also add a stub for a test showcasing their use

# This is the commit message #67:

WIP Constant matrix factory methods

# This is the commit message #68:

WIP Base classes for StructuredMatrix

# This is the commit message #69:

WIP Refactor StructuredMatrix using inheritance from Base classes

# This is the commit message #70:

Implement friend functions through base classes

This avoids the need to declare friend functions inside every
StructuredMatrix specialization.

# This is the commit message #71:

Add getter and setter for initialized field in StructuredMatrix

# This is the commit message #72:

Revert "WIP Constant matrix factory methods"

This reverts commit 742fe9f.

# This is the commit message #73:

Add interface for creating constant matrices

This includes Identity matrix, Zero matrix and Givens rotations

# This is the commit message #74:

Add test showcasing the use of Identity and Zero matrices

# This is the commit message #75:

Revert "WIP: Add data size calculator depending on Storage scheme and structure."

This reverts commit 1f7b6c4.

Author: hidanielesgit

CMakeLists.txt

@@ -37,7 +37,7 @@ project( GraphBLAS
 	DESCRIPTION "The ultimate engine for sparse computation"
 	LANGUAGES CXX C
 )
-set( CMAKE_CXX_STANDARD 11 )
+set( CMAKE_CXX_STANDARD 14 )
 set( CMAKE_CXX_STANDARD_REQUIRED ON )
 
 # install within the build directory by default (NOT to /usr/local or the likes)

include/graphblas/base/vector.hpp

@@ -948,6 +948,9 @@ namespace grb {
 			}
 	};
 
+	template< typename T, typename View, typename StorageSchemeType, enum Backend backend, typename C >
+	class VectorView { };
+
 } // end namespace ``grb''
 
 #endif // _H_GRB_VECTOR_BASE

include/graphblas/blas1.hpp

@@ -28,7 +28,7 @@
 #ifdef _GRB_WITH_REFERENCE
  #include <graphblas/reference/blas1.hpp>
 #endif
-#ifdef _GRB_WITH_DENSE
+#ifdef _GRB_WITH_DENSEREF
  #include <graphblas/denseref/blas1.hpp>
 #endif
 #ifdef _GRB_WITH_HYPERDAGS

include/graphblas/config.hpp

@@ -29,7 +29,7 @@
 #ifdef _GRB_WITH_REFERENCE
  #include "graphblas/reference/config.hpp"
 #endif
-#ifdef _GRB_WITH_DENSE
+#ifdef _GRB_WITH_DENSEREF
  #include "graphblas/denseref/config.hpp"
 #endif
 #ifdef _GRB_WITH_HYPERDAGS

include/graphblas/denseref/blas1.hpp

@@ -23,8 +23,255 @@
 #ifndef _H_GRB_DENSEREF_BLAS1
 #define _H_GRB_DENSEREF_BLAS1
 
+#include <graphblas/backends.hpp>
+#include <graphblas/config.hpp>
+#include <graphblas/rc.hpp>
+
 namespace grb {
 
+    /**
+     * Calculates the dot product, \f$ \alpha = (x,y) \f$, under a given additive
+     * monoid and multiplicative operator.
+     *
+     * @tparam descr      The descriptor to be used (descriptors::no_operation
+     *                    if left unspecified).
+     * @tparam Ring       The semiring type to use.
+     * @tparam OutputType The output type.
+     * @tparam InputType1 The input element type of the left-hand input vector.
+     * @tparam InputType2 The input element type of the right-hand input vector.
+     *
+     * @param[in,out]  z    The output element \f$ z + \alpha \f$.
+     * @param[in]      x    The left-hand input vector.
+     * @param[in]      y    The right-hand input vector.
+     * @param[in] addMonoid The additive monoid under which the reduction of the
+     *                      results of element-wise multiplications of \a x and
+     *                      \a y are performed.
+     * @param[in]   anyop   The multiplicative operator under which element-wise
+     *                      multiplications of \a x and \a y are performed. This can
+     *                      be any binary operator.
+     *
+     * By the definition that a dot-product operates under any additive monoid and
+     * any binary operator, it follows that a dot-product under any semiring can be
+     * trivially reduced to a call to this version instead.
+     *
+     * @return grb::MISMATCH When the dimensions of \a x and \a y do not match. All
+     *                       input data containers are left untouched if this exit
+     *                       code is returned; it will be as though this call was
+     *                       never made.
+     * @return grb::SUCCESS  On successful completion of this call.
+     *
+     * \parblock
+     * \par Performance semantics
+     *      -# This call takes \f$ \Theta(n/p) \f$ work at each user process, where
+     *         \f$ n \f$ equals the size of the vectors \a x and \a y, and
+     *         \f$ p \f$ is the number of user processes. The constant factor
+     *         depends on the cost of evaluating the addition and multiplication
+     *         operators. A good implementation uses vectorised instructions
+     *         whenever the input domains, output domain, and the operators used
+     *         allow for this.
+     *
+     *      -# This call takes \f$ \mathcal{O}(1) \f$ memory beyond the memory used
+     *         by the application at the point of a call to this function.
+     *
+     *      -# This call incurs at most
+     *         \f$ n( \mathit{sizeof}(\mathit{D1}) + \mathit{sizeof}(\mathit{D2}) ) + \mathcal{O}(p) \f$
+     *         bytes of data movement.
+     *
+     *      -# This call incurs at most \f$ \Theta(\log p) \f$ synchronisations
+     *         between two or more user processes.
+     *
+     *      -# A call to this function does result in any system calls.
+     * \endparblock
+     *
+     * \note This requires an implementation to pre-allocate \f$ \Theta(p) \f$
+     *       memory for inter-process reduction, if the underlying communication
+     *       layer indeed requires such a buffer. This buffer may not be allocated
+     *       (nor freed) during a call to this function.
+     *
+     * \parblock
+     * \par Valid descriptors
+     *   -# grb::descriptors::no_operation
+     *   -# grb::descriptors::no_casting
+     *   -# grb::descriptors::dense
+     * \endparblock
+     *
+     * If the dense descriptor is set, this implementation returns grb::ILLEGAL if
+     * it was detected that either \a x or \a y was sparse. In this case, it shall
+     * otherwise be as though the call to this function had not occurred (no side
+     * effects).
+     *
+     * \note The standard, in contrast, only specifies undefined behaviour would
+     *       occur. This implementation goes beyond the standard by actually
+     *       specifying what will happen.
+     */
+	template<
+		Descriptor descr = descriptors::no_operation,
+		class AddMonoid, class AnyOp,
+		typename OutputType, typename InputType1, typename InputType2,
+		typename InputView1, typename InputView2,
+		typename InputStorage1, typename InputStorage2,
+		typename InputCoords1, typename InputCoords2
+	>
+	RC dot( OutputType &z,
+		const VectorView< InputType1, InputView1, InputStorage1, reference_dense, InputCoords1 > &x,
+		const VectorView< InputType2, InputView2, InputStorage2, reference_dense, InputCoords2 > &y,
+		const AddMonoid &addMonoid = AddMonoid(),
+		const AnyOp &anyOp = AnyOp(),
+		const typename std::enable_if< !grb::is_object< OutputType >::value &&
+			!grb::is_object< InputType1 >::value &&
+			!grb::is_object< InputType2 >::value &&
+			grb::is_monoid< AddMonoid >::value &&
+			grb::is_operator< AnyOp >::value,
+		void >::type * const = NULL
+	) {
+		(void)z;
+		(void)x;
+		(void)y;
+		(void)addMonoid;
+		(void)anyOp;
+		// static sanity checks
+		// NO_CAST_ASSERT( ( !( descr & descriptors::no_casting ) || std::is_same< InputType1, typename AnyOp::D1 >::value ), "grb::dot",
+		// 	"called with a left-hand vector value type that does not match the first "
+		// 	"domain of the given multiplicative operator" );
+		// NO_CAST_ASSERT( ( !( descr & descriptors::no_casting ) || std::is_same< InputType2, typename AnyOp::D2 >::value ), "grb::dot",
+		// 	"called with a right-hand vector value type that does not match the second "
+		// 	"domain of the given multiplicative operator" );
+		// NO_CAST_ASSERT( ( !( descr & descriptors::no_casting ) || std::is_same< typename AddMonoid::D3, typename AnyOp::D1 >::value ), "grb::dot",
+		// 	"called with a multiplicative operator output domain that does not match "
+		// 	"the first domain of the given additive operator" );
+		// NO_CAST_ASSERT( ( !( descr & descriptors::no_casting ) || std::is_same< OutputType, typename AddMonoid::D2 >::value ), "grb::dot",
+		// 	"called with an output vector value type that does not match the second "
+		// 	"domain of the given additive operator" );
+		// NO_CAST_ASSERT( ( !( descr & descriptors::no_casting ) || std::is_same< typename AddMonoid::D3, typename AddMonoid::D2 >::value ), "grb::dot",
+		// 	"called with an additive operator whose output domain does not match its "
+		// 	"second input domain" );
+		// NO_CAST_ASSERT( ( !( descr & descriptors::no_casting ) || std::is_same< OutputType, typename AddMonoid::D3 >::value ), "grb::dot",
+		// 	"called with an output vector value type that does not match the third "
+		// 	"domain of the given additive operator" );
+
+		// dynamic sanity check
+		// const size_t n = internal::getCoordinates( y ).size();
+		// if( internal::getCoordinates( x ).size() != n ) {
+		// 	return MISMATCH;
+		// }
+
+		// // cache nnzs
+		// const size_t nnzx = internal::getCoordinates( x ).nonzeroes();
+		// const size_t nnzy = internal::getCoordinates( y ).nonzeroes();
+
+		// // catch trivial case
+		// if( nnzx == 0 && nnzy == 0 ) {
+		// 	return SUCCESS;
+		// }
+
+		// // dot will be computed out-of-place here. A separate field is needed because
+		// // of possible multi-threaded computation of the dot.
+		// OutputType oop = addMonoid.template getIdentity< OutputType >();
+
+		// if descriptor says nothing about being dense...
+		RC ret = SUCCESS;
+		// if( !( descr & descriptors::dense ) ) {
+		// 	// check if inputs are actually dense...
+		// 	if( nnzx == n && nnzy == n ) {
+		// 		// call dense implementation
+		// 		ret = internal::dot_generic< descr | descriptors::dense >( oop, x, y, addMonoid, anyOp );
+		// 	} else {
+		// 		// pass to sparse implementation
+		// 		ret = internal::dot_generic< descr >( oop, x, y, addMonoid, anyOp );
+		// 	}
+		// } else {
+		// 	// descriptor says dense, but if any of the vectors are actually sparse...
+		// 	if( nnzx < n || nnzy < n ) {
+		// 		return ILLEGAL;
+		// 	} else {
+		// 		// all OK, pass to dense implementation
+		// 		ret = internal::dot_generic< descr >( oop, x, y, addMonoid, anyOp );
+		// 	}
+		// }
+
+		// fold out-of-place dot product into existing input, and exit
+		// ret = ret ? ret : foldl( z, oop, addMonoid.getOperator() );
+		return ret;
+	}
+
+    /**
+	 * Provides a generic implementation of the dot computation on semirings by
+	 * translating it into a dot computation on an additive commutative monoid
+	 * with any multiplicative operator.
+	 *
+	 * For return codes, exception behaviour, performance semantics, template
+	 * and non-template arguments, @see grb::dot.
+	 */
+	template<
+		Descriptor descr = descriptors::no_operation, class Ring,
+		typename IOType, typename InputType1, typename InputType2,
+		typename InputView1, typename InputView2,
+		typename InputStorage1, typename InputStorage2,
+		Backend backend, typename Coords1, typename Coords2
+	>
+	RC dot( IOType &x,
+		const VectorView< InputType1, InputView1, InputStorage1, backend, Coords1 > &left,
+		const VectorView< InputType2, InputView2, InputStorage2, backend, Coords2 > &right,
+		const Ring &ring = Ring(),
+		const typename std::enable_if<
+			!grb::is_object< InputType1 >::value &&
+			!grb::is_object< InputType2 >::value &&
+			!grb::is_object< IOType >::value &&
+			grb::is_semiring< Ring >::value,
+		void >::type * const = NULL
+	) {
+		// return grb::dot< descr >( x,
+		return grb::dot( x,
+			left, right,
+			ring.getAdditiveMonoid(),
+			ring.getMultiplicativeOperator()
+		);
+	}
+
+    /**
+	 * Provides a generic implementation of the 2-norm computation.
+	 *
+	 * Proceeds by computing a dot-product on itself and then taking the square
+	 * root of the result.
+	 *
+	 * This function is only available when the output type is floating point.
+	 *
+	 * For return codes, exception behaviour, performance semantics, template
+	 * and non-template arguments, @see grb::dot.
+	 *
+	 * @param[out] x The 2-norm of \a y. The input value of \a x will be ignored.
+	 * @param[in]  y The vector to compute the norm of.
+	 * @param[in] ring The Semiring under which the 2-norm is to be computed.
+	 *
+	 * \warning This function computes \a x out-of-place. This is contrary to
+	 *          standard ALP/GraphBLAS functions that are always in-place.
+	 *
+	 * \warning A \a ring is not sufficient for computing a two-norm. This
+	 *          implementation assumes the standard <tt>sqrt</tt> function
+	 *          must be applied on the result of a dot-product of \a y with
+	 *          itself under the supplied semiring.
+	 */
+	template<
+		Descriptor descr = descriptors::no_operation, class Ring,
+		typename InputType, typename OutputType,
+        typename InputView,
+		typename InputStorage,
+		Backend backend, typename Coords
+	>
+	RC norm2( OutputType &x,
+		const VectorView< InputType, InputView, InputStorage, backend, Coords > &y,
+		const Ring &ring = Ring(),
+		const typename std::enable_if<
+			std::is_floating_point< OutputType >::value,
+		void >::type * const = NULL
+	) {
+		RC ret = grb::dot< descr >( x, y, y, ring );
+		if( ret == SUCCESS ) {
+			x = sqrt( x );
+		}
+		return ret;
+	}
+
 } // end namespace ``grb''
 
 #endif // end ``_H_GRB_DENSEREF_BLAS1''