# This is a combination of 115 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.

# This is the commit message #76:

draft of selection and range views.

# This is the commit message #77:

Using default coords template param for VectorView.

# This is the commit message #78:

Added matrix-related doxygen draft. In need of compilation check (had to push to from machine without compiler support).

# This is the commit message #79:

Fixed interface compilation (need to double check buildMatrix friend functions though)

# This is the commit message #80:

Add doxygen for reference_dense vector

Also minor code cleanup.

# This is the commit message #81:

WIP blas1 interface for reference dense

# This is the commit message #82:

WIP: Add blas2 interface for reference_dense backend

# This is the commit message #83:

Fix compilation errors in denseref blas1

# This is the commit message #84:

Complete blas2 interface for denseref backend

# This is the commit message #85:

Fix compilation of vector

# This is the commit message #86:

Add possibility for VectorView to be a temporary

# This is the commit message #87:

Add VectorView tmp parameter to blas1 and blas2

# This is the commit message #88:

Add doxygen for VectorView

Provides detailed description of relevant concepts.

# This is the commit message #89:

Fix specification of tmp template parameters in blas1 and blas2

# This is the commit message #90:

Fix remaining tmp template errors in blas1

# This is the commit message #91:

Correct tmp template specializaiton in denseref VectorView

# This is the commit message #92:

Add missing tmp parameter to view source type

# This is the commit message #93:

Expand doxygen for denseref blas1

# This is the commit message #94:

Comment out performance semantics doxygen from blas1

It requires revision if still applies to the denseref backend

# This is the commit message #95:

Started working on doxygen description for level3 functions

# This is the commit message #96:

Added doxygen draft to blas3 operations

# This is the commit message #97:

compiler messages cleanup

# This is the commit message #98:

Add capacity to dense vector

# This is the commit message #99:

Expand doxygen for dense vector

# This is the commit message #100:

Inline functions to avoid "multiple definitions" linking error

# This is the commit message #101:

Remove tmp template parameter from VectorView interface.

This commit is the result of squashing the commits listed above and
cleanup of other locations where tmp parameter was introduced (doxygen,
blas3).

Revert "Add missing tmp parameter to view source type"
This reverts commit cd70999.

Revert "Correct tmp template specializaiton in denseref VectorView"
This reverts commit bdc728e.

Revert "Fix remaining tmp template errors in blas1"
This reverts commit 8821830.

Revert "Fix specification of tmp template parameters in blas1 and blas2"
This reverts commit d00b3ed.

Revert "Add VectorView tmp parameter to blas1 and blas2"
This reverts commit d009aac.

Revert "Add possibility for VectorView to be a temporary"
This reverts commit fd5bf70.

# This is the commit message #102:

Rename Identity view to Original

including related variables, typenames and doxygen fixes

# This is the commit message #103:

Rename StructuredMatrix base classes

This includes StructuredMatrixBase, StructuredMatrixContainer and
StructuredMatrixReference

# This is the commit message #104:

Remove tmp template parameter from StructuredMatrix interface

# This is the commit message #105:

Remove 'initialized' field from StructureMatrix classes

as it is already present in the underlying container grb::Matrix.
Expose that field through friend functions operaiting on
StructuredMatrix classes.

# This is the commit message #106:

Store reference instead of a pointer to a source matrix

# This is the commit message #107:

Adjust comments to reflect renaming Identity to Original view

# This is the commit message #108:

Remove 'initialized' field from VectorView

as it is already present in the underlying container grb::Vector.
Expose that field through friend functions operaiting on
VectorView.

# This is the commit message #109:

!19 Resolve internal issue #360: Make VectorView "compatible" with StructuredMatrix in terms of template parameters
This commit mainly adds Structure to the VectorView and reorders VectorView's template parameters to follow the same order as in StructuredMatrix. Doxygen is updated to reflect these changes.

In addition, there are the following changes:
* Remove VectorView's Tmp parameter from blas1 doxygen
* Use consistent ordering of template name parameters across blas 1/2/3. The order is Output, Mask, Inputs.
* Fix minor unrelated issues
* Generalize over storage scheme type for VectorView in level 1/2/3 routines

# This is the commit message #110:

!18 Resolve internal issue #357: Include capacity argument to VectorView and StructuredMatrix

