FLASH_util_prototypes.h File Reference

(r12600)

Go to the source code of this file.

Functions
double	FLASH_Max_elemwise_diff (FLA_Obj A, FLA_Obj B)
FLA_Error	FLASH_Random_matrix (FLA_Obj H)
FLA_Error	FLASH_Random_spd_matrix (FLA_Uplo uplo, FLA_Obj H)
FLA_Error	FLASH_Norm1 (FLA_Obj H, FLA_Obj norm)
FLA_Error	FLASH_Obj_shift_diagonal (FLA_Conj conj, FLA_Obj sigma, FLA_Obj H)
FLA_Error	FLASH_Set (FLA_Obj alpha, FLA_Obj H)
FLA_Error	FLASH_Obj_create_diag_panel (FLA_Obj A, FLA_Obj *U)
FLA_Error	FLASH_LU_find_zero_on_diagonal (FLA_Obj A)
FLA_Error	FLASH_Triangularize (FLA_Uplo uplo, FLA_Diag diag, FLA_Obj A)
FLA_Error	FLASH_Hermitianize (FLA_Uplo uplo, FLA_Obj A)
FLA_Error	FLASH_LU_find_zero_on_diagonal_check (FLA_Obj A)

---

Function Documentation

FLA_Error FLASH_Hermitianize	(	FLA_Uplo	uplo,
		FLA_Obj	A
	)

References FLA_Hermitianize(), FLA_Obj_free(), FLA_Obj_has_zero_dim(), FLASH_Obj_create_flat_copy_of_hier(), and FLASH_Obj_hierarchify().

{
    FLA_Error r_val;
    FLA_Obj   A_flat;

    // Exit early if one dimension is zero.
    if ( FLA_Obj_has_zero_dim( A ) ) return FLA_SUCCESS;

    // Create a temporary flat copy of the hierarchical object.
    FLASH_Obj_create_flat_copy_of_hier( A, &A_flat );

    // Hermitianize the flat matrix object as specified by uplo.
    r_val = FLA_Hermitianize( uplo, A_flat );
    
    // Copy the flat object's contents back to the hierarchical object.
    FLASH_Obj_hierarchify( A_flat, A );

    // Free the temporary flat object.
    FLA_Obj_free( &A_flat );
    
    return r_val;
}

FLA_Error FLASH_LU_find_zero_on_diagonal

(

FLA_Obj

A

)

References FLA_Check_error_level(), FLA_Cont_with_3x3_to_2x2(), FLA_LU_find_zero_on_diagonal(), FLA_Obj_elemtype(), FLA_Obj_length(), FLA_Obj_min_dim(), FLA_Part_2x2(), FLA_Repart_2x2_to_3x3(), FLASH_LU_find_zero_on_diagonal_check(), and FLASH_Obj_scalar_length().

Referenced by FLASH_LU_nopiv(), and FLASH_LU_piv().

{
  FLA_Obj ATL,   ATR,      A00,  a01,     A02, 
          ABL,   ABR,      a10t, alpha11, a12t,
                           A20,  a21,     A22;

  FLA_Error e_val;

  if ( FLA_Check_error_level() >= FLA_MIN_ERROR_CHECKING )
    FLASH_LU_find_zero_on_diagonal_check( A );

  if ( FLA_Obj_elemtype( A ) == FLA_SCALAR )
    return FLA_LU_find_zero_on_diagonal( A );

  FLA_Part_2x2( A,    &ATL, &ATR,
                      &ABL, &ABR,     0, 0, FLA_TL );

  while ( FLA_Obj_length( ATL ) < FLA_Obj_min_dim( A ) ){

    FLA_Repart_2x2_to_3x3( ATL, /**/ ATR,       &A00,  /**/ &a01,     &A02,
                        /* ************* */   /* ************************** */
                                                &a10t, /**/ &alpha11, &a12t,
                           ABL, /**/ ABR,       &A20,  /**/ &a21,     &A22,
                           1, 1, FLA_BR );

    /*------------------------------------------------------------*/

    e_val = FLA_LU_find_zero_on_diagonal( *FLASH_OBJ_PTR_AT( alpha11 ) );

    if ( e_val != FLA_SUCCESS )
      return FLASH_Obj_scalar_length( A00 ) + e_val;

    /*------------------------------------------------------------*/

    FLA_Cont_with_3x3_to_2x2( &ATL, /**/ &ATR,       A00,  a01,     /**/ A02,
                                                     a10t, alpha11, /**/ a12t,
                            /* ************** */  /* ************************ */
                              &ABL, /**/ &ABR,       A20,  a21,     /**/ A22,
                              FLA_TL );
  }

  return FLA_SUCCESS;
}

