Documentation for module cp_fm_types

represent a full matrix distributed on many processors

source: cp_fm_types.F
Loading...

public Types:

cp_fm_type
represent a full matrix
cp_fm_p_type
just to build arrays of pointers to matrices
copy_info_type
Stores the state of a copy between cp_fm_start_copy_general and cp_fm_finish_copy_general

Generic procedures:

cp_fm_to_fm

public Subroutines/Functions:

...
Completes the copy operation: wait for comms clean up MPI state
General copy of a fm matrix to another fm matrix. Uses non-blocking MPI rather than ScaLAPACK.
creates a new full matrix with the given structure
Completes the copy operation: wait for comms, unpack, clean up MPI state
SUBROUTINE
cp_fm_get_diag (matrix, diag)
returns the diagonal elements of a fm
returns an element of a fm this value is valid on every cpu using this call is expensive
returns all kind of information about the full matrix
FUNCTION
INTEGER
cp_fm_get_mm_type
...
gets a submatrix of a full matrix op(target_m)(1:n_rows,1:n_cols) =fm(start_row:start_row+n_rows,start_col:start_col+n_cols) target_m is replicated on all cpus using this call is expensive
FUNCTION
INTEGER
cp_fm_indxg2l (indxglob, nb, iproc, isrcproc, nprocs)
wrapper to scalapack function INDXG2L that computes the local index of a distributed matrix entry pointed to by the global index INDXGLOB.
FUNCTION
INTEGER
cp_fm_indxg2p (indxglob, nb, iproc, isrcproc, nprocs)
wrapper to scalapack function INDXG2P that computes the process coordinate which posseses the entry of a distributed matrix specified by a global index INDXGLOB.
FUNCTION
INTEGER
cp_fm_indxl2g (indxloc, nb, iproc, isrcproc, nprocs)
wrapper to scalapack function INDXL2G that computes the global index of a distributed matrix entry pointed to by the local index INDXLOC of the process indicated by IPROC.
fills a matrix with random numbers
find the maximum over the rows of the sum of the absolute values of the elements of a given row = || A ||_infinity
find the maximum absolute value of the matrix element maxval(abs(matrix))
...
SUBROUTINE
cp_fm_release (matrix)
releases a full matrix
SUBROUTINE
cp_fm_retain (matrix)
retains a full matrix
SUBROUTINE
cp_fm_setup (mult_type)
...
set all elements of a matrix to the same value, and optionally the diagonal to a different one
sets an element of a matrix
sets a submatrix of a full matrix fm(start_row:start_row+n_rows,start_col:start_col+n_cols) = alpha*op(new_values)(1:n_rows,1:n_cols)+ beta * fm(start_row:start_row+n_rows,start_col:start_col+n_cols)
Initiates the copy operation: get distribution data, post MPI isend and irecvs
copy just a part ot the matrix
copy just a triangular matrix
find the inorm of each column norm_{j}= sqrt( \sum_{i} A_{ij}*A_{ij} )
summing up all the elements along the matrix's i-th index
Write out a full matrix in plain text.
...

public Types:

TYPE :: copy_info_type

Stores the state of a copy between cp_fm_start_copy_general and cp_fm_finish_copy_general


INTEGER
:: send_size ...
INTEGER,
DIMENSION(2) :: nlocal_recv ...
INTEGER,
DIMENSION(2) :: nblock_src ...
INTEGER,
DIMENSION(2) :: src_num_pe ...
INTEGER,
DIMENSION(:), POINTER :: send_request ...
INTEGER,
DIMENSION(:), POINTER :: recv_request ...
INTEGER,
DIMENSION(:), POINTER :: recv_disp ...
INTEGER,
DIMENSION(:), POINTER :: recv_col_indices ...
INTEGER,
DIMENSION(:), POINTER :: recv_row_indices ...
INTEGER,
DIMENSION(:,:), POINTER :: src_blacs2mpi ...
REAL(dp),
DIMENSION(:), POINTER :: recv_buf ...
REAL(dp),
DIMENSION(:), POINTER :: send_buf ...

