MODULE Utilities

Module Utilities Utilities exports subroutines and functions for simple and general computations.

Some of these routines can be used in place of intrinsic functions in the STATPACK library, like the dot_product2(), transpose2() and matmul2() functions described below, if the cpp macros _DOT_PRODUCT, _TRANSPOSE and _MATMUL are activated at compilation of the STATPACK library. See the section Preprocessor cpp macros for more details.

Some of these routines are adapted from public domain routines in Numerical Recipes. Note, finally, that many of these routines are low-level routines, which do not include checking of the correctness of the size/shape of their array arguments for enhanced speed at execution. This means that the user must exercise care when using these low-level subroutines and functions.

In order to use one of these routines, you must include an appropriate use Utilities or use Statpack statement in your Fortran program, like:

use Utilities, only: transpose2

or :

use Statpack, only: transpose2

In order to replace the calls to the intrinsic functions dot_product(), transpose() or matmul() by the corresponding STATPACK functions dot_product2(), transpose2() and matmul2() in your Fortran program, include in your program a statement like:

use Utilities, only: transpose=>transpose2

or :

use Statpack, only: transpose=>transpose2

Here is the list of the public routines exported by module Utilities:

transpose2()

Synopsis:

mat_t(:m,:n) = transpose2( mat(:n,:m) )  ! mat is a  real    matrix of kind stnd
mat_t(:m,:n) = transpose2( mat(:n,:m) )  ! mat is a  complex matrix of kind stnd
mat_t(:m,:n) = transpose2( mat(:n,:m) )  ! mat is an integer matrix of kind i4b
mat_t(:m,:n) = transpose2( mat(:n,:m) )  ! mat is a  logical matrix of kind lgl

Examples:

ex1_transpose2.F90

dot_product2()

Synopsis:

xy = dot_product2( vecx(:n) , vecy(:n) )  ! vecx and vecy are real    vectors of kind stnd
xy = dot_product2( vecx(:n) , vecy(:n) )  ! vecx and vecy are complex vectors of kind stnd
xy = dot_product2( vecx(:n) , vecy(:n) )  ! vecx and vecy are integer vectors of kind i4b
xy = dot_product2( vecx(:n) , vecy(:n) )  ! vecx and vecy are logical vectors of kind lgl

mmproduct()

Synopsis:

array(:m)    = mmproduct( vec(:n)     , mat(:n,:m)  ) ! vec and mat   are real    arrays of kind stnd
array(:n)    = mmproduct( mat(:n,:m)  , vec2(:m)    ) ! mat and vec2  are real    arrays of kind stnd
array(:n,:m) = mmproduct( mat1(:n,:p) , mat2(:p,:m) ) ! mat1 and mat2 are real    arrays of kind stnd
array(:m)    = mmproduct( vec(:n)     , mat(:n,:m)  ) ! vec and mat   are complex arrays of kind stnd
array(:n)    = mmproduct( mat(:n,:m)  , vec2(:m)    ) ! mat and vec2  are complex arrays of kind stnd
array(:n,:m) = mmproduct( mat1(:n,:p) , mat2(:p,:m) ) ! mat1 and mat2 are complex arrays of kind stnd

matmul2()

Synopsis:

array(:m)    = matmul2( vec(:n)     , mat(:n,:m)  ) ! vec and mat   are real    arrays of kind stnd
array(:n)    = matmul2( mat(:n,:m)  , vec2(:m)    ) ! mat and vec2  are real    arrays of kind stnd
array(:n,:m) = matmul2( mat1(:n,:p) , mat2(:p,:m) ) ! mat1 and mat2 are real    arrays of kind stnd
array(:m)    = matmul2( vec(:n)     , mat(:n,:m)  ) ! vec and mat   are complex arrays of kind stnd
array(:n)    = matmul2( mat(:n,:m)  , vec2(:m)    ) ! mat and vec2  are complex arrays of kind stnd
array(:n,:m) = matmul2( mat1(:n,:p) , mat2(:p,:m) ) ! mat1 and mat2 are complex arrays of kind stnd
array(:m)    = matmul2( vec(:n)     , mat(:n,:m)  ) ! vec and mat   are real    arrays of kind i4b
array(:n)    = matmul2( mat(:n,:m)  , vec2(:m)    ) ! mat and vec2  are real    arrays of kind i4b
array(:n,:m) = matmul2( mat1(:n,:p) , mat2(:p,:m) ) ! mat1 and mat2 are real    arrays of kind i4b
array(:m)    = matmul2( vec(:n)     , mat(:n,:m)  ) ! vec and mat   are logical arrays of kind lgl
array(:n)    = matmul2( mat(:n,:m)  , vec2(:m)    ) ! mat and vec2  are logical arrays of kind lgl
array(:n,:m) = matmul2( mat1(:n,:p) , mat2(:p,:m) ) ! mat1 and mat2 are logical arrays of kind lgl

Examples:

ex1_matmul2.F90

array_copy()

Synopsis:

call array_copy( src(:) , dest(:) , n_copied, n_not_copied ) ! src and dest are integer vectors of kind i4b
call array_copy( src(:) , dest(:) , n_copied, n_not_copied ) ! src and dest are real    vectors of kind stnd
call array_copy( src(:) , dest(:) , n_copied, n_not_copied ) ! src and dest are complex vectors of kind stnd

swap()

Synopsis:

call swap( a        , b                      ) ! a and b are integers of kind i4b
call swap( a        , b                      ) ! a and b are reals    of kind stnd
call swap( a        , b                      ) ! a and b are complex  of kind stnd
call swap( a(:n)    , b(:n)                  ) ! a and b are integer vectors of kind i4b
call swap( a(:n)    , b(:n)                  ) ! a and b are real vectors    of kind stnd
call swap( a(:n)    , b(:n)                  ) ! a and b are complex vectors of kind stnd
call swap( a(:n,:m) , b(:n,:m)               ) ! a and b are integer matrices of kind i4b
call swap( a(:n,:m) , b(:n,:m)               ) ! a and b are real matrices    of kind stnd
call swap( a(:n,:m) , b(:n,:m)               ) ! a and b are complex matrices of kind stnd
call swap( a        , b        , mask        ) ! a and b are integers of kind i4b
call swap( a        , b        , mask        ) ! a and b are reals    of kind stnd
call swap( a        , b        , mask        ) ! a and b are complex  of kind stnd
call swap( a(:n)    , b(:n)    , mask(:n)    ) ! a and b are integer vectors of kind i4b
call swap( a(:n)    , b(:n)    , mask(:n)    ) ! a and b are real vectors    of kind stnd
call swap( a(:n)    , b(:n)    , mask(:n)    ) ! a and b are complex vectors of kind stnd
call swap( a(:n,:m) , b(:n,:m) , mask(:n,:m) ) ! a and b are integer matrices of kind i4b
call swap( a(:n,:m) , b(:n,:m) , mask(:n,:m) ) ! a and b are real matrices    of kind stnd
call swap( a(:n,:m) , b(:n,:m) , mask(:n,:m) ) ! a and b are complex matrices of kind stnd

mvalloc(F2003 only)

Synopsis:

call mvalloc( p(:)   , n     , ialloc )  ! p is an allocated array to an integer vector of kind i4b
call mvalloc( p(:)   , n     , ialloc )  ! p is an allocated array to a real vector of kind stnd
call mvalloc( p(:)   , n     , ialloc )  ! p is an allocated array to a complex vector of kind stnd
call mvalloc( p(:)   , n     , ialloc )  ! p is an allocated array to a character vector
call mvalloc( p(:,:) , n , m , ialloc )  ! p is an allocated array to an integer matrix of kind i4b
call mvalloc( p(:,:) , n , m , ialloc )  ! p is an allocated array to a real matrix of kind stnd
call mvalloc( p(:,:) , n , m , ialloc )  ! p is an allocated array to a complex matrix of kind stnd