FLA_Error FLASH_LU_find_zero_on_diagonal_check

(

FLA_Obj

A

)

References FLA_Check_floating_object(), and FLA_Check_nonconstant_object().

Referenced by FLASH_LU_find_zero_on_diagonal().

{
  FLA_Error e_val;

  e_val = FLA_Check_floating_object( A );
  FLA_Check_error_code( e_val );

  e_val = FLA_Check_nonconstant_object( A );
  FLA_Check_error_code( e_val );

  return FLA_SUCCESS;
}

double FLASH_Max_elemwise_diff	(	FLA_Obj	A,
		FLA_Obj	B
	)

References FLA_Max_elemwise_diff(), FLA_Obj_free(), FLA_Obj_has_zero_dim(), and FLASH_Obj_create_flat_copy_of_hier().

{
    FLA_Obj A_flat, B_flat;
    double  max_diff;

    // Exit early if one dimension is zero.
    if ( FLA_Obj_has_zero_dim( A ) ) return -1.0;

    // Create a temporary flat copy of the hierarchical objects.
    FLASH_Obj_create_flat_copy_of_hier( A, &A_flat );
    FLASH_Obj_create_flat_copy_of_hier( B, &B_flat );

    // Get the maximum element-wise diff.
    max_diff = FLA_Max_elemwise_diff( A_flat, B_flat );
    
    // Free the temporary flat objects.
    FLA_Obj_free( &A_flat );
    FLA_Obj_free( &B_flat );
    
    return max_diff;
}

FLA_Error FLASH_Norm1	(	FLA_Obj	H,
		FLA_Obj	norm
	)

References FLA_Norm1(), FLA_Obj_free(), FLA_Obj_has_zero_dim(), FLA_Set(), FLA_ZERO, and FLASH_Obj_create_flat_copy_of_hier().

{
    FLA_Obj F;

    // Exit early if one dimension is zero.
    if ( FLA_Obj_has_zero_dim( H ) )
    {
        FLA_Set( FLA_ZERO, norm );
        return FLA_SUCCESS;
    }

    // Create a temporary flat copy of the hierarchical object.
    FLASH_Obj_create_flat_copy_of_hier( H, &F );

    // Compute the 1-norm of F and store it in norm.
    FLA_Norm1( F, norm );
    
    // Free the temporary flat object.
    FLA_Obj_free( &F );
    
    return FLA_SUCCESS;
}

FLA_Error FLASH_Obj_create_diag_panel	(	FLA_Obj	A,
		FLA_Obj *	U
	)

References FLA_Obj_datatype(), FLA_Obj_min_dim(), FLA_Part_1x2(), FLA_Part_2x2(), FLASH_Obj_create(), FLASH_Obj_scalar_length_tl(), and FLASH_Obj_scalar_min_dim().

Referenced by FLASH_LU_incpiv_opt1(), and FLASH_QR_UT_inc_opt1().

{
    FLA_Datatype datatype;
    dim_t        b_flash;
    dim_t        b_flash_last;
    dim_t        n_blocks_min_dim;
    dim_t        m_U, n_U;

    // Acquire the datatype of the matrix to be factored.
    datatype = FLA_Obj_datatype( A );

    // Acquire the storage blocksize of the top-left element.
    b_flash = FLASH_Obj_scalar_length_tl( A );

    // Get the number of storage blocks in the minimum dimension of A.
    n_blocks_min_dim = FLA_Obj_min_dim( A );

    // Compute the scalar length and width of U.
    m_U = b_flash;
    n_U = n_blocks_min_dim * b_flash;

    // Create U with storage blocksize of b_flash.
    FLASH_Obj_create( datatype, m_U, n_U, 1, &b_flash, U );

    // The last, bottom-right-most diagonal block of A might be smaller
    // than the other diagonal blocks. Compute the size of this block.
    b_flash_last = FLASH_Obj_scalar_min_dim( A ) % b_flash;

    // If the remainder is zero, then A does not need its last block
    // shrunk and thus it is ready as-is. However, if b_flash_last is
    // non-zero, then we must manually adjust the size of the last block of
    // U. Note that we are not freeing and re-allocating memory, just
    // changing the size of the view into the last block.

    if ( b_flash_last > 0 )
    {
        FLA_Obj  UL,    UR;
        FLA_Obj  URTL,  URTR,
                 URBL,  URBR;
        FLA_Obj* UR_p;

        // Repartition U so we can access the last block object.
        FLA_Part_1x2( *U,   &UL, &UR,    1, FLA_RIGHT );

        // Dereference the 1x1 object reference to get a pointer to
        // the actual block object in U.
        UR_p = FLASH_OBJ_PTR_AT( UR );

        // Repartition the last block object so that URTL is the
        // correct size.
        FLA_Part_2x2( *UR_p,    &URTL, &URTR,
                                &URBL, &URBR,     b_flash_last,
                                                  b_flash_last, FLA_TL );

        // Overwrite the original object pointed to by UR_p with the
        // corrected object URTL.
        *UR_p = URTL;
    }

    return FLA_SUCCESS;
}

