represent a full matrix distributed on many processors More...

Data Types
type	copy_info_type
	Stores the state of a copy between cp_fm_start_copy_general and cp_fm_finish_copy_general. More...

type	cp_fm_p_type
	just to build arrays of pointers to matrices More...

interface	cp_fm_release

interface	cp_fm_to_fm

type	cp_fm_type
	represent a full matrix More...

Functions/Subroutines
subroutine, public	cp_fm_create (matrix, matrix_struct, name, use_sp)
	creates a new full matrix with the given structure

subroutine, public	cp_fm_init_random (matrix, ncol, start_col)
	fills a matrix with random numbers

subroutine, public	cp_fm_set_all (matrix, alpha, beta)
	set all elements of a matrix to the same value, and optionally the diagonal to a different one

subroutine, public	cp_fm_get_diag (matrix, diag)
	returns the diagonal elements of a fm

subroutine, public	cp_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

subroutine, public	cp_fm_set_element (matrix, irow_global, icol_global, alpha)
	sets an element of a matrix

subroutine, public	cp_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

subroutine, public	cp_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

subroutine, public	cp_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

subroutine, public	cp_fm_write_info (matrix, io_unit)
	Write nicely formatted info about the FM to the given I/O unit (including the underlying FM struct)

subroutine, public	cp_fm_maxabsval (matrix, a_max, ir_max, ic_max)
	find the maximum absolute value of the matrix element maxval(abs(matrix))

subroutine, public	cp_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

subroutine, public	cp_fm_vectorsnorm (matrix, norm_array)
	find the inorm of each column norm_{j}= sqrt( \sum_{i} A_{ij}*A_{ij} )

subroutine, public	cp_fm_vectorssum (matrix, sum_array, dir)
	summing up all the elements along the matrix's i-th index \( \mathrm{sum}_{j} = \sum_{i} A_{ij} \) or \( \mathrm{sum}_{i} = \sum_{j} A_{ij} \)

subroutine, public	cp_fm_to_fm_triangular (msource, mtarget, uplo)
	copy just a triangular matrix

subroutine, public	cp_fm_to_fm_submat (msource, mtarget, nrow, ncol, s_firstrow, s_firstcol, t_firstrow, t_firstcol)
	copy just a part ot the matrix

subroutine, public	cp_fm_copy_general (source, destination, para_env)
	General copy of a fm matrix to another fm matrix. Uses non-blocking MPI rather than ScaLAPACK.

subroutine, public	cp_fm_start_copy_general (source, destination, para_env, info)
	Initiates the copy operation: get distribution data, post MPI isend and irecvs.

subroutine, public	cp_fm_finish_copy_general (destination, info)
	Completes the copy operation: wait for comms, unpack, clean up MPI state.

subroutine, public	cp_fm_cleanup_copy_general (info)
	Completes the copy operation: wait for comms clean up MPI state.

subroutine, public	cp_fm_to_fm_submat_general (source, destination, nrows, ncols, s_firstrow, s_firstcol, d_firstrow, d_firstcol, global_context)
	General copy of a submatrix of fm matrix to a submatrix of another fm matrix. The two matrices can have different contexts.

subroutine, public	cp_fm_add_to_element (matrix, irow_global, icol_global, alpha)
	...

subroutine, public	cp_fm_write_unformatted (fm, unit)
	...

subroutine, public	cp_fm_write_formatted (fm, unit, header, value_format)
	Write out a full matrix in plain text.

subroutine, public	cp_fm_read_unformatted (fm, unit)
	...

subroutine, public	cp_fm_setup (mm_type)
	...

integer function, public	cp_fm_get_mm_type ()
	...

integer function, public	cp_fm_pilaenv (ictxt, prec)
	...

Detailed Description

represent a full matrix distributed on many processors

History: 3) separated structure object, removed globenv, renamed to full matrix many changes (fawzi 08.2002)

Author: Matthias Krack (22.05.2001)

Function/Subroutine Documentation

◆ cp_fm_create()