TYPE :: cp_fm_p_type

just to build arrays of pointers to matrices


TYPE(cp_fm_type),
POINTER :: matrix the pointer to the matrix

TYPE :: cp_fm_type

represent a full matrix


CHARACTER(60)
:: name the name of the matrix, used for printing
INTEGER
:: id_nr identification number that makes this matrix unique
INTEGER
:: ref_count ...
INTEGER
:: print_count sequential number to make the printed files unique
LOGICAL
:: use_sp ...
POINTER :: matrix_struct structure of this matrix
REAL(dp),
DIMENSION(:,:), POINTER :: local_data array with the data of the matrix (its contents depend on the matrix type used: in parallel runs it will be in scalapack format, in sequential, it will simply contain the matrix)
REAL(sp),
DIMENSION(:,:), POINTER :: local_data_sp ...


Generic procedure cp_fm_to_fm

...

TYPE(cp_fm_type),
POINTER
:: source ×
TYPE(cp_fm_type),
POINTER
:: destination ×
TYPE(cp_fm_type),
POINTER
:: msource ×
TYPE(cp_fm_type),
POINTER
:: mtarget ×
INTEGER,
INTENT(in)
:: ncol ×
INTEGER,
INTENT(in),
OPTIONAL
:: source_start ×
INTEGER,
INTENT(in),
OPTIONAL
:: target_start ×

SUBROUTINEcp_fm_add_to_element(matrix, irow_global, icol_global, alpha)

...

Arguments:
TYPE(cp_fm_type),
POINTER
:: matrix ...
INTEGER,
INTENT(in)
:: irow_global ...
INTEGER,
INTENT(in)
:: icol_global ...
REAL(dp),
INTENT(in)
:: alpha ...

SUBROUTINEcp_fm_cleanup_copy_general(source, info)

Completes the copy operation: wait for comms clean up MPI state

Arguments:
TYPE(cp_fm_type),
POINTER
:: source fm matrix
INTENT(inout)
:: info all of the data that will be needed to complete the copy operation

SUBROUTINEcp_fm_copy_general(source, destination, para_env)

General copy of a fm matrix to another fm matrix. Uses non-blocking MPI rather than ScaLAPACK.

Arguments:
TYPE(cp_fm_type),
POINTER
:: source input fm matrix
TYPE(cp_fm_type),
POINTER
:: destination output fm matrix
POINTER
:: para_env parallel environment corresponding to the BLACS env that covers all parts of the input and output matrices

SUBROUTINEcp_fm_create(matrix, matrix_struct, name, use_sp)

creates a new full matrix with the given structure

Arguments:
TYPE(cp_fm_type),
POINTER
:: matrix the matrix to be created
POINTER
:: matrix_struct the structure of matrix
CHARACTER(*),
INTENT(in),
OPTIONAL
:: name ...
LOGICAL,
INTENT(in),
OPTIONAL
:: use_sp ...

SUBROUTINEcp_fm_finish_copy_general(destination, info)

Completes the copy operation: wait for comms, unpack, clean up MPI state

Arguments:
TYPE(cp_fm_type),
POINTER
:: destination output fm matrix
INTENT(inout)
:: info all of the data that will be needed to complete the copy operation

SUBROUTINEcp_fm_get_diag(matrix, diag)

returns the diagonal elements of a fm

Arguments:
TYPE(cp_fm_type),
POINTER
:: matrix ...
REAL(dp),
INTENT(out)
:: diag(:) ...

SUBROUTINEcp_fm_get_element(matrix, irow_global, icol_global, alpha, local)

returns an element of a fm this value is valid on every cpu using this call is expensive

Arguments:
TYPE(cp_fm_type),
POINTER
:: matrix the matrix to read
INTEGER,
INTENT(in)
:: irow_global the row
INTEGER,
INTENT(in)
:: icol_global the col
REAL(dp),
INTENT(out)
:: alpha the value of matrix(irow_global, icol_global)
LOGICAL,
INTENT(out),
OPTIONAL
:: local true if the element is on this cpu, false otherwise

