283 provide the implementation of the masked outer product

NOTICE

@@ -33,7 +33,9 @@ to Huawei Technologies Co., Ltd. or one of its subsidiaries:
 
  - Denis Jelovina, Huawei Technologies Switzerland AG; 2022-current.
 
- - Benjamin Lozes, Huawei Technologies Switzerland AG; 2023.
+ - Benjamin Lozes, Huawei Technologies Switzerland AG; 2023-2024.
+
+ - Aleksa Milisavljevic, Huawei Technologies Switzerland AG; 2024.
 
 The experimental banshee backend has been developed in collaboration with
 Prof. Luca Benini at ETH Zuerich and his group. In particular this backend

include/graphblas/base/blas3.hpp

@@ -442,6 +442,96 @@ namespace grb {
 		return ret == SUCCESS ? UNSUPPORTED : ret;
 	}
 
+	/**
+	 * Masked outer product of two vectors. Assuming vectors \a u and \a v are
+	 * oriented column-wise, the result matrix \a A will contain \f$ uv^T \f$,
+	 * masked to non-zero values from \a mask. This is an out-of-place
+	 * function and will be updated soon to be in-place instead.
+	 *
+	 * \internal Implemented via mxm as a multiplication of a column vector with
+	 *           a row vector, while following the given mask.
+	 *
+	 * @tparam descr      The descriptor to be used. Optional; the default is
+	 *                    #grb::descriptors::no_operation.
+	 * @tparam Operator   The operator to use.
+	 * @tparam InputType1 The value type of the left-hand vector.
+	 * @tparam InputType2 The value type of the right-hand vector.
+	 * @tparam MaskType   The value type of the mask matrix.
+	 * @tparam OutputType The value type of the ouput matrix
+	 *
+	 * @param[out]  A      The output matrix.
+	 * @param[out]  mask   The mask matrix.
+	 * @param[in]   u      The left-hand input vector.
+	 * @param[in]   v      The right-hand input vector.
+	 * @param[in]   op     The operator.
+	 * @param[in]   phase  The #grb::Phase the call should execute. Optional; the
+	 *                     default parameter is #grb::EXECUTE.
+	 *
+	 * @return #grb::SUCCESS  On successful completion of this call.
+	 * @return #grb::MISMATCH Whenever the dimensions of the inputs and/or outputs
+	 *                        do not match. All input data containers are left
+	 *                        untouched if this exit code is returned; it will be
+	 *                        be as though this call was never made.
+	 * @return #grb::FAILED   If \a phase is #grb::EXECUTE, indicates that the
+	 *                        capacity of \a A was insufficient. The output
+	 *                        matrix \a A is cleared, and the call to this function
+	 *                        has no further effects.
+	 * @return #grb::OUTOFMEM If \a phase is #grb::RESIZE, indicates an
+	 *                        out-of-memory exception. The call to this function
+	 *                        shall have no other effects beyond returning this
+	 *                        error code; the previous state of \a A is retained.
+	 * @return #grb::PANIC    A general unmitigable error has been encountered. If
+	 *                        returned, ALP enters an undefined state and the user
+	 *                        program is encouraged to exit as quickly as possible.
+	 *
+	 * \par Performance semantics
+	 *
+	 * Each backend must define performance semantics for this primitive.
+	 *
+	 * @see perfSemantics
+	 */
+	template<
+		Descriptor descr = descriptors::no_operation,
+		class Operator,
+		typename InputType1, typename InputType2,
+		typename OutputType, typename MaskType,
+		typename Coords,
+		typename RIT, typename CIT, typename NIT,
+		Backend backend
+	>
+	RC outer(
+		Matrix< OutputType, backend, RIT, CIT, NIT > &A,
+		const Matrix< MaskType, backend, RIT, CIT, NIT > &mask,
+		const Vector< InputType1, backend, Coords > &u,
+		const Vector< InputType2, backend, Coords > &v,
+		const Operator &op = Operator(),
+		const Phase &phase = EXECUTE,
+		const typename std::enable_if<
+			grb::is_operator< Operator >::value &&
+			!grb::is_object< InputType1 >::value &&
+			!grb::is_object< InputType2 >::value &&
+			!grb::is_object< MaskType >::value &&
+			!grb::is_object< OutputType >::value,
+			void >::type * const = nullptr
+	) {
+		(void) A;
+		(void) mask;
+		(void) u;
+		(void) v;
+		(void) op;
+		(void) phase;
+#ifdef _DEBUG
+		std::cerr << "Selected backend does not implement grb::outer\n";
+#endif
+#ifndef NDEBUG
+		const bool selected_backend_does_not_support_masked_outer	= false;
+		assert( selected_backend_does_not_support_masked_outer );
+#endif
+		const RC ret = grb::clear( A );
+		return ret == SUCCESS ? UNSUPPORTED : ret;
+	}
+
+
 	/**
 	 * @}
 	 */