subroutine, public cp_fm_types::cp_fm_create	(	type(cp_fm_type), intent(out)	matrix,
		type(cp_fm_struct_type), intent(in), target	matrix_struct,
		character(len=*), intent(in), optional	name,
		logical, intent(in), optional	use_sp
	)

creates a new full matrix with the given structure

Parameters

matrix	the matrix to be created
matrix_struct	the structure of matrix
name	...
use_sp	...

History: 08.2002 created [fawzi]

Author: Fawzi Mohamed

Note: preferred allocation routine

Definition at line 163 of file cp_fm_types.F.

Here is the call graph for this function:

◆ cp_fm_init_random()

subroutine, public cp_fm_types::cp_fm_init_random	(	type(cp_fm_type), intent(in)	matrix,
		integer, intent(in), optional	ncol,
		integer, intent(in), optional	start_col
	)

fills a matrix with random numbers

Parameters

matrix	: to be initialized
ncol	: numbers of cols to fill
start_col	: starting at coll number

Author: Joost VandeVondele

Note: the value of a_ij is independent of the number of cpus

Definition at line 444 of file cp_fm_types.F.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ cp_fm_set_all()

subroutine, public cp_fm_types::cp_fm_set_all	(	type(cp_fm_type), intent(in)	matrix,
		real(kind=dp), intent(in)	alpha,
		real(kind=dp), intent(in), optional	beta
	)

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

Parameters

matrix	input matrix
alpha	scalar used to set all elements of the matrix
beta	scalar used to set diagonal of the matrix

Note: can be used to zero a matrix can be used to create a unit matrix (I-matrix) alpha=0.0_dp beta=1.0_dp

Definition at line 527 of file cp_fm_types.F.

Here is the call graph for this function:

◆ cp_fm_get_diag()

subroutine, public cp_fm_types::cp_fm_get_diag	(	type(cp_fm_type), intent(in)	matrix,
		real(kind=dp), dimension(:), intent(out)	diag
	)

returns the diagonal elements of a fm

Parameters

matrix	...
diag	...

Definition at line 562 of file cp_fm_types.F.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ cp_fm_get_element()

subroutine, public cp_fm_types::cp_fm_get_element	(	type(cp_fm_type), intent(in)	matrix,
		integer, intent(in)	irow_global,
		integer, intent(in)	icol_global,
		real(kind=dp), intent(out)	alpha,
		logical, intent(out), optional	local
	)

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

Parameters

matrix	the matrix to read
irow_global	the row
icol_global	the col
alpha	the value of matrix(irow_global, icol_global)
local	true if the element is on this cpu, false otherwise

Note

modified semantics. now this function always returns the value previously the value was zero on cpus that didn't own the relevant part of the matrix (Joost VandeVondele, May 2003)
usage of the function should be avoided, as it is likely to rather slow using row_indices/col_indices/local_data + some smart scheme normally yields a real parallel code

Definition at line 635 of file cp_fm_types.F.

Here is the caller graph for this function:

◆ cp_fm_set_element()

subroutine, public cp_fm_types::cp_fm_set_element	(	type(cp_fm_type), intent(in)	matrix,
		integer, intent(in)	irow_global,
		integer, intent(in)	icol_global,
		real(kind=dp), intent(in)	alpha
	)

sets an element of a matrix

Parameters

matrix	...
irow_global	...
icol_global	...
alpha	...

Note: we expect all cpus to have the same arguments in the call to this function (otherwise one should use local_data tricks)

Definition at line 692 of file cp_fm_types.F.

Here is the caller graph for this function:

◆ cp_fm_set_submatrix()

subroutine, public cp_fm_types::cp_fm_set_submatrix	(	type(cp_fm_type), intent(in)	fm,
		real(kind=dp), dimension(:, :), intent(in)	new_values,
		integer, intent(in), optional	start_row,
		integer, intent(in), optional	start_col,
		integer, intent(in), optional	n_rows,
		integer, intent(in), optional	n_cols,
		real(kind=dp), intent(in), optional	alpha,
		real(kind=dp), intent(in), optional	beta,
		logical, intent(in), optional	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)

Parameters

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