SUBROUTINEcp_fm_get_info(matrix, name, nrow_global, ncol_global, nrow_block, ncol_block, nrow_local, ncol_local, row_indices, col_indices, local_data, context, nrow_locals, ncol_locals, matrix_struct, para_env)

returns all kind of information about the full matrix

Arguments:
TYPE(cp_fm_type),
POINTER
:: matrix ...
CHARACTER(*),
INTENT(out),
OPTIONAL
:: name ...
INTEGER,
INTENT(out),
OPTIONAL
:: nrow_global ...
INTEGER,
INTENT(out),
OPTIONAL
:: ncol_global ...
INTEGER,
INTENT(out),
OPTIONAL
:: nrow_block ...
INTEGER,
INTENT(out),
OPTIONAL
:: ncol_block ...
INTEGER,
INTENT(out),
OPTIONAL
:: nrow_local ...
INTEGER,
INTENT(out),
OPTIONAL
:: ncol_local ...
INTEGER,
OPTIONAL, POINTER
:: row_indices(:) ...
INTEGER,
OPTIONAL, POINTER
:: col_indices(:) ...
REAL(dp),
POINTER, OPTIONAL
:: local_data(:,:) ...
POINTER, OPTIONAL
:: context ...
INTEGER,
OPTIONAL, POINTER
:: nrow_locals(:) ...
INTEGER,
OPTIONAL, POINTER
:: ncol_locals(:) ...
POINTER, OPTIONAL
:: matrix_struct ...
POINTER, OPTIONAL
:: para_env ...

FUNCTIONcp_fm_get_mm_type()

...

Return Value ::
INTEGER

SUBROUTINEcp_fm_get_submatrix(fm, target_m, start_row, start_col, n_rows, n_cols, transpose)

gets a submatrix of a full matrix op(target_m)(1:n_rows,1:n_cols) =fm(start_row:start_row+n_rows,start_col:start_col+n_cols) target_m is replicated on all cpus using this call is expensive

Arguments:
TYPE(cp_fm_type),
POINTER
:: fm the full you want to get the info from
REAL(dp),
INTENT(out)
:: target_m(:,:) a replicated full matrix that will contain the result
INTEGER,
INTENT(in),
OPTIONAL
:: start_row the starting row of b_matrix (defaults to 1)
INTEGER,
INTENT(in),
OPTIONAL
:: start_col the starting col of b_matrix (defaults to 1)
INTEGER,
INTENT(in),
OPTIONAL
:: n_rows the number of row to change in b (defaults to size(op(new_values),1))
INTEGER,
INTENT(in),
OPTIONAL
:: n_cols the number of columns to change in b (defaults to size(op(new_values),2))
LOGICAL,
INTENT(in),
OPTIONAL
:: transpose if target_m should be transposed: if true op(target_m)=target_m^T, else op(target_m)=target_m (defaults to false)

FUNCTIONcp_fm_indxg2l(indxglob, nb, iproc, isrcproc, nprocs)

wrapper to scalapack function INDXG2L that computes the local index of a distributed matrix entry pointed to by the global index INDXGLOB.

Return Value ::
INTEGER
Arguments:
INTEGER,
INTENT(in)
:: indxglob ...
INTEGER,
INTENT(in)
:: nb ...
INTEGER,
INTENT(in)
:: iproc ...
INTEGER,
INTENT(in)
:: isrcproc ...
INTEGER,
INTENT(in)
:: nprocs ...

FUNCTIONcp_fm_indxg2p(indxglob, nb, iproc, isrcproc, nprocs)

wrapper to scalapack function INDXG2P that computes the process coordinate which posseses the entry of a distributed matrix specified by a global index INDXGLOB.

Return Value ::
INTEGER
Arguments:
INTEGER,
INTENT(in)
:: indxglob ...
INTEGER,
INTENT(in)
:: nb ...
INTEGER,
INTENT(in)
:: iproc ...
INTEGER,
INTENT(in)
:: isrcproc ...
INTEGER,
INTENT(in)
:: nprocs ...

FUNCTIONcp_fm_indxl2g(indxloc, nb, iproc, isrcproc, nprocs)