include/graphblas/bsp1d/blas3.hpp

@@ -205,6 +205,50 @@ namespace grb {
 		return internal::checkGlobalErrorStateOrClear( C, ret );
 	}
 
+	/** \internal Simply delegates to process-local backend */
+	template<
+		Descriptor descr = descriptors::no_operation,
+		class Operator,
+		typename InputType1, typename InputType2,
+		typename MaskType, typename OutputType,
+		typename Coords,
+		typename RIT, typename CIT, typename NIT
+	>
+	RC outer(
+		Matrix< OutputType, BSP1D, RIT, CIT, NIT > &A,
+		const Matrix< MaskType, BSP1D, RIT, CIT, NIT > &mask,
+		const Vector< InputType1, BSP1D, Coords > &u,
+		const Vector< InputType2, BSP1D, Coords > &v,
+		const Operator &mul = Operator(),
+		const Phase &phase = EXECUTE,
+		const typename std::enable_if<
+			grb::is_operator< Operator >::value &&
+			!grb::is_object< InputType1 >::value &&
+			!grb::is_object< InputType2 >::value &&
+			!grb::is_object< MaskType >::value &&
+			!grb::is_object< OutputType >::value,
+			void >::type * const = nullptr
+	) {
+		assert( phase != TRY );
+		RC ret = outer< descr, Operator >(
+			internal::getLocal( A ),
+			internal::getLocal( mask ),
+			internal::getLocal( u ),
+			internal::getLocal( v ),
+			mul,
+			phase
+		);
+		if( phase == RESIZE ) {
+			if( collectives<>::allreduce( ret, operators::any_or< RC >() ) != SUCCESS ) {
+				return PANIC;
+			} else {
+				return SUCCESS;
+			}
+		}
+		assert( phase == EXECUTE );
+		return internal::checkGlobalErrorStateOrClear( A, ret );
+	}
+
 } // namespace grb
 
 #endif

include/graphblas/hyperdags/blas3.hpp

@@ -257,6 +257,59 @@ namespace grb {
 		return ret;
 	}
 
+	template<
+		Descriptor descr = descriptors::no_operation,
+		class Operator,
+		typename InputType1, typename InputType2,
+		typename MaskType, typename OutputType,
+		typename Coords,
+		typename RIT, typename CIT, typename NIT
+	>
+	RC outer(
+		Matrix< OutputType, hyperdags, RIT, CIT, NIT > &A,
+		const Matrix< MaskType, hyperdags, RIT, CIT, NIT > &mask,
+		const Vector< InputType1, hyperdags, Coords > &u,
+		const Vector< InputType2, hyperdags, Coords > &v,
+		const Operator &mul = Operator(),
+		const Phase &phase = EXECUTE,
+		const typename std::enable_if<
+			grb::is_operator< Operator >::value &&
+			!grb::is_object< InputType1 >::value &&
+			!grb::is_object< InputType2 >::value &&
+			!grb::is_object< MaskType >::value &&
+			!grb::is_object< OutputType >::value,
+			void >::type * const = nullptr
+	) {
+		const RC ret = outer< descr >(
+			internal::getMatrix( A ),
+			internal::getMatrix( mask ),
+			internal::getVector( u ),
+			internal::getVector( v ),
+			mul,
+			phase
+		);
+		if( ret != SUCCESS ) { return ret; }
+		if( phase != EXECUTE ) { return ret; }
+		if( nrows( A ) == 0 || ncols( A ) == 0 ) { return ret; }
+		std::array< const void *, 0 > sourcesP{};
+		std::array< uintptr_t, 4 > sourcesC{
+			getID( internal::getVector(u) ),
+			getID( internal::getVector(v) ),
+			getID( internal::getMatrix(mask) ),
+			getID( internal::getMatrix(A) )
+		};
+		std::array< uintptr_t, 1 > destinations{
+			getID( internal::getMatrix(A) )
+		};
+		internal::hyperdags::generator.addOperation(
+			internal::hyperdags::MASKED_OUTER,
+			sourcesP.begin(), sourcesP.end(),
+			sourcesC.begin(), sourcesC.end(),
+			destinations.begin(), destinations.end()
+		);
+		return ret;
+	}
+
 	template<
 		Descriptor descr = descriptors::no_operation,
 		typename OutputType, typename InputType1, typename InputType2,

