ParaMonte Fortran 2.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation.
pm_matrixPack Module Reference

This module contains abstract and concrete derived types that are required for compile-time resolution of procedures within the generic interfaces of the ParaMonte library for Linear Algebra operations.
Such procedures frequently need to work with different packaging of Symmetric/Hermitian/Band or other special types of their input matrix arguments.
More...

Data Types

interface  isMatPack
 Generate and return .true. if and only if a desired matrix with the specified input shape is of the specified input packing pack.
More...
 
type  lcpack_type
 This is a concrete derived type whose instances are exclusively used to signify Linear Contiguous Packing format of a subset of a matrix within an interface of a procedure of the ParaMonte library.
More...
 
type  ldpack_type
 This is a concrete derived type whose instances are exclusively used to signify Linear Sparse (or Standard) Packing format of a (triangular) subset of a matrix within an interface of a procedure of the ParaMonte library.
More...
 
type  lfpack_type
 This is a concrete derived type whose instances are exclusively used to signify Linear Full contiguous Packing format of a (triangular) subset of a matrix within an interface of a procedure of the ParaMonte library.
More...
 
type  package_type
 This is an abstract derived type for constructing concrete derived types to distinguish various procedure signatures that require different forms of matrix packing (triangular, Band, ...).
More...
 
type  rcpack_type
 This is a concrete derived type whose instances are exclusively used to signify Rectangular Full contiguous Packing format of a (triangular) subset of a matrix within an interface of a procedure of the ParaMonte library.
More...
 
type  rdpack_type
 This is a concrete derived type whose instances are exclusively used to signify Rectangular Sparse (or Standard) Packing format of a (triangular) subset of a matrix within an interface of a procedure of the ParaMonte library.
More...
 
type  rfpack_type
 This is a concrete derived type whose instances are exclusively used to signify Rectangular Full contiguous Packing format of a (triangular) subset of a matrix within an interface of a procedure of the ParaMonte library.
More...
 

Variables

character(*, SK), parameter MODULE_NAME = "@pm_matrixPack"
 
type(rdpack_type), parameter rdpack = rdpack_type()
 This is an object instance of class rdpack_type that is exclusively used to signify Rectangular Sparse (or Standard) Packing format of a given (triangular) subset of a matrix within an interface of a procedure of the ParaMonte library.
More...
 
type(lfpack_type), parameter lfpack = lfpack_type()
 This is an object instance of class lfpack_type that is exclusively used to signify Linear Full contiguous Packing format of a (triangular) subset of a matrix within an interface of a procedure of the ParaMonte library.
More...
 
type(rfpack_type), parameter rfpack = rfpack_type()
 This is an object instance of class rfpack_type that is exclusively used to signify Rectangular Full contiguous Packing format of a (triangular) subset of a matrix within an interface of a procedure of the ParaMonte library.
More...
 

Detailed Description

This module contains abstract and concrete derived types that are required for compile-time resolution of procedures within the generic interfaces of the ParaMonte library for Linear Algebra operations.
Such procedures frequently need to work with different packaging of Symmetric/Hermitian/Band or other special types of their input matrix arguments.