wrapper to scalapack function INDXL2G that computes the global index of a distributed matrix entry pointed to by the local index INDXLOC of the process indicated by IPROC.

Return Value ::
INTEGER
Arguments:
INTEGER,
INTENT(in)
:: indxloc ...
INTEGER,
INTENT(in)
:: nb ...
INTEGER,
INTENT(in)
:: iproc ...
INTEGER,
INTENT(in)
:: isrcproc ...
INTEGER,
INTENT(in)
:: nprocs ...

SUBROUTINEcp_fm_init_random(matrix, ncol, start_col)

fills a matrix with random numbers

Arguments:
TYPE(cp_fm_type),
POINTER
:: matrix to be initialized
INTEGER,
INTENT(in),
OPTIONAL
:: ncol numbers of cols to fill
INTEGER,
INTENT(in),
OPTIONAL
:: start_col starting at coll number

SUBROUTINEcp_fm_maxabsrownorm(matrix, a_max)

find the maximum over the rows of the sum of the absolute values of the elements of a given row = || A ||_infinity

Arguments:
TYPE(cp_fm_type),
POINTER
:: matrix ...
REAL(dp),
INTENT(out)
:: a_max ...

SUBROUTINEcp_fm_maxabsval(matrix, a_max, ir_max, ic_max)

find the maximum absolute value of the matrix element maxval(abs(matrix))

Arguments:
TYPE(cp_fm_type),
POINTER
:: matrix ...
REAL(dp),
INTENT(out)
:: a_max ...
INTEGER,
INTENT(out),
OPTIONAL
:: ir_max ...
INTEGER,
INTENT(out),
OPTIONAL
:: ic_max ...

SUBROUTINEcp_fm_read_unformatted(fm, unit)

...

Arguments:
TYPE(cp_fm_type),
POINTER
:: fm ...
INTEGER
:: unit ...

SUBROUTINEcp_fm_release(matrix)

releases a full matrix

Arguments:
TYPE(cp_fm_type),
POINTER
:: matrix the matrix to release

SUBROUTINEcp_fm_retain(matrix)

retains a full matrix

Arguments:
TYPE(cp_fm_type),
POINTER
:: matrix the matrix to retain

SUBROUTINEcp_fm_setup(mult_type)

...

Arguments:
INTEGER
:: mult_type ...

SUBROUTINEcp_fm_set_all(matrix, alpha, beta)

set all elements of a matrix to the same value, and optionally the diagonal to a different one

Arguments:
TYPE(cp_fm_type),
POINTER
:: matrix input matrix
REAL(dp),
INTENT(in)
:: alpha scalar used to set all elements of the matrix
REAL(dp),
INTENT(in),
OPTIONAL
:: beta scalar used to set diagonal of the matrix

SUBROUTINEcp_fm_set_element(matrix, irow_global, icol_global, alpha)

sets an element of a matrix

Arguments:
TYPE(cp_fm_type),
POINTER
:: matrix ...
INTEGER,
INTENT(in)
:: irow_global ...
INTEGER,
INTENT(in)
:: icol_global ...
REAL(dp),
INTENT(in)
:: alpha ...

SUBROUTINEcp_fm_set_submatrix(fm, new_values, start_row, start_col, n_rows, n_cols, alpha, beta, transpose)

sets a submatrix of a full matrix fm(start_row:start_row+n_rows,start_col:start_col+n_cols) = alpha*op(new_values)(1:n_rows,1:n_cols)+ beta * fm(start_row:start_row+n_rows,start_col:start_col+n_cols)