ifirstloc()

Synopsis:

index = ifirstloc( mask(:) )

imaxloc()

Synopsis:

index = imaxloc( arr(:n)            ) ! arr is an integer array of kind i4b
index = imaxloc( arr(:n) , mask(:n) ) ! arr is an integer array of kind i4b
index = imaxloc( arr(:n)            ) ! arr is a   real array   of kind stnd
index = imaxloc( arr(:n) , mask(:n) ) ! arr is a   real array   of kind stnd

iminloc()

Synopsis:

index = iminloc( arr(:n)            ) ! arr is an integer array of kind i4b
index = iminloc( arr(:n) , mask(:n) ) ! arr is an integer array of kind i4b
index = iminloc( arr(:n)            ) ! arr is a   real array   of kind stnd
index = iminloc( arr(:n) , mask(:n) ) ! arr is a   real array   of kind stnd

assert()

Synopsis:

call assert( n1 ,                string )
call assert( n1 , n2 ,           string )
call assert( n1 , n2 , n3 ,      string )
call assert( n1 , n2 , n3 , n4 , string )
call assert( n(:) ,              string )

assert_eq()

Synopsis:

n = assert_eq( n1 , n2 ,           string )
n = assert_eq( n1 , n2 , n3 ,      string )
n = assert_eq( n1 , n2 , n3 , n4 , string )
n = assert_eq( nn(:) ,             string )

merror()

Synopsis:

call merror( string , ierror=ierror )

arth()

Synopsis:

vec(:n)    = arth( first     , increment     , n ) ! first and increment are integers of kind i4b
vec(:n)    = arth( first     , increment     , n ) ! first and increment are reals    of kind stnd
vec(:n)    = arth( first     , increment     , n ) ! first and increment are complex  of kind stnd
vec(:m,:n) = arth( first(:m) , increment(:m) , n ) ! first and increment are integer vectors of kind i4b
vec(:m,:n) = arth( first(:m) , increment(:m) , n ) ! first and increment are real vectors    of kind stnd
vec(:m,:n) = arth( first(:m) , increment(:m) , n ) ! first and increment are complex vectors of kind stnd

geop()

Synopsis:

vec(:n)    = geop( first     , factor     , n ) ! first and factor are integers of kind i4b
vec(:n)    = geop( first     , factor     , n ) ! first and factor are reals    of kind stnd
vec(:n)    = geop( first     , factor     , n ) ! first and factor are complex  of kind stnd
vec(:m,:n) = geop( first(:m) , factor(:m) , n ) ! first and factor are integer vectors of kind i4b
vec(:m,:n) = geop( first(:m) , factor(:m) , n ) ! first and factor are real vectors    of kind stnd
vec(:m,:n) = geop( first(:m) , factor(:m) , n ) ! first and factor are complex vectors of kind stnd

cumsum()

Synopsis:

vec(:n) = cumsum( arr(:n) , seed ) ! arr is an integer array of kind i4b
vec(:n) = cumsum( arr(:n) , seed ) ! arr is a  real    array of kind stnd
vec(:n) = cumsum( arr(:n) , seed ) ! arr is a  complex array of kind stnd

cumprod()

Synopsis:

vec(:n) = cumprod( arr(:n) , seed ) ! arr is an integer array of kind i4b
vec(:n) = cumprod( arr(:n) , seed ) ! arr is a  real    array of kind stnd
vec(:n) = cumprod( arr(:n) , seed ) ! arr is a  complex array of kind stnd

poly()

Synopsis:

y     = poly( x     , coeffs(:)            ) ! x is a real    scalar of kind stnd and coeffs is a real    array of kind stnd
y     = poly( x     , coeffs(:)            ) ! x is a complex scalar of kind stnd and coeffs is a real    array of kind stnd
y     = poly( x     , coeffs(:)            ) ! x is a complex scalar of kind stnd and coeffs is a complex array of kind stnd
y(:n) = poly( x(:n) , coeffs(:)            ) ! x and coeffs are real arrays of kind stnd
y(:n) = poly( x(:n) , coeffs(:) , mask(:n) ) ! x and coeffs are real arrays of kind stnd and mask is a logical array of kind lgl