FLA_Error FLASH_Obj_shift_diagonal	(	FLA_Conj	conj,
		FLA_Obj	sigma,
		FLA_Obj	H
	)

FLA_Error FLASH_Random_matrix

(

FLA_Obj

H

)

References FLA_Obj_free(), FLA_Obj_has_zero_dim(), FLA_Random_matrix(), FLASH_Obj_create_flat_copy_of_hier(), and FLASH_Obj_hierarchify().

{
    FLA_Obj F;

    // Exit early if one dimension is zero.
    if ( FLA_Obj_has_zero_dim( H ) ) return FLA_SUCCESS;

    // Create a temporary flat copy of the hierarchical object.
    FLASH_Obj_create_flat_copy_of_hier( H, &F );

    // Randomize the flat matrix object.
    FLA_Random_matrix( F );

    // Copy the flat object's contents back to the hierarchical object.
    FLASH_Obj_hierarchify( F, H );

    // Free the temporary flat object.
    FLA_Obj_free( &F );

    return FLA_SUCCESS;
}

FLA_Error FLASH_Random_spd_matrix	(	FLA_Uplo	uplo,
		FLA_Obj	H
	)

References FLA_Check_error_level(), FLA_Check_valid_uplo(), FLA_Obj_has_zero_dim(), FLA_Random_spd_matrix(), FLASH_Obj_create_flat_copy_of_hier(), FLASH_Obj_free(), and FLASH_Obj_hierarchify().

{
    FLA_Obj   F;
    FLA_Error e_val;

    if ( FLA_Check_error_level() >= FLA_MIN_ERROR_CHECKING )
    {
        e_val = FLA_Check_valid_uplo( uplo );
        FLA_Check_error_code( e_val );
    }

    // Exit early if one dimension is zero.
    if ( FLA_Obj_has_zero_dim( H ) ) return FLA_SUCCESS;

    // Create a temporary flat copy of the hierarchical object.
    FLASH_Obj_create_flat_copy_of_hier( H, &F );

    // Randomize the flat matrix object to be SPD.
    FLA_Random_spd_matrix( uplo, F );

    // Copy the flat object's contents back to the hierarchical object.
    FLASH_Obj_hierarchify( F, H );

    // Free the temporary flat object.
    FLASH_Obj_free( &F );

    return FLA_SUCCESS;
}

FLA_Error FLASH_Set	(	FLA_Obj	alpha,
		FLA_Obj	H
	)

References FLA_Obj_free(), FLA_Obj_has_zero_dim(), FLA_Set(), FLASH_Obj_create_flat_copy_of_hier(), and FLASH_Obj_hierarchify().

Referenced by FLASH_LQ_UT_solve().

{
    FLA_Obj F;

    // Exit early if one dimension is zero.
    if ( FLA_Obj_has_zero_dim( H ) ) return FLA_SUCCESS;

    // Create a temporary flat copy of the hierarchical object.
    FLASH_Obj_create_flat_copy_of_hier( H, &F );

    // Scale the flat matrix object by alpha.
    FLA_Set( alpha, F );

    // Copy the flat object's contents back to the hierarchical object.
    FLASH_Obj_hierarchify( F, H );
    
    // Free the temporary flat object.
    FLA_Obj_free( &F );
    
    return FLA_SUCCESS;
}

FLA_Error FLASH_Triangularize	(	FLA_Uplo	uplo,
		FLA_Diag	diag,
		FLA_Obj	A
	)

References FLA_Obj_free(), FLA_Obj_has_zero_dim(), FLA_Triangularize(), FLASH_Obj_create_flat_copy_of_hier(), and FLASH_Obj_hierarchify().

{
    FLA_Error r_val;
    FLA_Obj   A_flat;

    // Exit early if one dimension is zero.
    if ( FLA_Obj_has_zero_dim( A ) ) return FLA_SUCCESS;

    // Create a temporary flat copy of the hierarchical object.
    FLASH_Obj_create_flat_copy_of_hier( A, &A_flat );

    // Triangularize the flat matrix object as specified by uplo and diag.
    r_val = FLA_Triangularize( uplo, diag, A_flat );
    
    // Copy the flat object's contents back to the hierarchical object.
    FLASH_Obj_hierarchify( A_flat, A );

    // Free the temporary flat object.
    FLA_Obj_free( &A_flat );
    
    return r_val;
}