History: 07.2002 created borrowing from Joost's blacs_replicated_copy [fawzi]

Author: Fawzi Mohamed

Note: optimized for full column updates and alpha=1.0, beta=0.0 the new_values need to be valid on all cpus

Definition at line 759 of file cp_fm_types.F.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ cp_fm_get_submatrix()

subroutine, public cp_fm_types::cp_fm_get_submatrix	(	type(cp_fm_type), intent(in)	fm,
		real(kind=dp), dimension(:, :), intent(out)	target_m,
		integer, intent(in), optional	start_row,
		integer, intent(in), optional	start_col,
		integer, intent(in), optional	n_rows,
		integer, intent(in), optional	n_cols,
		logical, intent(in), optional	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

Parameters

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

History: 07.2002 created borrowing from Joost's blacs_replicated_copy [fawzi]

Author: Fawzi Mohamed

Note: optimized for full column updates. Zeros out a little too much of target_m the target_m is replicated and valid on all cpus

Definition at line 892 of file cp_fm_types.F.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ cp_fm_get_info()

subroutine, public cp_fm_types::cp_fm_get_info	(	type(cp_fm_type), intent(in)	matrix,
		character(len=*), 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, dimension(:), optional, pointer	row_indices,
		integer, dimension(:), optional, pointer	col_indices,
		real(kind=dp), dimension(:, :), optional, pointer, contiguous	local_data,
		type(cp_blacs_env_type), optional, pointer	context,
		integer, dimension(:), optional, pointer	nrow_locals,
		integer, dimension(:), optional, pointer	ncol_locals,
		type(cp_fm_struct_type), optional, pointer	matrix_struct,
		type(mp_para_env_type), optional, pointer	para_env
	)

returns all kind of information about the full matrix

Parameters

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	...

Note

◆ cp_fm_write_info()

subroutine, public cp_fm_types::cp_fm_write_info	(	type(cp_fm_type), intent(in)	matrix,
		integer, intent(in)	io_unit
	)

Write nicely formatted info about the FM to the given I/O unit (including the underlying FM struct)

Parameters

matrix	a cp_fm_type instance
io_unit	the I/O unit to use for writing

Definition at line 1040 of file cp_fm_types.F.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ cp_fm_maxabsval()

subroutine, public cp_fm_types::cp_fm_maxabsval	(	type(cp_fm_type), intent(in)	matrix,
		real(kind=dp), intent(out)	a_max,
		integer, intent(out), optional	ir_max,
		integer, intent(out), optional	ic_max
	)

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

Parameters

matrix	...
a_max	...
ir_max	...
ic_max	...

Definition at line 1056 of file cp_fm_types.F.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ cp_fm_maxabsrownorm()

subroutine, public cp_fm_types::cp_fm_maxabsrownorm	(	type(cp_fm_type), intent(in)	matrix,
		real(kind=dp), intent(out)	a_max
	)

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

Parameters

matrix	...
a_max	...

Note: for a real symmetric matrix it holds that || A ||_2 = |lambda_max| < || A ||_infinity Hence this can be used to estimate an upper bound for the eigenvalues of a matrix http://mathworld.wolfram.com/MatrixNorm.html (but the bound is not so tight in the general case)

Definition at line 1158 of file cp_fm_types.F.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ cp_fm_vectorsnorm()

subroutine, public cp_fm_types::cp_fm_vectorsnorm	(	type(cp_fm_type), intent(in)	matrix,
		real(kind=dp), dimension(:), intent(out)	norm_array
	)

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

Parameters

matrix	...
norm_array	...

Definition at line 1199 of file cp_fm_types.F.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ cp_fm_vectorssum()

subroutine, public cp_fm_types::cp_fm_vectorssum	(	type(cp_fm_type), intent(in)	matrix,
		real(kind=dp), dimension(:), intent(out)	sum_array,
		character(len=1), intent(in), optional	dir
	)

summing up all the elements along the matrix's i-th index \( \mathrm{sum}_{j} = \sum_{i} A_{ij} \) or \( \mathrm{sum}_{i} = \sum_{j} A_{ij} \)

Parameters

matrix	an input matrix A
sum_array	sums of elements in each column/row
dir	...

Note: forked from cp_fm_vectorsnorm() to be used with the maximum overlap method added row variation

Definition at line 1244 of file cp_fm_types.F.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ cp_fm_to_fm_triangular()

subroutine, public cp_fm_types::cp_fm_to_fm_triangular	(	type(cp_fm_type), intent(in)	msource,
		type(cp_fm_type), intent(in)	mtarget,
		character(len=1), intent(in), optional	uplo
	)

copy just a triangular matrix

Parameters

msource	...
mtarget	...
uplo	...

Definition at line 1422 of file cp_fm_types.F.

Here is the caller graph for this function:

◆ cp_fm_to_fm_submat()

subroutine, public cp_fm_types::cp_fm_to_fm_submat	(	type(cp_fm_type), intent(in)	msource,
		type(cp_fm_type), intent(in)	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
	)

copy just a part ot the matrix

Parameters

msource	...
mtarget	...
nrow	...
ncol	...
s_firstrow	...
s_firstcol	...
t_firstrow	...
t_firstcol	...

Definition at line 1471 of file cp_fm_types.F.

Here is the caller graph for this function:

◆ cp_fm_copy_general()

subroutine, public cp_fm_types::cp_fm_copy_general	(	type(cp_fm_type), intent(in)	source,
		type(cp_fm_type), intent(in)	destination,
		type(mp_para_env_type), intent(in)	para_env
	)

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

Parameters

source	input fm matrix
destination	output fm matrix
para_env	parallel environment corresponding to the BLACS env that covers all parts of the input and output matrices

History: 31-Jan-2017 : Re-implemented using non-blocking MPI [IainB, MarkT]

Definition at line 1536 of file cp_fm_types.F.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ cp_fm_start_copy_general()

subroutine, public cp_fm_types::cp_fm_start_copy_general	(	type(cp_fm_type), intent(in)	source,
		type(cp_fm_type), intent(in)	destination,
		type(mp_para_env_type), intent(in)	para_env,
		type(copy_info_type), intent(out)	info
	)

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

Parameters

source	input fm matrix
destination	output fm matrix
para_env	parallel environment corresponding to the BLACS env that covers all parts of the input and output matrices
info	all of the data that will be needed to complete the copy operation

Definition at line 1566 of file cp_fm_types.F.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ cp_fm_finish_copy_general()

subroutine, public cp_fm_types::cp_fm_finish_copy_general	(	type(cp_fm_type), intent(in)	destination,
		type(copy_info_type), intent(inout)	info
	)

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

Parameters

destination	output fm matrix
info	all of the data that will be needed to complete the copy operation

Definition at line 1880 of file cp_fm_types.F.

Here is the caller graph for this function:

◆ cp_fm_cleanup_copy_general()

subroutine, public cp_fm_types::cp_fm_cleanup_copy_general ( type(copy_info_type), intent(inout) info )

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

Parameters

info	all of the data that will be needed to complete the copy operation

Definition at line 1944 of file cp_fm_types.F.

Here is the caller graph for this function:

◆ cp_fm_to_fm_submat_general()

subroutine, public cp_fm_types::cp_fm_to_fm_submat_general	(	type(cp_fm_type), intent(in)	source,
		type(cp_fm_type), intent(in)	destination,
		integer, intent(in)	nrows,
		integer, intent(in)	ncols,
		integer, intent(in)	s_firstrow,
		integer, intent(in)	s_firstcol,
		integer, intent(in)	d_firstrow,
		integer, intent(in)	d_firstcol,
		class(cp_blacs_type), intent(in)	global_context
	)

General copy of a submatrix of fm matrix to a submatrix of another fm matrix. The two matrices can have different contexts.

Summary of distribution routines for dense matrices The following will copy A(iA:iA+M-1,jA:jA+N-1) to B(iB:iB+M-1,jB:jB+N-1):

call pdgemr2d(M,N,Aloc,iA,jA,descA,Bloc,iB,jB,descB,context)

A process that is not a part of the context of A should set descA(2) to -1, and similarly for B.

Parameters

source	input fm matrix
destination	output fm matrix
nrows	number of rows of sub matrix to be copied
ncols	number of cols of sub matrix to be copied
s_firstrow	starting global row index of sub matrix in source
s_firstcol	starting global col index of sub matrix in source
d_firstrow	starting global row index of sub matrix in destination
d_firstcol	starting global col index of sub matrix in destination
global_context	process grid that covers all parts of either A or B.

Definition at line 1993 of file cp_fm_types.F.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ cp_fm_add_to_element()

subroutine, public cp_fm_types::cp_fm_add_to_element	(	type(cp_fm_type), intent(in)	matrix,
		integer, intent(in)	irow_global,
		integer, intent(in)	icol_global,
		real(kind=dp), intent(in)	alpha
	)

...

Parameters

matrix	...
irow_global	...
icol_global	...
alpha	...

Definition at line 2091 of file cp_fm_types.F.

Here is the caller graph for this function:

◆ cp_fm_write_unformatted()

subroutine, public cp_fm_types::cp_fm_write_unformatted	(	type(cp_fm_type), intent(in)	fm,
		integer, intent(in)	unit
	)

...

Parameters

fm	...
unit	...

Definition at line 2145 of file cp_fm_types.F.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ cp_fm_write_formatted()

subroutine, public cp_fm_types::cp_fm_write_formatted	(	type(cp_fm_type), intent(in)	fm,
		integer, intent(in)	unit,
		character(len=*), intent(in), optional	header,
		character(len=*), intent(in), optional	value_format
	)

Write out a full matrix in plain text.

Parameters

fm	the matrix to be outputted
unit	the unit number for I/O
header	optional header
value_format	...

Definition at line 2249 of file cp_fm_types.F.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ cp_fm_read_unformatted()

subroutine, public cp_fm_types::cp_fm_read_unformatted	(	type(cp_fm_type), intent(inout)	fm,
		integer, intent(in)	unit
	)

...

Parameters

fm	...
unit	...

Definition at line 2376 of file cp_fm_types.F.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ cp_fm_setup()

subroutine, public cp_fm_types::cp_fm_setup ( integer, intent(in) mm_type )

...

Parameters

mm_type ...

Definition at line 2432 of file cp_fm_types.F.

Here is the caller graph for this function:

◆ cp_fm_get_mm_type()

integer function, public cp_fm_types::cp_fm_get_mm_type

...

Returns: ...

Definition at line 2442 of file cp_fm_types.F.

Here is the caller graph for this function:

◆ cp_fm_pilaenv()

integer function, public cp_fm_types::cp_fm_pilaenv	(	integer	ictxt,
		character(len=1)	prec
	)

...

Parameters

ictxt	...
prec	...

Returns: ...

Definition at line 2454 of file cp_fm_types.F.

Here is the caller graph for this function:

Data Types

Functions/Subroutines

Detailed Description

Function/Subroutine Documentation

◆ cp_fm_create()

◆ cp_fm_init_random()

◆ cp_fm_set_all()

◆ cp_fm_get_diag()

◆ cp_fm_get_element()

◆ cp_fm_set_element()

◆ cp_fm_set_submatrix()

◆ cp_fm_get_submatrix()

◆ cp_fm_get_info()

◆ cp_fm_write_info()

◆ cp_fm_maxabsval()

◆ cp_fm_maxabsrownorm()

◆ cp_fm_vectorsnorm()

◆ cp_fm_vectorssum()

◆ cp_fm_to_fm_triangular()

◆ cp_fm_to_fm_submat()

◆ cp_fm_copy_general()

◆ cp_fm_start_copy_general()

◆ cp_fm_finish_copy_general()

◆ cp_fm_cleanup_copy_general()

◆ cp_fm_to_fm_submat_general()

◆ cp_fm_add_to_element()

◆ cp_fm_write_unformatted()

◆ cp_fm_write_formatted()

◆ cp_fm_read_unformatted()

◆ cp_fm_setup()

◆ cp_fm_get_mm_type()

◆ cp_fm_pilaenv()