poly_term()

Synopsis:

y(:n) = poly_term( coeffs(:n) , x ) ! x is a real    scalar of kind stnd and coeffs is a real    array of kind stnd
y(:n) = poly_term( coeffs(:n) , x ) ! x is a complex scalar of kind stnd and coeffs is a complex array of kind stnd

zroots_unity()

Synopsis:

x(:nn) = zroots_unity( n, nn )

update_rk1()

Synopsis:

call update_rk1( mat(:m,:n) , u(:m) , v(:n) ) ! all are integer arrays of kind i4b
call update_rk1( mat(:m,:n) , u(:m) , v(:n) ) ! all are real    arrays of kind stnd
call update_rk1( mat(:m,:n) , u(:m) , v(:n) ) ! all are complex arrays of kind stnd

update_rk2()

Synopsis:

call update_rk2( mat(:m,:n) , u(:m) , v(:n) , u2(:m) , v2(:n) ) ! all are integer arrays of kind i4b
call update_rk2( mat(:m,:n) , u(:m) , v(:n) , u2(:m) , v2(:n) ) ! all are real    arrays of kind stnd
call update_rk2( mat(:m,:n) , u(:m) , v(:n) , u2(:m) , v2(:n) ) ! all are complex arrays of kind stnd

outerprod()

Synopsis:

mat(:n,:m) =  outerprod( a(:n) , b(:m) ) ! a and b are integer arrays of kind i4b
mat(:n,:m) =  outerprod( a(:n) , b(:m) ) ! a and b are real    arrays of kind stnd
mat(:n,:m) =  outerprod( a(:n) , b(:m) ) ! a and b are complex arrays of kind stnd

outerdiv()

Synopsis:

mat(:n,:m) =  outerdiv( a(:n) , b(:m) ) ! a and b are real    arrays of kind stnd
mat(:n,:m) =  outerdiv( a(:n) , b(:m) ) ! a and b are complex arrays of kind stnd

outersum()

Synopsis:

mat(:n,:m) =  outersum( a(:n) , b(:m) ) ! a and b are integer arrays of kind i4b
mat(:n,:m) =  outersum( a(:n) , b(:m) ) ! a and b are real    arrays of kind stnd
mat(:n,:m) =  outersum( a(:n) , b(:m) ) ! a and b are complex arrays of kind stnd

outerdiff()

Synopsis:

mat(:n,:m) = outerdiff( a(:n) , b(:m) ) ! a and b are integer arrays of kind i4b
mat(:n,:m) = outerdiff( a(:n) , b(:m) ) ! a and b are real    arrays of kind stnd
mat(:n,:m) = outerdiff( a(:n) , b(:m) ) ! a and b are complex arrays of kind stnd

outerand()

Synopsis:

mat(:n,:m) = outerand( a(:n) , b(:m) ) ! a and b are logical arrays of kind lgl

outeror()

Synopsis:

mat(:n,:m) = outeror( a(:n) , b(:m) ) ! a and b are logical arrays of kind lgl

triangle()

Synopsis:

mat(:j,:k) = triangle( upper , j , k , extra=extra )

abse()

Synopsis:

l2norm     = abse( vec(:)   ) ! vec is real    array of kind stnd
l2norm     = abse( vec(:)   ) ! vec is complex array of kind stnd
fnorm      = abse( mat(:,:) ) ! mat is real    array of kind stnd
fnorm      = abse( mat(:,:) ) ! mat is complex array of kind stnd
l2norm(:)  = abse( mat(:,:) , dim ) ! mat is real    array of kind stnd
l2norm(:)  = abse( mat(:,:) , dim ) ! mat is complex array of kind stnd

lassq()

Synopsis:

call lassq( vec(:)   , scal, ssq ) ! vec is real    array of kind stnd
call lassq( vec(:)   , scal, ssq ) ! vec is complex array of kind stnd
call lassq( mat(:,:) , scal, ssq ) ! mat is real    array of kind stnd
call lassq( mat(:,:) , scal, ssq ) ! mat is complex array of kind stnd

norm()

Synopsis:

l2norm     = norm( vec(:)   ) ! vec is real    array of kind stnd
l2norm     = norm( vec(:)   ) ! vec is complex array of kind stnd
fnorm      = norm( mat(:,:) ) ! mat is real    array of kind stnd
fnorm      = norm( mat(:,:) ) ! mat is complex array of kind stnd
l2norm(:)  = norm( mat(:,:) , dim ) ! mat is real    array of kind stnd
l2norm(:)  = norm( mat(:,:) , dim ) ! mat is complex array of kind stnd

scatter_add()

Synopsis:

call scatter_add( dest(:) , source(:n) , dest_index(:n) ) ! dest and sources are integer arrays of kind i4b
call scatter_add( dest(:) , source(:n) , dest_index(:n) ) ! dest and sources are real    arrays of kind stnd
call scatter_add( dest(:) , source(:n) , dest_index(:n) ) ! dest and sources are complex arrays of kind stnd

scatter_max()

Synopsis:

call scatter_max( dest(:) , source(:n) , dest_index(:n) ) ! dest and sources are integer arrays of kind i4b
call scatter_max( dest(:) , source(:n) , dest_index(:n) ) ! dest and sources are real    arrays of kind stnd

diagadd()

Synopsis:

call diagadd( mat(:,:)   , diag            ) ! mat is a real    array of kind stnd
call diagadd( mat(:,:)   , diag            ) ! mat is a complex array of kind stnd
call diagadd( mat(:n,:m) , diag(:min(n,m)) ) ! diag and mat are real    arrays of kind stnd
call diagadd( mat(:n,:m) , diag(:min(n,m)) ) ! diag and mat are complex arrays of kind stnd

diagmult()

Synopsis:

call diagmult( mat(:,:)   , diag            ) ! mat is a real    array of kind stnd
call diagmult( mat(:,:)   , diag            ) ! mat is a complex array of kind stnd
call diagmult( mat(:n,:m) , diag(:min(n,m)) ) ! diag and mat are real    arrays of kind stnd
call diagmult( mat(:n,:m) , diag(:min(n,m)) ) ! diag and mat are complex arrays of kind stnd

get_diag()

Synopsis:

diag(:min(n,m)) = get_diag( mat(:n,:m) ) ! mat is a real    array of kind stnd
diag(:min(n,m)) = get_diag( mat(:n,:m) ) ! mat is a complex array of kind stnd

put_diag()

Synopsis:

call put_diag( diag             , mat(:,:)  ) ! mat is a real    array of kind stnd
call put_diag( diag             , mat(:,:)  ) ! mat is a complex array of kind stnd
call put_diag( diag(:min(n,m)) , mat(:n,:m) ) ! diagv and mat are real    arrays of kind stnd
call put_diag( diag(:min(n,m)) , mat(:n,:m) ) ! diagv and mat are complex arrays of kind stnd

unit_matrix()

Synopsis:

call unit_matrix( mat(:,:) ) ! mat is a real    array of kind stnd
call unit_matrix( mat(:,:) ) ! mat is a complex array of kind stnd

lascl()

Synopsis:

call lascl( x        , cfrom , cto )
call lascl( x(:)     , cfrom , cto )
call lascl( x(:,:)   , cfrom , cto )
call lascl( x(:,:)   , cfrom , cto , type        )
call lascl( x        , cfrom , cto , mask        )
call lascl( x(:n)    , cfrom , cto , mask(:n)    )
call lascl( x(:n,:m) , cfrom , cto , mask(:n,:m) )

norme()

Synopsis:

x = norme( vec(:n)    )
x = norme( mat(:n,:m) )

pythag()

Synopsis:

x = pythag( a , b )