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

Author: hidanielesgit

.gitignore

@@ -8,4 +8,5 @@ paths.mk
 [Bb]uild*/
 [Oo]bj*/
 [Ii]nstall*/
-cmake-build-*/
+cmake-build-*/
+.vscode/

include/graphblas/base/matrix.hpp

@@ -37,6 +37,10 @@
 #include <graphblas/descriptors.hpp>
 #include <graphblas/ops.hpp>
 #include <graphblas/rc.hpp>
+#include <graphblas/storage.hpp>
+#include <graphblas/structures.hpp>
+#include <graphblas/utils.hpp>
+#include <graphblas/views.hpp>
 
 
 namespace grb {
@@ -391,6 +395,82 @@ namespace grb {
 
 	};
 
+/**
+ * An ALP structured matrix.
+ *
+ * This is an opaque data type for that implements the below functions.
+ *
+ * @tparam T The type of the matrix elements. \a T shall not be a GraphBLAS
+ *            type.
+ * @tparam Structure  One of the matrix structures in grb::structures.
+ * @tparam view  One of the matrix views in enum grb::Views. All static views except for
+ * 		   \a Views::original disable the possibility to instantiate a new container and only
+ * 		   allow the creation of a reference to an existing \a StructuredMatrix
+ * 		   (note that this could be view itself). A view could be instanciated into a separate container
+ * 		   than its original source by explicit copy.
+ * @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.
+ */
+template< typename T, typename Structure, typename StorageSchemeType, typename View, enum Backend backend >
+class StructuredMatrix {
+
+	size_t m, n;
+
+	/**
+	 * The container's data.
+	 * The geometry and access scheme are specified by a combination of
+	 * \a Structure, \a storage_scheme, \a m, and \a n.
+	 */
+	T * __restrict__ data;
+
+	/**
+	 * The container's storage scheme. \a storage_scheme is not exposed to the user as an option
+	 * but can defined by ALP at different points in the execution depending on the \a backend choice.
+	 * For example, if the container is associated to an I/O matrix, with a reference backend
+	 * it might be set to reflect the storage scheme of the user data as specified at buildMatrix.
+	 * If \a backend is set to \a mlir then the scheme could be fixed by the JIT compiler to effectively
+	 * support its optimization strategy.
+	 * At construction time and until the moment the scheme decision is made it may be set to
+	 * an appropriate default choice, e.g. if \a StorageSchemeType is \a storage::Dense then
+	 * \a storage::Dense::full could be used.
+	 */
+	StorageSchemeType storage_scheme;
+
+	/** Whether the container presently is initialized or not. */
+	bool initialized;
+
+	public :
+
+		/**
+	     * Usable only in case of an \a original view. Otherwise the view should only reference another view.
+	     */
+		StructuredMatrix( const size_t m, const size_t n );
+
+	/**
+	 * In case of non-original views should set up the container so to share the data of other.
+	 */
+	StructuredMatrix( const StructuredMatrix< T, Structure, StorageSchemeType, View, backend > & other );
+
+	/**
+	 * Usable only in case of an \a original view. Otherwise the view should only reference another view.
+	 */
+	StructuredMatrix( StructuredMatrix< T, Structure, StorageSchemeType, View, backend > && other );
+
+	/**
+	 * When view is \a original data should be properly deallocated.
+	 */
+	~StructuredMatrix();
+};
+
+template< typename InputType, Backend backend >
+RC clear( Matrix< InputType, backend > & A ) noexcept {
+	// this is the generic stub implementation
+	return UNSUPPORTED;
+}
+
 } // end namespace ``grb''
 
 #endif // end _H_GRB_MATRIX_BASE

include/graphblas/denseref/matrix.hpp

@@ -23,11 +23,83 @@
 #ifndef _H_GRB_DENSEREF_MATRIX
 #define _H_GRB_DENSEREF_MATRIX
 
+#include <graphblas/backends.hpp>
+#include <graphblas/base/matrix.hpp>
+#include <graphblas/config.hpp>
+#include <graphblas/utils.hpp>
+#include <graphblas/ops.hpp>
+#include <graphblas/rc.hpp>
+//#include <graphblas/reference/blas1.hpp>
+//#include <graphblas/reference/compressed_storage.hpp>
+//#include <graphblas/reference/init.hpp>
+#include <graphblas/type_traits.hpp>
+#include <graphblas/utils/autodeleter.hpp>
+//#include <graphblas/utils/pattern.hpp> //for help with dealing with pattern matrix input
+
 namespace grb {
 
 	/** \internal TODO */
 	template< typename T >
 	class Matrix< T, reference_dense > {
+	private:
+		/** Our own type. */
+		typedef Matrix< T, reference_dense > self_type;
+
+		/**
+		* The number of rows.
+		*
+		* \internal Not declared const to be able to implement move in an elegant way.
+		*/
+		size_t m;
+
+		/**
+		* The number of columns.
+		*
+		* \internal Not declared const to be able to implement move in an elegant way.
+		*/
+		size_t n;
+
+		/** Whether the container presently is uninitialized. */
+		bool initialized;
+
+		std::vector< T > container;
+	public:
+		/** @see Matrix::value_type */
+		typedef T value_type;
+
+		/** @see Matrix::Matrix() */
+		Matrix( const size_t rows, const size_t columns ): m( rows ), n( columns ), initialized( false ) {
+
+		}
+
+		/** @see Matrix::Matrix( const Matrix & ) */
+		Matrix( const Matrix< T, reference_dense > &other ) : Matrix( other.m, other.n ) {
+			initialized = other.initialized;
+		}
+
+		/** @see Matrix::Matrix( Matrix&& ). */
+		Matrix( self_type &&other ) noexcept {
+			moveFromOther( std::forward< self_type >(other) );
+		}
+
+		/** * Move from temporary. */
+		self_type& operator=( self_type &&other ) noexcept {
+			moveFromOther( std::forward< self_type >(other) );
+			return *this;
+		}
+
+		/** @see Matrix::~Matrix(). */
+		~Matrix() {
+
+		}
+
+	};
+
+	// template specialisation for GraphBLAS type traits
+	template< typename T >
+	struct is_container< Matrix< T, reference_dense > > {
+		/** A reference_dense Matrix is a GraphBLAS object. */
+		static const constexpr bool value = true;
 	};
 
 } // end namespace ``grb''