# This is the commit message #111:

!20 Resolve internal issue #361: Introduce Scalar container

# This is the commit message #112:

!25 Resolve internal issue #366: Scalar version of operations at level 1

This commit introduces the following changes:
* Update ALP tests to use ALP Scalar
* Update level 1 functions to operate on ALP scalars

# This is the commit message #113:

!30 Resolve internal issue #377: Do not expose coordinates template argument in alp vectors

# This is the commit message #114:

!24 Resolves internal issue #371: Introducing Union of Bands Structure
* Using past-the-end notation for static grb::Interval
* Indent comments from MR !24
* simple example of usage in test
* Initial draft of Band structure

# This is the commit message #115:

!26 Resolve internal issue #364: Resize operations for reference dense containers

* Add resize functions for dense ALP containers
* Resize for dense containers succeeds if new_cap <= current_cap

Author: hidanielesgit

include/graphblas.hpp

@@ -526,6 +526,7 @@ namespace grb {
 // declare those.
 #include <graphblas/vector.hpp>
 #include <graphblas/matrix.hpp>
+#include <graphblas/scalar.hpp>
 
 // The aforementioned forward declarations must be in sync with the
 // declarations of the user primitives defined as free functions in the below.

include/graphblas/base/matrix.hpp

@@ -402,82 +402,9 @@ RC clear( Matrix< InputType, backend > & A ) noexcept {
 	return UNSUPPORTED;
 }
 
-/**
- * \brief An ALP structured matrix.
- *
- * This is an opaque data type for structured matrices. 
- * This container allows to maintain the interface of grb::Matrix and grb::Vector 
- * unaltered enabling back-compatibility while building on them to create
- * semantically reacher algebraic objects.
- * A structured matrix is generalized over five parameters further described 
- * below: its data type, 
- * its structure, whether it is stored using a dense or sparse storage scheme, 
- * a static view and the backend for which it is implemented.
- * At a high level of abstraction a structured matrix exposes a mathematical 
- * \em logical layout which allows to express implementation-oblivious concepts 
- * (e.g., the transpose of a symmetric matrix).
- * At the lowest level, the logical layout maps to its physical counterpart via 
- * a particular choice of a storage scheme within those exposed by the chosen 
- * backend. grb::Matrix and grb::Vector are used as interfaces to the physical
- * layout.
- * To visualize this, you could think of a band matrix. Using either the 
- * \a storage::Dense:full or \a storage::Dense:band storage schemes would require
- * the use of a \a grb::Matrix container (see include/graphblas/storage.hpp for
- * more details about the two storage schemes). However, the interpration of its 
- * content would differ in the two cases being a function of both the Structure 
- * information and the storage scheme combined.
- * 
- * Views can be used to create logical \em perspectives on top of a container. 
- * For example, I could decide to refer to the transpose of a matrix or to see 
- * a for limited part of my program a square matrix as symmetric. 
- * If a view can be expressed as concept invariant of specific runtime features,
- * such views can be defined statically (for example I can always refer to the 
- * transpose or the diagonal of a matrix irrespective of features such as its 
- * size). Other may depend on features such as the size of a matrix
- * and can be expressed as linear transformations via operations such as \a mxm 
- * (e.g., gathering/scattering the rows/columns of a matrix or permuting them).
- * Structured matrices defined as views on other matrices do not instantiate a
- * new container but refer to the one used by their targets. (See the 
- * documentation of StructuredMatrix for both scenarios within the \em denseref 
- * backend folder).
- *
- * @tparam T The type of the matrix elements. \a T shall not be a GraphBLAS
- *            type.
- * @tparam Structure  One of the matrix structures in \a grb::structures.
- * @tparam StorageSchemeType Either \em enum \a storage::Dense or \em enum 
- * 	       \a storage::Sparse.
- * 		   A StructuredMatrix will be allowed to pick among the storage schemes 
- *         within their specified \a StorageSchemeType.
- * @tparam View  One of the matrix views in \a grb::view.
- * 		   All static views except for \a view::Identity (via 
- *         \a view::identity<void> cannot instantiate a new container and only 
- *         allow to refer to an existing \a StructuredMatrix.  
- *         The \a View parameter should not be used directly by the user but 
- *         can be set using specific member types appropriately 
- *         defined by each StructuredMatrix. (See examples of StructuredMatrix 
- *         definitions within \a include/graphblas/denseref/matrix.hpp and the
- *         \a dense_structured_matrix.cpp unit test).
- * @tparam backend Allows multiple backends to implement different versions 
- *         of this data type.
- *
- * \note The presence of different combination of structures and views could 
- *       produce many specialization with lots of logic replication. We might
- *       could use some degree of inheritence to limit this.
- */
 template< typename T, typename Structure, typename StorageSchemeType, typename View, enum Backend backend >
 class StructuredMatrix {
 
-
-	/** 
-	 * Whether the container presently is initialized or not. 
-	 * We differentiate the concept of empty matrix (matrix of size \f$0\times 0\f$)
-	 * from the one of uninitialized (matrix of size \f$m\times n\f$ which was never set)
-	 * and that of zero matrix (matrix with all zero elements).
-	 * \note in sparse format a zero matrix result in an ampty data structure. Is this
-	 * used to refer to uninitialized matrix in ALP/GraphBLAS?
-	 **/
-	bool initialized;
-
 	/**
 	 * The two following members define the \em logical layout of a structured matrix:
 	 * Its structure and access relations. This is enabled only if the structured matrix
@@ -517,7 +444,7 @@ class StructuredMatrix {
 	 * When a structured matrix defines a View over another matrix, it contains a pointer
 	 * to the latter. Its type can be identified via the View parameter.
 	 */
-	using target_type = typename std::enable_if<! std::is_same<View, view::Identity<void> >::value, typename View::applied_to>::type;
+	using target_type = typename std::enable_if<! std::is_same<View, view::Original<void> >::value, typename View::applied_to>::type;
 	target_type * ref;
 
 	public :

include/graphblas/base/scalar.hpp

@@ -0,0 +1,171 @@
+
+/*
+ *   Copyright 2021 Huawei Technologies Co., Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef _H_GRB_SCALAR_BASE
+#define _H_GRB_SCALAR_BASE
+
+#include <cstdlib>  //size_t
+#include <stdexcept>
+
+#include <graphblas/backends.hpp>
+#include <graphblas/descriptors.hpp>
+#include <graphblas/ops.hpp>
+#include <graphblas/rc.hpp>
+
+namespace grb {
+
+	/**
+	 * \brief An ALP scalar.
+	 *
+	 * This is an opaque data type for scalars.
+	 *
+	 * @tparam T         The type of the vector elements. \a T shall not
+	 *                   be an ALP type.
+	 * @tparam Structure One of the structures. One of possible use cases
+	 *                   for a structured scalar is a random structure.
+	 *                   Depending on the backend implementation, this may mean,
+	 *                   for example, randomizing the scalar value on each
+	 *                   interaction with the scalar.
+	 *
+	 * \warning Creating a grb::Scalar of other ALP types is
+	 *                <em>not allowed</em>.
+	 *          Passing a ALP type as template parameter will lead to
+	 *          undefined behaviour.
+	 *
+	 */
+	template< typename T, typename Structure, enum Backend backend >
+	class Scalar {
+
+		public:
+			/** @see Vector::value_type. */
+			typedef T value_type;
+
+			/**
+			 * The default ALP scalar constructor.
+			 *
+			 * The constructed object will be uninitalised after successful construction.
+			 *
+			 *
+			 * \parblock
+			 * \par Performance semantics.
+			 *        -# This constructor entails \f$ \Theta(1) \f$ amount of work.
+			 *        -# This constructor may allocate \f$ \Theta(1) \f$ bytes
+			 *           of dynamic memory.
+			 *        -# This constructor will use \f$ \Theta(1) \f$ extra bytes of
+			 *           memory beyond that at constructor entry.
+			 *        -# This constructor incurs \f$ \Theta(1) \f$ data movement.
+			 *        -# This constructor \em may make system calls.
+			 * \endparblock
+			 *
+			 */
+			Scalar() {}
+
+			/**
+			 * The ALP scalar constructor for converting a reference to C/C++ scalar
+			 * to ALP scalar.
+			 *
+			 * The constructed object will be initialized after successful construction.
+			 *
+			 *
+			 * \parblock
+			 * \par Performance semantics.
+			 *        -# This constructor entails \f$ \Theta(1) \f$ amount of work.
+			 *        -# This constructor may allocate \f$ \Theta(1) \f$ bytes
+			 *           of dynamic memory.
+			 *        -# This constructor will use \f$ \Theta(1) \f$ extra bytes of
+			 *           memory beyond that at constructor entry.
+			 *        -# This constructor incurs \f$ \Theta(1) \f$ data movement.
+			 *        -# This constructor \em may make system calls.
+			 * \endparblock
+			 *
+			 * \warning This constructor saves the reference to the provied value.
+			 *          Therefore, the changes to the container or the value will
+			 *          be mirrored into each-other. For preserving the separation,
+			 *          use Scalar( const T ) version.
+			 *
+			 */
+			explicit Scalar( T &value ) {
+				(void)value;
+			}
+
+			/**
+			 * The ALP scalar constructor for converting a C/C++ scalar to ALP scalar.
+			 *
+			 * The constructed object will be initialized after successful construction.
+			 *
+			 *
+			 * \parblock
+			 * \par Performance semantics.
+			 *        -# This constructor entails \f$ \Theta(1) \f$ amount of work.
+			 *        -# This constructor may allocate \f$ \Theta(1) \f$ bytes
+			 *           of dynamic memory.
+			 *        -# This constructor will use \f$ \Theta(1) \f$ extra bytes of
+			 *           memory beyond that at constructor entry.
+			 *        -# This constructor incurs \f$ \Theta(1) \f$ data movement.
+			 *        -# This constructor \em may make system calls.
+			 * \endparblock
+			 *
+			 */
+			explicit Scalar( T value ) {
+				(void)value;
+			}
+
+			/**
+			 * Copy constructor.
+			 *
+			 * @param other The scalar to copy. The initialization state of the copy
+			 *              reflects the state of \a other.
+			 *
+			 * \parblock
+			 * \par Performance semantics.
+			 *        -# This constructor entails \f$ \Theta(1) \f$ amount of work.
+			 *        -# This constructor allocates \f$ \Theta(1) \f$ bytes
+			 *           of dynamic memory.
+			 *        -# This constructor incurs \f$ \Theta(1) \f$ of data
+			 *           movement.
+			 *        -# This constructor \em may make system calls.
+			 * \endparblock
+			 *
+			 */
+			Scalar( const Scalar &other ) noexcept {
+				(void)other;
+			}
+
+			/**
+			 * Move constructor. The new scalar equals the given
+			 * scalar. Invalidates the use of the input scalar.
+			 *
+			 * @param[in] other The ALP scalar to move to this new instance.
+			 *
+			 * \parblock
+			 * \par Performance semantics.
+			 *        -# This constructor entails \f$ \Theta(1) \f$ amount of work.
+			 *        -# This constructor will not allocate any new dynamic memory.
+			 *        -# This constructor will use \f$ \Theta(1) \f$ extra bytes of
+			 *           memory beyond that at constructor entry.
+			 *        -# This constructor will move \f$ \Theta(1) \f$ bytes of data.
+			 * \endparblock
+			 */
+			Scalar( Scalar &&other ) noexcept {
+				(void)other;
+			}
+
+	}; // class Scalar
+
+} // namespace grb
+
+#endif // _H_GRB_SCALAR_BASE

include/graphblas/base/vector.hpp

@@ -948,7 +948,7 @@ namespace grb {
 			}
 	};
 
-	template< typename T, typename View, typename StorageSchemeType, enum Backend backend, typename C >
+	template< typename T, typename Structure, typename StorageSchemeType, typename View, enum Backend backend >
 	class VectorView { };
 
 } // end namespace ``grb''

include/graphblas/blas1.hpp

@@ -365,6 +365,26 @@ namespace grb {
 	 *          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 OutputStructure,
+	// 	Backend backend, typename Coords
+	// >
+	// RC norm2( Scalar< OutputType, OutputStructure, backend > &x,
+	// 	const Vector< InputType, 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;
+	// }
+
+	/** Specialization for C++ scalars */
 	template<
 		Descriptor descr = descriptors::no_operation, class Ring,
 		typename InputType, typename OutputType,