psym2 Module Reference

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

Functions/Subroutines
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	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, public	expsym2 (em, expem)
	Get the exp of a symmetric 2*2 matrix. 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, 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	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, public	logsym2 (em, logem)
	Get the log of a symmetric positive-definite 2*2 matrix. 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, public	sqrtsym2 (em, z)
	Get the sqrt of a symmetric positive-definite 2*2 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...

Variables
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

Function/Subroutine Documentation

chol2()

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 455 of file psym2.f90.

References pietc::u0.

eigensym2()

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 43 of file psym2.f90.

References pietc::o2, pietc::u0, and pietc::u1.

eigensym2d()

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 76 of file psym2.f90.

References pietc::o2, pietc::u0, and pietc::u1.

expsym2()

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 277 of file psym2.f90.

expsym2d()

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 294 of file psym2.f90.

References pietc::o2.

expsym2d_e()

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 317 of file psym2.f90.

References pietc::u0.

expsym2d_t()

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 347 of file psym2.f90.

References id, and pietc::u1.

id2222()

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 439 of file psym2.f90.

References id.

invsym2()

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 112 of file psym2.f90.

invsym2d()

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 132 of file psym2.f90.

logsym2()

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 387 of file psym2.f90.

References pietc::u0.

logsym2d()

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 409 of file psym2.f90.

References pietc::o2, pietc::u0, and pietc::u1.

sqrtsym2()

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 150 of file psym2.f90.

sqrtsym2d()

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 177 of file psym2.f90.

References pietc::u1.

sqrtsym2d_e()

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 203 of file psym2.f90.

References pietc::o2, pietc::u0, and pietc::u1.

sqrtsym2d_t()

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 236 of file psym2.f90.

References id, pietc::o2, pietc::u0, and pietc::u1.

Variable Documentation

id

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

private

ID.

Definition at line 18 of file psym2.f90.

Referenced by expsym2d_t(), id2222(), and sqrtsym2d_t().