include/graphblas/matrix.hpp

@@ -28,8 +28,7 @@
 
 // now include all specialisations contained in the backend directories:
 #ifdef _GRB_WITH_REFERENCE
- #include <graphblas/reference/matrix.hpp>
- #include <graphblas/denseref/matrix.hpp>
+#include <graphblas/reference/matrix.hpp>
 #endif
 #ifdef _GRB_WITH_HYPERDAGS
  #include <graphblas/hyperdags/matrix.hpp>
@@ -38,10 +37,10 @@
  #include "graphblas/nonblocking/matrix.hpp"
 #endif
 #ifdef _GRB_WITH_LPF
- #include <graphblas/bsp1d/matrix.hpp>
+#include <graphblas/bsp1d/matrix.hpp>
 #endif
 #ifdef _GRB_WITH_BANSHEE
- #include <graphblas/banshee/matrix.hpp>
+#include <graphblas/banshee/matrix.hpp>
 #endif
 
 // specify default only if requested during compilation
@@ -55,7 +54,14 @@ namespace grb {
 		typename NonzeroIndexType = config::NonzeroIndexType
 	>
 	class Matrix;
-}
+
+	/*
+	 * The default value of \a StorageSchemeType could also be made conditional (Dense or Sparse) depending on \a config::default_backend
+	 */
+	template< typename T, typename Structure, typename StorageSchemeType = storage::Dense, typename View = view::Identity< void >, enum Backend backend = config::default_backend >
+	class StructuredMatrix;
+
+} // namespace grb
 #endif
 
 #endif // end ``_H_GRB_MATRIX''

include/graphblas/storage.hpp

@@ -0,0 +1,81 @@
+/*
+ *   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.
+ */
+
+/**
+ *
+ * @file This file registers matrix storage schemes that are either
+ *       implemented, under implementation, or were at any point in time
+ *       conceived and noteworthy enough to be recorded for future consideration.
+ */
+
+#ifndef _H_GRB_STORAGE
+#define _H_GRB_STORAGE
+
+#include <tuple>
+#include <type_traits>
+
+namespace grb {
+
+	namespace storage {
+
+		/**
+		 * Collection of possible storage scheme options for dense matrices (or now including classic BLAS/LAPACK storage schemes).
+		 * \note Assumption is row-major but a complete specification might depend by a similar row/column-major option perhaps included
+		 * at the level of Matrix (general ).
+		 */
+		enum Dense {
+
+			/**
+			 * Conventional storage in a 2D array. The matrix element \f$A(i,j)\f$ is stored in array element \f$a(i,j)\f$.
+			 * Although some non-general structured matrices may forbid access to part of the array,
+			 * with this storage option a full rectangular array must be allocated.
+			 * This option could also be used as default/initial choice when a storage scheme decision has not yet been made.
+			 */
+			full,
+
+			/**
+			 * Compact 2D storage for Band matrices. An \f$m-\times-n\f$ band matrix with \f$kl\f$ subdiagonals
+			 * and \f$ku\f$ superdiagonals may be stored compactly in a 2D array with \f$m\f$ rows and \f$kl+ku+1\f$ columns.
+			 * Rows of the matrix are stored in corresponding rows of the array, and diagonals of the matrix are stored
+			 * in columns of the array.
+			 * This storage scheme should be used in practice only if \f$kl, ku \ll \min(m,n)\f$, although it should work correctly
+			 * for all values of \f$kl\f$ and \f$ku\f$.
+			 */
+			band,
+
+			/**
+			 * A tridiagonal matrix of order \f$n\f$ is stored in three 1D arrays, one of length \f$n\f$
+			 * containing the diagonal elements, and two of length \f$n-1\f$ containing the subdiagonal
+			 * and superdiagonal elements.
+			 * Symmetric tridiagonal and bidiagonal matrices are stored in two 1D arrays, one of length \f$n\f$
+			 * containing the diagonal elements, and one of length \f$n-1\f$ containing the off-diagonal elements.
+			 * A diagonal matrix is stored as a 1D array of length \f$n\f$.
+			 * Symmetric, Hermitian or triangular matrices store the relevant triangle packed by rows in a 1D array:
+			 * \li \c AlignLeft \f$A(i,j)\f$ is stored in \f$a( j + i*(i + 1)/2 )\f$ for \f$i \leq j\f$
+			 * \li \c AlignLeft \f$A(i,j)\f$ is stored in \f$a( j + i*(2*n - i - 1)/2 )\f$ for \f$j \leq i\f$
+			 */
+			array1d
+		}; // Dense
+
+		// enum Sparse {
+		//     ...
+		// };
+
+	} // namespace storage
+
+} // namespace grb
+
+#endif // _H_GRB_STORAGE