Arguments:
TYPE(cp_fm_type),
POINTER
:: fm the full to change
REAL(dp),
INTENT(in)
:: new_values(:,:) a replicated full matrix with the new values
INTEGER,
INTENT(in),
OPTIONAL
:: start_row the starting row of b_matrix (defaults to 1)
INTEGER,
INTENT(in),
OPTIONAL
:: start_col the starting col of b_matrix (defaults to 1)
INTEGER,
INTENT(in),
OPTIONAL
:: n_rows the number of row to change in b (defaults to size(op(new_values),1))
INTEGER,
INTENT(in),
OPTIONAL
:: n_cols the number of columns to change in b (defaults to size(op(new_values),2))
REAL(dp),
INTENT(in),
OPTIONAL
:: alpha rescaling factor for the new values (defaults to 1.0)
REAL(dp),
INTENT(in),
OPTIONAL
:: beta rescaling factor for the old values (defaults to 0.0)
LOGICAL,
INTENT(in),
OPTIONAL
:: transpose if new_values should be transposed: if true op(new_values)=new_values^T, else op(new_values)=new_values (defaults to false)

SUBROUTINEcp_fm_start_copy_general(source, destination, para_env, info)

Initiates the copy operation: get distribution data, post MPI isend and irecvs

Arguments:
TYPE(cp_fm_type),
POINTER
:: source input fm matrix
TYPE(cp_fm_type),
POINTER
:: destination output fm matrix
POINTER
:: para_env parallel environment corresponding to the BLACS env that covers all parts of the input and output matrices
INTENT(out)
:: info all of the data that will be needed to complete the copy operation

SUBROUTINEcp_fm_to_fm_submat(msource, mtarget, nrow, ncol, s_firstrow, s_firstcol, t_firstrow, t_firstcol)

copy just a part ot the matrix

Arguments:
TYPE(cp_fm_type),
POINTER
:: msource ...
TYPE(cp_fm_type),
POINTER
:: mtarget ...
INTEGER,
INTENT(in)
:: nrow ...
INTEGER,
INTENT(in)
:: ncol ...
INTEGER,
INTENT(in)
:: s_firstrow ...
INTEGER,
INTENT(in)
:: s_firstcol ...
INTEGER,
INTENT(in)
:: t_firstrow ...
INTEGER,
INTENT(in)
:: t_firstcol ...

SUBROUTINEcp_fm_to_fm_triangular(msource, mtarget, uplo)

copy just a triangular matrix

Arguments:
TYPE(cp_fm_type),
POINTER
:: msource ...
TYPE(cp_fm_type),
POINTER
:: mtarget ...
CHARACTER(*),
INTENT(in)
:: uplo ...

SUBROUTINEcp_fm_vectorsnorm(matrix, norm_array)

find the inorm of each column norm_{j}= sqrt( \sum_{i} A_{ij}*A_{ij} )

Arguments:
TYPE(cp_fm_type),
POINTER
:: matrix ...
REAL(dp),
INTENT(out)
:: norm_array(:) ...

SUBROUTINEcp_fm_vectorssum(matrix, sum_array)

summing up all the elements along the matrix's i-th index

Arguments:
TYPE(cp_fm_type),
POINTER
:: matrix an input matrix A
REAL(dp),
INTENT(out)
:: sum_array(:) sums of elements in each column

SUBROUTINEcp_fm_write_formatted(fm, unit, header)

Write out a full matrix in plain text.

Arguments:
TYPE(cp_fm_type),
POINTER
:: fm the matrix to be outputted
INTEGER
:: unit the unit number for I/O
CHARACTER(*),
OPTIONAL
:: header optional header

SUBROUTINEcp_fm_write_unformatted(fm, unit)

...

Arguments:
TYPE(cp_fm_type),
POINTER
:: fm ...
INTEGER
:: unit ...

SUBROUTINEcp_fm_to_fm_matrix(source, destination)

copy one identically sized matrix in the other

Arguments:
TYPE(cp_fm_type),
POINTER
:: source ...
TYPE(cp_fm_type),
POINTER
:: destination ...

SUBROUTINEcp_fm_to_fm_columns(msource, mtarget, ncol, source_start, target_start)

copy just a subset of columns of a fm to a fm

Arguments:
TYPE(cp_fm_type),
POINTER
:: msource ...
TYPE(cp_fm_type),
POINTER
:: mtarget ...
INTEGER,
INTENT(in)
:: ncol ...
INTEGER,
INTENT(in),
OPTIONAL
:: source_start ...
INTEGER,
INTENT(in),
OPTIONAL
:: target_start ...