This module follows the conventions of the LAPACK Linear Algebra Fortran software for matrix package schemes.
LAPACK routines use the following matrix package schemes:

  1. Linear Full Packing (LFP) for Symmetric, Hermitian triangular matrices (lfpack)
    This vector packing format compactly stores matrix elements as a vector.
    This is useful when only one part of the matrix, the upper or lower triangle, is necessary to determine all matrix elements.
    This is the case when the matrix is Symmetric, Hermitian, or is of upper/lower triangular class.
    A lower-diagonal triangular or Symmetric/Hermitian matrix of the form,

    \begin{equation} L = \begin{bmatrix} \ell_{1,1} & & & & \\ \ell_{2,1} & \ell_{2,2} & & & \\ \ell_{3,1} & \ell_{3,2} & \ddots & & \\ \vdots & \vdots & \ddots & \ell_{n-1,n-1} & \\ \ell_{n,1} & \ell_{n,2} & \ldots & \ell_{n,n-1} & \ell_{n,n} \end{bmatrix} ~, \end{equation}

    translates to the packed (column-major) format,

    \begin{equation} L_{\mathrm{packed}} = [ \ell_{1,1}, \ell_{2,1}, \ell_{3,1}, \ldots, \ell_{n,1}, \ell_{2,2}, \ell_{3,2}, \ldots, \ell_{n,2}, \ldots, \ell_{n-1,n-1}, \ell_{n,n-1}, \ell_{n,n} ] ~. \end{equation}

    In general, the indices \((i, j), 1\leq j\leq i \leq n\) of a full lower-diagonal \(n\times n\) matrix translate to packed vector index,
    1. \(k(i, j) = i - 1 + (j - 1) * (2 * n - j) / 2\) for a column-major matrix layout (Fortran-style).
    2. \(k(i, j) = i - 1 + j * (j - 1) / 2\) for a row-major matrix layout (C-style).
    Similarly, an upper-diagonal triangular or Symmetric/Hermitian matrix of the form,

    \begin{equation} U = \begin{bmatrix} u_{1,1} & u_{1,2} & u_{1,3} & \ldots & u_{1,n} \\ & u_{2,2} & u_{2,3} & \ldots & u_{2,n} \\ & & u_{3,3} & \ddots & \vdots \\ & & & \ddots & u_{n-1,n} \\ & & & & u_{n,n} \end{bmatrix} ~, \end{equation}

    translates to the packed (column-major) format,

    \begin{equation} U_{\mathrm{packed}} = [ u_{1,1}, u_{1,2}, u_{1,2}, u_{1,3}, u_{2,3}, u_{3,3}, \ldots, u_{1,n}, u_{2,n}, u_{3,2}, \ldots, u_{n-1,n}, u_{n,n} ] ~. \end{equation}

    In general, the indices \((i, j), 1\leq i\leq j \leq n\) of a full upper-diagonal \(n\times n\) matrix translate to the packed vector index,
    1. \(k(i, j) = i - 1 + j * (j - 1) / 2\) for a column-major matrix layout (Fortran-style).
    2. \(k(i, j) = j - 1 + (i - 1) * (2 * n - i) / 2\) for a row-major matrix layout (C-style).
  2. Rectangular Band Packing (RBP or rbpack) which is to be added to this module.
  3. Rectangular Full Packing (RFP or rfpack) for symmetric, Hermitian, or triangular matrices.
    The Rectangular Full Packing is a combination of the contiguous and triangular packings.
    It can be used to pack the upper or lower triangle of a symmetric, Hermitian, or triangular matrix contiguously.
    It offers the package savings of the triangular packing plus the efficiency of using contiguous-pack Level 3 BLAS and LAPACK routines.
    The RFP scheme is typically defined by three parameters in major libraries such as Intel MKL:
    1. A matrix layout parameter, which specifies column major (with the value LAPACK_COL_MAJOR) or row major (with the value LAPACK_ROW_MAJOR) matrix layout.
      By default, the Fortran routines of the ParaMonte library assume column-major layout, unless the procedure is to accessed from C-style programming languages.
    2. A subset parameter (represented by uplo in the LAPACK library), which specifies which upper/lower triangle of the matrix is packed in RFP format.
      The upper/lower triangles are represented with the string values "U" and "L" respectively.
      1. The following figure illustrates the RFP layout of an even-order matrix with upper-diagonal triangle storage.
      2. The following figure illustrates the RFP layout of an odd-order matrix with upper-diagonal triangle storage.
      3. The following figure illustrates the RFP layout of an even-order matrix with lower-diagonal triangle storage.
      4. The following figure illustrates the RFP layout of an odd-order matrix with lower-diagonal triangle storage.
    3. A transposition operation parameter (represented frequently by transA or transB in the LAPACK library), which specifies one of the following three transposition operations on the matrix,
      1. nothing indicating No transposition (as is, with the LAPACK string value "N").
      2. Symmetric transpose (with the value "T").
      3. Conjugate (Hermitian) transpose (with the value "C").
    Note
    A matrix in RFP format, will always have an odd number of rows, unless it is transposed.
    An odd-order matrix has \(\ms{ncol} = \ms{nrow} / 2 + 1\) columns.
    An even-order matrix has \(\ms{ncol} = \ms{nrow} / 2\) columns.
  4. Rectangular Default (i.e., standard, no specific) packing (RDP or rdpack)
    This is the regular matrix package.
    An \(m\times n\) full matrix \(A\) has the form,

    \begin{equation} \large \mathbf{A} = \begin{bmatrix} a_{11} & a_{12} & \cdots & a_{1n} \\ a_{21} & a_{22} & \cdots & a_{2n} \\ \vdots & \vdots & \ddots & \vdots \\ a_{m1} & a_{m2} & \cdots & a_{mn} \end{bmatrix} ~. \end{equation}


Final Remarks


If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

  1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
  2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Author:
Amir Shahmoradi, September 1, 2017, 12:00 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas Austin

Variable Documentation

◆ lfpack

type(lfpack_type), parameter pm_matrixPack::lfpack = lfpack_type()

This is an object instance of class lfpack_type that is exclusively used to signify Linear Full contiguous Packing format of a (triangular) subset of a matrix within an interface of a procedure of the ParaMonte library.

For example usage, see the documentation of the target procedure requiring this object.

See also
lfpack
rfpack
rdpack
lfpack_type
rfpack_type
lcpack_type
rcpack_type
ldpack_type
rdpack_type
package_type


Final Remarks


If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

  1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
  2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Author:
Amir Shahmoradi, September 1, 2017, 12:00 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas Austin

Definition at line 401 of file pm_matrixPack.F90.

◆ MODULE_NAME

character(*,SK), parameter pm_matrixPack::MODULE_NAME = "@pm_matrixPack"

Definition at line 132 of file pm_matrixPack.F90.

◆ rdpack

type(rdpack_type), parameter pm_matrixPack::rdpack = rdpack_type()

This is an object instance of class rdpack_type that is exclusively used to signify Rectangular Sparse (or Standard) Packing format of a given (triangular) subset of a matrix within an interface of a procedure of the ParaMonte library.

For example usage, see the documentation of the target procedure requiring this object.

See also
lfpack
rfpack
rdpack
lfpack_type
rfpack_type
lcpack_type
rcpack_type
ldpack_type
rdpack_type
package_type


Final Remarks


If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

  1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
  2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Author:
Amir Shahmoradi, September 1, 2017, 12:00 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas Austin

Definition at line 263 of file pm_matrixPack.F90.

◆ rfpack

type(rfpack_type), parameter pm_matrixPack::rfpack = rfpack_type()

This is an object instance of class rfpack_type that is exclusively used to signify Rectangular Full contiguous Packing format of a (triangular) subset of a matrix within an interface of a procedure of the ParaMonte library.

For example usage, see the documentation of the target procedure requiring this object.

See also
lfpack
rfpack
rdpack
lfpack_type
rfpack_type
lcpack_type
rcpack_type
ldpack_type
rdpack_type
package_type


Final Remarks


If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

  1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
  2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Author:
Amir Shahmoradi, September 1, 2017, 12:00 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas Austin

Definition at line 468 of file pm_matrixPack.F90.