A suite of routines to perform the eigen-decomposition of symmetric 2*2 matrices and to deliver basic analytic functions, and the derivatives of these functions, of such matrices. More...

Data Types
interface	chol2

interface	eigensym2

interface	expsym2

interface	expsym2d_e

interface	expsym2d_t

interface	id2222

interface	invsym2

interface	logsym2

interface	sqrtsym2

interface	sqrtsym2d_e

interface	sqrtsym2d_t

Public Member Functions
subroutine, public	chol2 (s, c, ff)
	Return the cholesky lower triangular factor, C, of the 2X2 symmetric matrix, S, or raise the failure flag, FF, if S is not positive-definite. More...

subroutine, public	eigensym2 (em, vv, oo)
	Get the orthogonal eigenvectors, vv, and diagonal matrix of eigenvalues, oo, of the symmetric 2*2 matrix, em. More...

subroutine, public	expsym2 (em, expem)
	Get the exp of a symmetric 2*2 matrix. More...

subroutine, public	id2222 (em)
	General routine for a symmetrized 4th-rank tensor that acts as an effective identity for operations on symmetric matrices. More...

subroutine, public	invsym2 (em, z)
	Get the inverse of a 2*2 matrix (need not be symmetric in this case). More...

subroutine, public	logsym2 (em, logem)
	Get the log of a symmetric positive-definite 2*2 matrix. More...

subroutine, public	sqrtsym2 (em, z)
	Get the sqrt of a symmetric positive-definite 2*2 matrix. More...

Private Member Functions
subroutine	eigensym2d (em, vv, oo, vvd, ood, ff)
	For a symmetric 2*2 matrix, em, return the normalized eigenvectors, vv, and the diagonal matrix of eigenvalues, oo. More...

subroutine	expsym2d (x, z, zd)
	Get the exp of a symmetric 2*2 matrix, and its symmetric derivative. More...

subroutine	expsym2d_e (x, z, zd)
	Get the exponential and its symmetric derivative for a symmetric 2*2 matrix using eigen-decomposition. More...

subroutine	expsym2d_t (x, z, zd)
	Use the Taylor-series method (eigenvalues both fairly close to zero). More...

subroutine	invsym2d (em, z, zd)
	Get the inverse, z,of a 2*2 symmetric matrix, em, and its derivative, zd, with respect to symmetric variations of its components. More...

subroutine	logsym2d (x, z, zd)
	General routine to evaluate the logarithm, z=log(x), and the symmetric derivative, zd = dz/dx, where x is a symmetric 2*2 positive-definite matrix. More...

subroutine	sqrtsym2d (x, z, zd)
	General routine to evaluate z=sqrt(x), and the symmetric derivative, zd = dz/dx, where x is a symmetric 2*2 positive-definite matrix. More...

subroutine	sqrtsym2d_e (x, z, zd)
	Eigen-method. More...

subroutine	sqrtsym2d_t (x, z, zd)
	Use the Taylor-series method (eigenvalues both fairly close to unity). More...

Private Attributes
real(dp), dimension(2, 2, 2, 2)	id
	ID. More...

Detailed Description

A suite of routines to perform the eigen-decomposition of symmetric 2*2 matrices and to deliver basic analytic functions, and the derivatives of these functions, of such matrices.

In addition, we include a simple cholesky routine.

Author: R. J. Purser

Definition at line 11 of file psym2.f90.

Member Function/Subroutine Documentation

subroutine, public psym2::chol2	(	real(dp), dimension(2,2), intent(in)	s,
		real(dp), dimension(2,2), intent(out)	c,
		logical, intent(out)	ff
	)

Return the cholesky lower triangular factor, C, of the 2X2 symmetric matrix, S, or raise the failure flag, FF, if S is not positive-definite.

Parameters

[in]	s	2X2 symmetric matrix
[out]	c	cholesky lower triangular factor
[out]	ff	raise the failure flag

Author: R. J. Purser

Definition at line 454 of file psym2.f90.

subroutine, public psym2::eigensym2	(	real(dp), dimension(2,2), intent(in)	em,
		real(dp), dimension(2,2), intent(out)	vv,
		real(dp), dimension(2,2), intent(out)	oo
	)

Get the orthogonal eigenvectors, vv, and diagonal matrix of eigenvalues, oo, of the symmetric 2*2 matrix, em.

Parameters

[in]	em	symmetric 2*2 matrix
[out]	vv	orthogonal eigenvectors
[out]	oo	diagonal matrix of eigenvalues

Author: R. J. Purser

Definition at line 42 of file psym2.f90.

