Provide tril([out] Matrix, [in] Matrix, int, Phase)

[byjtew]

Allocate and gather the lower/upper triangular portion of a matrix

Parameters:

• L / U: Output matrix
  The lower/upper triangular portion of A in sparse format.
• A: Input matrix
  Matrix to extract the triangular portion from.
• k: integer (optional)
  The topmost diagonal of the triangular portion to extract

Signature of tril(L, A, k, phase) (triu(L, A, k, phase) is implicit)

/**
 * Return the lower triangular portion of a matrix, strictly below the diagonal
 * starting at the k-th column (included).
 * 
 * Out-of-place variant.
 *
 * @tparam descr      The descriptor to be used (descriptors::no_operation
 * 					  if left unspecified).
 * @tparam InputType  The type of the elements in the supplied ALP/GraphBLAS
 *                    matrix \a A.
 * @tparam OutputType The type of the elements in the supplied ALP/GraphBLAS
 *                    matrix \a L.
 *
 * @param[out] L       The lower triangular portion of \a A, strictly below
 * 					   the k-th diagonal.
 * @param[in]  A       Any ALP/GraphBLAS matrix.
 * @param[in]  k       The smallest column of the diagonal above which to zero out \a A.
 * @param[in]  phase   The #grb::Phase in which the primitive is to proceed.
 *
 * @return grb::SUCCESS  When the call completed successfully.
 * @return grb::MISMATCH If the dimensions of \a L and \a A do not match.
 * 
 * \parblock
 * \par Parameter \a k
 * If you want to extract the strict lower triangular portion of a matrix \a A 
 * (without its main diagonal), you can use the following call:
 *        grb::tril( L, A, 1 );
 * \par Extract the main diagonal
 * If you want to extract the main diagonal of \a A, 
 * you can use the following calls:
 * 			grb::triu( U, A, 0 );
 *        	grb::tril( L, U, 0 );
 * \endparblock
 *
 * \parblock
 * \par Allowed descriptors
 * - transpose_matrix: Consider A^T instead of A.
 * - no_casting: If the types of \a L and \a A differ, the primitive
 * 				 will fail.
 * \endparblock
 */
template<
	Descriptor descr = descriptors::no_operation,
	typename InputType,
	typename OutputType,
	typename RIT_L, typename CIT_L, typename NIT_L,
	typename RIT_A, typename CIT_A, typename NIT_A,
	Backend implementation
>
RC tril(
	Matrix< OutputType, implementation, RIT_L, CIT_L, NIT_L > & L,
	const Matrix< InputType, implementation, RIT_A, CIT_A, NIT_A > & A,
	const long int k,
	const Phase &phase = Phase::EXECUTE,
	const typename std::enable_if<
		!grb::is_object< OutputType >::value &&
		!grb::is_object< InputType >::value &&
		std::is_convertible< InputType, OutputType >::value
	>::type * const = nullptr
) {
	(void) L;
	(void) A;
	(void) k;
	(void) phase;
#ifdef _DEBUG
	std::cerr << "Selected backend does not implement grb::tril()\n";
#endif
#ifndef NDEBUG
	const bool selected_backend_does_not_support_tril = false;
	assert( selected_backend_does_not_support_tril );
#endif
	const RC ret = grb::clear( L );
	return ret == SUCCESS ? UNSUPPORTED : ret;
}

/**
 * Return the lower triangular portion of a matrix, strictly below the diagonal
 * starting at the k-th column (included).
 * 
 * Out-of-place variant.
 * 
 * This primitive is strictly equivalent to calling
 * grb::tril( L, A, 0, phase ).
 *
 * see grb::tril( L, A, k, phase ) for full description.
 */
template<
	Descriptor descr = descriptors::no_operation,
	typename InputType,
	typename OutputType,
	typename RIT_L, typename CIT_L, typename NIT_L,
	typename RIT_A, typename CIT_A, typename NIT_A,
	Backend implementation
>
RC tril(
	Matrix< OutputType, implementation, RIT_L, CIT_L, NIT_L > & L,
	const Matrix< InputType, implementation, RIT_A, CIT_A, NIT_A > & A,
	const Phase &phase = Phase::EXECUTE,
	const typename std::enable_if<
		!grb::is_object< OutputType >::value &&
		!grb::is_object< InputType >::value &&
		std::is_convertible< InputType, OutputType >::value
	>::type * const = nullptr
) {
	return tril< descr >( L, A, 0, phase );
}