include/graphblas/hyperdags/hyperdags.hpp

@@ -386,6 +386,8 @@ namespace grb {
 
 				OUTER,
 
+				MASKED_OUTER,
+
 				UNZIP_VECTOR_VECTOR_VECTOR,
 
 				ZIP_MATRIX_VECTOR_VECTOR_VECTOR,
@@ -493,7 +495,7 @@ namespace grb {
 			};
 
 			/** \internal How many operation vertex types exist. */
-			const constexpr size_t numOperationVertexTypes = 106;
+			const constexpr size_t numOperationVertexTypes = 107;
 
 			/** \internal An array of all operation vertex types. */
 			const constexpr enum OperationVertexType
@@ -553,6 +555,7 @@ namespace grb {
 				MXM_MATRIX_MATRIX_MATRIX_SEMIRING,
 				MXM_MATRIX_MATRIX_MATRIX_MONOID,
 				OUTER,
+				MASKED_OUTER,
 				UNZIP_VECTOR_VECTOR_VECTOR,
 				ZIP_MATRIX_VECTOR_VECTOR_VECTOR,
 				ZIP_MATRIX_VECTOR_VECTOR,

include/graphblas/nonblocking/blas3.hpp

@@ -416,6 +416,52 @@ namespace grb {
 		);
 	}
 
+	template<
+		Descriptor descr = descriptors::no_operation,
+		class Operator,
+		typename InputType1, typename InputType2,
+		typename OutputType, typename MaskType,
+		typename Coords,
+		typename RIT, typename CIT, typename NIT
+	>
+	RC outer(
+		Matrix< OutputType, nonblocking, RIT, CIT, NIT > &A,
+		const Matrix< MaskType, nonblocking, RIT, CIT, NIT > &mask,
+		const Vector< InputType1, nonblocking, Coords > &u,
+		const Vector< InputType2, nonblocking, Coords > &v,
+		const Operator &mul = Operator(),
+		const Phase &phase = EXECUTE,
+		const typename std::enable_if<
+			grb::is_operator< Operator >::value &&
+			!grb::is_object< InputType1 >::value &&
+			!grb::is_object< InputType2 >::value &&
+			!grb::is_object< MaskType >::value &&
+			!grb::is_object< OutputType >::value,
+			void >::type * const = nullptr
+	) {
+		if( internal::NONBLOCKING::warn_if_not_native &&
+			config::PIPELINE::warn_if_not_native
+		) {
+			std::cerr << "Warning: outer (nonblocking) currently delegates "
+				<< "to a blocking implementation.\n"
+				<< "         Further similar such warnings will be suppressed.\n";
+			internal::NONBLOCKING::warn_if_not_native = false;
+		}
+
+		// nonblocking execution is not supported
+		// first, execute any computation that is not completed
+		internal::le.execution();
+
+		// second, delegate to the reference backend
+		return outer< descr, Operator >(
+			internal::getRefMatrix( A ),
+			internal::getRefMatrix( mask ),
+			internal::getRefVector( u ),
+			internal::getRefVector( v ),
+			mul, phase
+		);
+	}
+
 	namespace internal {
 
 		template<