subroutine psym2::eigensym2d	(	real(dp), dimension(2,2), intent(in)	em,
		real(dp), dimension(2,2), intent(out)	vv,
		real(dp), dimension(2,2), intent(out)	oo,
		real(dp), dimension(2,2,2,2), intent(out)	vvd,
		real(dp), dimension(2,2,2,2), intent(out)	ood,
		logical, intent(out)	ff
	)

private

For a symmetric 2*2 matrix, em, return the normalized eigenvectors, vv, and the diagonal matrix of eigenvalues, oo.

If the two eigenvalues are equal, proceed no further and raise the logical failure flag, ff, to .true.; otherwise, return with vvd=d(vv)/d(em) and ood=d(oo)/d(em) and ff=.false., and maintain the symmetries between the last two of the indices of these derivatives.

Parameters

[in]	em	symmetric 2*2 matrix
[out]	vv	normalized eigenvectors
[out]	oo	diagonal matrix of eigenvalues
[out]	vvd	vvd=d(vv)/d(em)
[out]	ood	ood=d(oo)/d(em)
[out]	ff	logical failure flag

Author: R. J. Purser

Definition at line 75 of file psym2.f90.

subroutine, public psym2::expsym2	(	real(dp), dimension(2,2), intent(in)	em,
		real(dp), dimension(2,2), intent(out)	expem
	)

Get the exp of a symmetric 2*2 matrix.

Parameters

[in]	em	symmetric 2*2 matrix
[out]	expem	exp of a symmetric 2*2 matrix

Author: R. J. Purser

Definition at line 276 of file psym2.f90.

subroutine psym2::expsym2d	(	real(dp), dimension(2,2), intent(in)	x,
		real(dp), dimension(2,2), intent(out)	z,
		real(dp), dimension(2,2,2,2), intent(out)	zd
	)

private

Get the exp of a symmetric 2*2 matrix, and its symmetric derivative.

Parameters

[in]	x	symmetric 2*2 positive-definite matrix
[out]	z	exp of symmetric 2*2 matrix x
[out]	zd	symmetric derivative wrt x of exp of x

Author: R. J. Purser

Definition at line 293 of file psym2.f90.

subroutine psym2::expsym2d_e	(	real(dp), dimension(2,2), intent(in)	x,
		real(dp), dimension(2,2), intent(out)	z,
		real(dp), dimension(2,2,2,2), intent(out)	zd
	)

private

Get the exponential and its symmetric derivative for a symmetric 2*2 matrix using eigen-decomposition.

Parameters

[in]	x	symmetric 2*2 positive-definite matrix
[out]	z	exp of symmetrix matrix x
[out]	zd	symmetric derivative of z wrt x

Author: R. J. Purser

Definition at line 316 of file psym2.f90.

subroutine psym2::expsym2d_t	(	real(dp), dimension(2,2), intent(in)	x,
		real(dp), dimension(2,2), intent(out)	z,
		real(dp), dimension(2,2,2,2), intent(out)	zd
	)

private

Use the Taylor-series method (eigenvalues both fairly close to zero).

For a 2*2 symmetric matrix x, try to get both the z=exp(x) and dz/dx using the Taylor series expansion method.

Parameters

[in]	x	symmetric 2*2 positive-definite matrix
[out]	z	Taylor series expansion method exp(x)
[out]	zd	symmetric derivative

Author: R. J. Purser

Definition at line 346 of file psym2.f90.

subroutine, public psym2::id2222 ( real(dp), dimension(2,2,2,2), intent(out) em )

General routine for a symmetrized 4th-rank tensor that acts as an effective identity for operations on symmetric matrices.

Parameters

[out] em symmetrized effective identity in space of symmetrix matrices.

Author: R. J. Purser

Definition at line 438 of file psym2.f90.

subroutine, public psym2::invsym2	(	real(dp), dimension(2,2), intent(in)	em,
		real(dp), dimension(2,2), intent(out)	z
	)

Get the inverse of a 2*2 matrix (need not be symmetric in this case).

Parameters

[in]	em	2*2 matrix
[out]	z	inverse of a 2*2 matrix

Author: R. J. Purser

Definition at line 111 of file psym2.f90.

subroutine psym2::invsym2d	(	real(dp), dimension(2,2), intent(in)	em,
		real(dp), dimension(2,2), intent(out)	z,
		real(dp), dimension(2,2,2,2), intent(out)	zd
	)

private

Get the inverse, z,of a 2*2 symmetric matrix, em, and its derivative, zd, with respect to symmetric variations of its components.

I.e., for a symmetric infinitesimal change, delta_em, in em, the resulting infinitesimal change in z would be:

delta_z(i,j) = matmul(zd(i,j,:,:),delta_em)

Parameters

[in]	em	2*2 symmetric matrix
[out]	z	inverse of a 2*2 symmetric matrix
[out]	zd	derivative of the 2*2 symmetric matrix

Author: R. J. Purser

Definition at line 131 of file psym2.f90.

subroutine, public psym2::logsym2	(	real(dp), dimension(2,2), intent(in)	em,
		real(dp), dimension(2,2), intent(out)	logem
	)

Get the log of a symmetric positive-definite 2*2 matrix.

Parameters

[in]	em	symmetric 2*2 matrix
[out]	logem	log of a symmetric positive-definite 2*2 matrix

Author: R. J. Purser

Definition at line 386 of file psym2.f90.

subroutine psym2::logsym2d	(	real(dp), dimension(2,2), intent(in)	x,
		real(dp), dimension(2,2), intent(out)	z,
		real(dp), dimension(2,2,2,2), intent(out)	zd
	)

private

General routine to evaluate the logarithm, z=log(x), and the symmetric derivative, zd = dz/dx, where x is a symmetric 2*2 positive-definite matrix.

Parameters

[in]	zd	the symmetric derivative
[out]	x	a symmetric 2*2 positive-definite matrix
[out]	z	evaluate the logarithm log(x)

Author: R. J. Purser

Definition at line 408 of file psym2.f90.

subroutine, public psym2::sqrtsym2	(	real(dp), dimension(2,2), intent(in)	em,
		real(dp), dimension(2,2), intent(out)	z
	)

Get the sqrt of a symmetric positive-definite 2*2 matrix.

Parameters

[in]	em	2*2 symmetric matrix
[out]	z	sqrt of a symmetric positive-definite 2*2 matrix

Author: R. J. Purser

Definition at line 149 of file psym2.f90.

subroutine psym2::sqrtsym2d	(	real(dp), dimension(2,2), intent(in)	x,
		real(dp), dimension(2,2), intent(out)	z,
		real(dp), dimension(2,2,2,2), intent(out)	zd
	)

private

General routine to evaluate z=sqrt(x), and the symmetric derivative, zd = dz/dx, where x is a symmetric 2*2 positive-definite matrix.

If the eigenvalues are very close together, extract their geometric mean for "preconditioning" a scaled version, px, of x, whose sqrt, and hence its derivative, can be easily obtained by the series expansion method. Otherwise, use the eigen-method (which entails dividing by the difference in the eignevalues to get zd, and which therefore fails when the eigenvalues become too similar).

Parameters

[in]	x	symmetric 2*2 positive-definite matrix
[out]	z	sqrt(x) result
[out]	zd	symmetric derivative

Author: R. J. Purser

Definition at line 176 of file psym2.f90.

subroutine psym2::sqrtsym2d_e	(	real(dp), dimension(2,2), intent(in)	x,
		real(dp), dimension(2,2), intent(out)	z,
		real(dp), dimension(2,2,2,2), intent(out)	zd
	)

private

Eigen-method.

Parameters

[in]	x	symmetric 2*2 positive-definite matrix
[out]	z	sqrt(x) result
[out]	zd	symmetric derivative

Author: R. J. Purser

Definition at line 202 of file psym2.f90.

subroutine psym2::sqrtsym2d_t	(	real(dp), dimension(2,2), intent(in)	x,
		real(dp), dimension(2,2), intent(out)	z,
		real(dp), dimension(2,2,2,2), intent(out)	zd
	)

private

Use the Taylor-series method (eigenvalues both fairly close to unity).

For a 2*2 positive definite symmetric matrix x, try to get both the z=sqrt(x) and dz/dx using the binomial-expansion method applied to the intermediate matrix,

r = (x-1). ie z=sqrt(x) = (1+r)^{1/2} = I + (1/2)*r -(1/8)*r^2 ...
  + [(-)^n *(2n)!/{(n+1)! * n! *2^{2*n-1}} ]*r^{n+1}

Parameters

[in]	x	symmetric 2*2 positive-definite matrix
[out]	z	sqrt(x) result
[out]	zd	symmetric derivative

Author: R. J. Purser

Definition at line 235 of file psym2.f90.

Field Documentation

real(dp), dimension(2,2,2,2) psym2::id

private

ID.

Definition at line 18 of file psym2.f90.

The documentation for this module was generated from the following file:

/gpfs/dell2/emc/modeling/noscrub/George.Gayno/ufs_utils.git/UFS_UTILS.upstream/sorc/grid_tools.fd/regional_esg_grid.fd/psym2.f90

Data Types

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Function/Subroutine Documentation

Field Documentation