# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 30.0 `matop` Chapter.
``matop`` - Matrix Operations, Including Inversion
This module provides facilities for four types of problem:
(i) matrix inversion;
(#) matrix factorizations;
(#) matrix arithmetic and manipulation;
(#) matrix functions.
See `Background to the Problems <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01intro.html#background1>`__ where these problems are discussed.
See Also
--------
``naginterfaces.library.examples.matop`` :
This subpackage contains examples for the ``matop`` module.
See also the :ref:`library_matop_ex` subsection.
Functionality Index
-------------------
Action of the matrix exponential on a complex matrix: :meth:`complex_gen_matrix_actexp`
Action of the matrix exponential on a complex matrix (reverse communication): :meth:`complex_gen_matrix_actexp_rcomm`
Action of the matrix exponential on a real matrix: :meth:`real_gen_matrix_actexp`
Action of the matrix exponential on a real matrix (reverse communication): :meth:`real_gen_matrix_actexp_rcomm`
**Inversion (also see** submodule :mod:`~naginterfaces.library.lapacklin` **)**
real :math:`m\times n` matrix
pseudo-inverse: :meth:`real_gen_pseudinv`
real symmetric positive definite matrix
accurate inverse: :meth:`real_symm_posdef_inv`
approximate inverse: :meth:`real_symm_posdef_inv_noref`
**Matrix Arithmetic and Manipulation**
matrix addition
complex matrices: :meth:`complex_addsub`
real matrices: :meth:`real_addsub`
matrix multiplication
rectangular matrices
update
real matrices: :meth:`real_gen_matmul`
triangular matrices
in-place
complex matrices: :meth:`complex_tri_matmul_inplace`
real matrices: :meth:`real_tri_matmul_inplace`
update
complex matrices: :meth:`complex_tri_matmul`
real matrices: :meth:`real_tri_matmul`
matrix storage conversion
full to packed triangular storage
complex matrices: :meth:`ztrttp`
real matrices: :meth:`dtrttp`
full to Rectangular Full Packed storage
complex matrix: :meth:`ztrttf`
real matrix: :meth:`dtrttf`
packed band :math:`\leftrightarrow` rectangular storage, special provision for diagonal
complex matrices: :meth:`complex_band_pack`
real matrices: :meth:`real_band_pack`
packed triangular :math:`\leftrightarrow` square storage, special provision for diagonal
complex matrices: :meth:`complex_tri_pack`
real matrices: :meth:`real_tri_pack`
packed triangular to full storage
complex matrices: :meth:`ztpttr`
real matrices: :meth:`dtpttr`
packed triangular to Rectangular Full Packed storage
complex matrices: :meth:`ztpttf`
real matrices: :meth:`dtpttf`
Rectangular Full Packed to full storage
complex matrices: :meth:`ztfttr`
real matrices: :meth:`dtfttr`
Rectangular Full Packed to packed triangular storage
complex matrices: :meth:`ztfttp`
real matrices: :meth:`dtfttp`
matrix subtraction
real matrices: :meth:`real_addsub`
matrix transpose: :meth:`real_gen_trans_inplace`
**Matrix function**
complex Hermitian :math:`n\times n` matrix
matrix exponential: :meth:`complex_herm_matrix_exp`
matrix function: :meth:`complex_herm_matrix_fun`
complex :math:`n\times n` matrix
condition number for a matrix exponential: :meth:`complex_gen_matrix_cond_exp`
condition number for a matrix exponential, logarithm, sine, cosine, sinh or cosh: :meth:`complex_gen_matrix_cond_std`
condition number for a matrix function, using numerical differentiation: :meth:`complex_gen_matrix_cond_num`
condition number for a matrix function, using user-supplied derivatives: :meth:`complex_gen_matrix_cond_usd`
condition number for a matrix logarithm: :meth:`complex_gen_matrix_cond_log`
condition number for a matrix power: :meth:`complex_gen_matrix_cond_pow`
condition number for the matrix square root, logarithm, sine, cosine, sinh or cosh: :meth:`complex_gen_matrix_cond_sqrt`
Fréchet derivative
matrix exponential: :meth:`complex_gen_matrix_frcht_exp`
matrix logarithm: :meth:`complex_gen_matrix_frcht_log`
matrix power: :meth:`complex_gen_matrix_frcht_pow`
general power
matrix: :meth:`complex_gen_matrix_pow`
matrix exponential: :meth:`complex_gen_matrix_exp`
matrix exponential, sine, cosine, sinh or cosh: :meth:`complex_gen_matrix_fun_std`
matrix function, using numerical differentiation: :meth:`complex_gen_matrix_fun_num`
matrix function, using user-supplied derivatives: :meth:`complex_gen_matrix_fun_usd`
matrix logarithm: :meth:`complex_gen_matrix_log`
matrix square root: :meth:`complex_gen_matrix_sqrt`
upper triangular
matrix square root: :meth:`complex_tri_matrix_sqrt`
real :math:`n\times n` matrix
condition number for a matrix exponential: :meth:`real_gen_matrix_cond_exp`
condition number for a matrix function, using numerical differentiation: :meth:`real_gen_matrix_cond_num`
condition number for a matrix function, using user-supplied derivatives: :meth:`real_gen_matrix_cond_usd`
condition number for a matrix logarithm: :meth:`real_gen_matrix_cond_log`
condition number for a matrix power: :meth:`real_gen_matrix_cond_pow`
condition number for the matrix exponential, logarithm, sine, cosine, sinh or cosh: :meth:`real_gen_matrix_cond_std`
condition number for the matrix square root, logarithm, sine, cosine, sinh or cosh: :meth:`real_gen_matrix_cond_sqrt`
Fréchet derivative
matrix exponential: :meth:`real_gen_matrix_frcht_exp`
matrix logarithm: :meth:`real_gen_matrix_frcht_log`
matrix power: :meth:`real_gen_matrix_frcht_pow`
general power
matrix exponential: :meth:`real_gen_matrix_pow`
matrix exponential: :meth:`real_gen_matrix_exp`
matrix exponential, sine, cosine, sinh or cosh: :meth:`real_gen_matrix_fun_std`
matrix function, using numerical differentiation: :meth:`real_gen_matrix_fun_num`
matrix function, using user-supplied derivatives: :meth:`real_gen_matrix_fun_usd`
matrix logarithm: :meth:`real_gen_matrix_log`
matrix square root: :meth:`real_gen_matrix_sqrt`
upper quasi-triangular
matrix square root: :meth:`real_tri_matrix_sqrt`
real symmetric :math:`n\times n` matrix
matrix exponential: :meth:`real_symm_matrix_exp`
matrix function: :meth:`real_symm_matrix_fun`
**Matrix Transformations**
complex :math:`m\times n\left(m\leq n\right)` matrix
:math:`RQ` factorization: :meth:`complex_gen_rq`
complex matrix, form unitary matrix: :meth:`complex_gen_rq_formq`
complex upper trapezoidal matrix
:math:`RQ` factorization: :meth:`complex_trapez_rq`
eigenproblem :math:`Ax = \lambda Bx`, :math:`A`, :math:`B` banded
reduction to standard symmetric problem: :meth:`real_symm_posdef_geneig`
modified Cholesky factorization, form positive definite perturbed input matrix: :meth:`real_mod_chol_perturbed_a`
modified Cholesky factorization of a real symmetric matrix: :meth:`real_modified_cholesky`
non-negative matrix factorization: :meth:`real_nmf`
non-negative matrix factorization, reverse communication: :meth:`real_nmf_rcomm`
real almost block-diagonal matrix
:math:`LU` factorization: :meth:`real_gen_blkdiag_lu`
real band symmetric positive definite matrix
:math:`ULDL^\mathrm{T}U^\mathrm{T}` factorization: :meth:`real_symm_posdef_fac`
variable bandwidth, :math:`LDL^\mathrm{T}` factorization: :meth:`real_vband_posdef_fac`
real :math:`m\times n\left(m\leq n\right)` matrix
:math:`RQ` factorization: :meth:`real_gen_rq`
real matrix
form orthogonal matrix: :meth:`real_gen_rq_formq`
real sparse matrix
factorization: :meth:`real_gen_sparse_lu`
factorization, known sparsity pattern: :meth:`real_gen_sparse_lu_reuse`
real upper trapezoidal matrix
:math:`RQ` factorization: :meth:`real_trapez_rq`
tridiagonal matrix
:math:`LU` factorization: :meth:`real_gen_tridiag_lu`
For full information please refer to the NAG Library document
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01intro.html
"""
# NAG Copyright 2017-2024.
[docs]def real_symm_posdef_inv(a):
r"""
``real_symm_posdef_inv`` calculates the accurate inverse of a real symmetric positive definite matrix, using a Cholesky factorization and iterative refinement.
.. _f01ab-py2-py-doc:
For full information please refer to the NAG Library document for f01ab
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01abf.html
.. _f01ab-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n+1, n\right)`
The upper triangle of the :math:`n\times n` positive definite symmetric matrix :math:`A`. The elements of the array below the diagonal need not be set.
**Returns**
**a** : float, ndarray, shape :math:`\left(n+1, n\right)`
The lower triangle of the inverse matrix :math:`X` is stored in the elements of the array below the diagonal, in rows :math:`2` to :math:`n+1`; :math:`x_{{ij}}` is stored in :math:`\mathrm{a}[i,j-1]` for :math:`i\geq j`. The upper triangle of the original matrix is unchanged.
**b** : float, ndarray, shape :math:`\left(n, n\right)`
The lower triangle of the inverse matrix :math:`X`, with :math:`x_{{ij}}` stored in :math:`\mathrm{b}[i-1,j-1]`, for :math:`i\geq j`.
.. _f01ab-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
The matrix :math:`A` is not positive definite, possibly due to rounding errors.
(`errno` :math:`2`)
The refinement process failed to converge. The matrix :math:`A` is ill-conditioned.
(`errno` :math:`3`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 1`.
.. _f01ab-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
To compute the inverse :math:`X` of a real symmetric positive definite matrix :math:`A`, ``real_symm_posdef_inv`` first computes a Cholesky factorization of :math:`A` as :math:`A = LL^\mathrm{T}`, where :math:`L` is lower triangular.
An approximation to :math:`X` is found by computing :math:`L^{-1}` and then the product :math:`L^{-\mathrm{T}}L^{-1}`.
The residual matrix :math:`R = I-AX` is calculated using additional precision, and a correction :math:`D` to :math:`X` is found by solving :math:`LL^\mathrm{T}D = R`. :math:`X` is replaced by :math:`X+D`, and this iterative refinement of the inverse is repeated until full machine accuracy has been obtained.
.. _f01ab-py2-py-references:
**References**
Wilkinson, J H and Reinsch, C, 1971, `Handbook for Automatic Computation II, Linear Algebra`, Springer--Verlag
"""
raise NotImplementedError
[docs]def real_symm_posdef_inv_noref(a):
r"""
``real_symm_posdef_inv_noref`` calculates the approximate inverse of a real symmetric positive definite matrix, using a Cholesky factorization.
.. _f01ad-py2-py-doc:
For full information please refer to the NAG Library document for f01ad
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01adf.html
.. _f01ad-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n+1, n\right)`
The upper triangle of the :math:`n\times n` positive definite symmetric matrix :math:`A`. The elements of the array below the diagonal need not be set.
**Returns**
**a** : float, ndarray, shape :math:`\left(n+1, n\right)`
The lower triangle of the inverse matrix :math:`X` is stored in the elements of the array below the diagonal, in rows :math:`2` to :math:`n+1`; :math:`x_{{ij}}` is stored in :math:`\mathrm{a}[i,j-1]` for :math:`i\geq j`. The upper triangle of the original matrix is unchanged.
.. _f01ad-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
The matrix :math:`A` is not positive definite, possibly due to rounding errors.
(`errno` :math:`2`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
.. _f01ad-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
To compute the inverse :math:`X` of a real symmetric positive definite matrix :math:`A`, ``real_symm_posdef_inv_noref`` first computes a Cholesky factorization of :math:`A` as :math:`A = LL^\mathrm{T}`, where :math:`L` is lower triangular.
It then computes :math:`L^{-1}` and finally forms :math:`X` as the product :math:`L^{-\mathrm{T}}L^{-1}`.
.. _f01ad-py2-py-references:
**References**
Wilkinson, J H and Reinsch, C, 1971, `Handbook for Automatic Computation II, Linear Algebra`, Springer--Verlag
"""
raise NotImplementedError
[docs]def real_gen_pseudinv(t, a):
r"""
``real_gen_pseudinv`` calculates the rank and pseudo-inverse of an :math:`m\times n` real matrix, :math:`m\geq n`, using a :math:`QR` factorization with column interchanges.
.. _f01bl-py2-py-doc:
For full information please refer to the NAG Library document for f01bl
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01blf.html
.. _f01bl-py2-py-parameters:
**Parameters**
**t** : float
The tolerance used to decide when elements can be regarded as zero (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01blf.html#fcomments>`__).
**a** : float, array-like, shape :math:`\left(m, n\right)`
The :math:`m\times n` rectangular matrix :math:`A`.
**Returns**
**a** : float, ndarray, shape :math:`\left(m, n\right)`
The transpose of the pseudo-inverse of :math:`A`.
**aijmax** : float, ndarray, shape :math:`\left(n\right)`
:math:`\mathrm{aijmax}[i-1]` contains the element of largest modulus in the reduced matrix at the :math:`i`\ th stage. If :math:`r < n`, then only the first :math:`r+1` elements of :math:`\mathrm{aijmax}` have values assigned to them; the remaining elements are unused. The ratio :math:`\mathrm{aijmax}[0]/\mathrm{aijmax}[r-1]` usually gives an indication of the condition number of the original matrix (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01blf.html#fcomments>`__).
**irank** : int
:math:`r`, the rank of :math:`A` as determined using the tolerance :math:`\mathrm{t}`.
**inc** : int, ndarray, shape :math:`\left(n\right)`
The record of the column interchanges in the Householder factorization.
.. _f01bl-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
Inverse not found. Incorrect :math:`\mathrm{irank}`.
(`errno` :math:`2`)
Invalid tolerance, :math:`\mathrm{t}` too large: :math:`\mathrm{t} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
Invalid tolerance, :math:`\mathrm{t} < 0.0`: :math:`\mathrm{t} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq n`.
.. _f01bl-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
Householder's factorization with column interchanges is used in the decomposition :math:`F = QU`, where :math:`F` is :math:`A` with its columns permuted, :math:`Q` is the first :math:`r` columns of an :math:`m\times m` orthogonal matrix and :math:`U` is an :math:`r\times n` upper-trapezoidal matrix of rank :math:`r`.
The pseudo-inverse of :math:`F` is given by :math:`X` where
.. math::
X = U^\mathrm{T}\left(UU^\mathrm{T}\right)^{-1}Q^\mathrm{T}\text{.}
If the matrix is found to be of maximum rank, :math:`r = n`, :math:`U` is a nonsingular :math:`n\times n` upper-triangular matrix and the pseudo-inverse of :math:`F` simplifies to :math:`X = U^{-1}Q^\mathrm{T}`.
The transpose of the pseudo-inverse of :math:`A` is overwritten on :math:`A`.
.. _f01bl-py2-py-references:
**References**
Peters, G and Wilkinson, J H, 1970, `The least squares problem and pseudo-inverses`, Comput. J. (13), 309--316
Wilkinson, J H and Reinsch, C, 1971, `Handbook for Automatic Computation II, Linear Algebra`, Springer--Verlag
"""
raise NotImplementedError
[docs]def real_gen_sparse_lu(n, nz, warnlev, errlev, a, irn, icn, abort, pivot=0.1, lblock=True, grow=True, io_manager=None):
r"""
``real_gen_sparse_lu`` factorizes a real sparse matrix.
The function either forms the :math:`LU` factorization of a permutation of the entire matrix, or, optionally, first permutes the matrix to block lower triangular form and then only factorizes the diagonal blocks.
.. _f01br-py2-py-doc:
For full information please refer to the NAG Library document for f01br
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01brf.html
.. _f01br-py2-py-parameters:
**Parameters**
**n** : int
:math:`n`, the order of the matrix :math:`A`.
**nz** : int
The number of nonzero elements in the matrix :math:`A`.
**warnlev** : int
Setting :math:`\mathrm{warnlev} = 0` disables output of warning messages during the process of the computation. Setting :math:`\mathrm{warnlev} = 1` enables these messages.
**errlev** : int
Setting :math:`\mathrm{errlev} = 0` disables output of error messages during the process of the computation. Setting :math:`\mathrm{errlev} = 1` enables these messages.
**a** : float, array-like, shape :math:`\left(\textit{licn}\right)`
:math:`\mathrm{a}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,\mathrm{nz}`, must contain the nonzero elements of the sparse matrix :math:`A`. They can be in any order since ``real_gen_sparse_lu`` will reorder them.
**irn** : int, array-like, shape :math:`\left(\textit{lirn}\right)`
:math:`\mathrm{irn}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,\mathrm{nz}`, must contain the row index of the nonzero element stored in :math:`\mathrm{a}[i-1]`.
**icn** : int, array-like, shape :math:`\left(\textit{licn}\right)`
:math:`\mathrm{icn}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,\mathrm{nz}`, must contain the column index of the nonzero element stored in :math:`\mathrm{a}[i-1]`.
**abort** : bool, array-like, shape :math:`\left(4\right)`
If :math:`\mathrm{abort}[0] = \mathbf{True}`, ``real_gen_sparse_lu`` will exit immediately on detecting a structural singularity (one that depends on the pattern of nonzeros) and return :math:`\mathrm{errno}` = 1; otherwise it will complete the factorization (see `Singular and Rectangular Systems <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01brf.html#fcomments3>`__).
If :math:`\mathrm{abort}[1] = \mathbf{True}`, ``real_gen_sparse_lu`` will exit immediately on detecting a numerical singularity (one that depends on the numerical values) and return :math:`\mathrm{errno}` = 2; otherwise it will complete the factorization (see `Singular and Rectangular Systems <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01brf.html#fcomments3>`__).
If :math:`\mathrm{abort}[2] = \mathbf{True}`, ``real_gen_sparse_lu`` will exit immediately (with :math:`\mathrm{errno}` = 5) when the arrays :math:`\mathrm{a}` and :math:`\mathrm{comm}`\ ['icn'] are filled up by the previously factorized, active and unfactorized parts of the matrix; otherwise it continues so that better guidance on necessary array sizes can be given in :math:`\mathrm{comm}\ ['idisp'][5]` and :math:`\mathrm{comm}\ ['idisp'][6]`, and will exit with :math:`\textit{errno}` in the range :math:`4` to :math:`6`.
Note that there is always an immediate error exit if the array :math:`\mathrm{irn}` is too small.
If :math:`\mathrm{abort}[3] = \mathbf{True}`, ``real_gen_sparse_lu`` exits immediately (with :math:`\mathrm{errno}` = 13) if it finds duplicate elements in the input matrix.
If :math:`\mathrm{abort}[3] = \mathbf{False}`, ``real_gen_sparse_lu`` proceeds using a value equal to the sum of the duplicate elements.
In either case details of each duplicate element are output on the file object associated with the advisory I/O unit (see :class:`~naginterfaces.base.utils.FileObjManager`), unless suppressed by the value of :math:`\textit{errno}` on entry.
`Suggested value`:
:math:`\mathrm{abort}[0] = \mathbf{True}`
:math:`\mathrm{abort}[1] = \mathbf{True}`
:math:`\mathrm{abort}[2] = \mathbf{False}`
:math:`\mathrm{abort}[3] = \mathbf{True}`
**pivot** : float, optional
Should have a value in the range :math:`0.0\leq \mathrm{pivot}\leq 0.9999` and is used to control the choice of pivots. If :math:`\mathrm{pivot} < 0.0`, the value :math:`0.0` is assumed, and if :math:`\mathrm{pivot} > 0.9999`, the value :math:`0.9999` is assumed. When searching a row for a pivot, any element is excluded which is less than :math:`\mathrm{pivot}` times the largest of those elements in the row available as pivots. Thus decreasing :math:`\mathrm{pivot}` biases the algorithm to maintaining sparsity at the expense of stability.
**lblock** : bool, optional
If :math:`\mathrm{lblock} = \mathbf{True}`, the matrix is preordered into block lower triangular form before the :math:`LU` factorization is performed; otherwise the entire matrix is factorized.
**grow** : bool, optional
If :math:`\mathrm{grow} = \mathbf{True}`, then on exit :math:`\mathrm{increase}` contains an estimate (an upper bound) of the increase in size of elements encountered during the factorization. If the matrix is well-scaled (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01brf.html#fcomments2>`__), then a high value for :math:`\mathrm{increase}` indicates that the :math:`LU` factorization may be inaccurate and you should be wary of the results and perhaps increase the argument :math:`\mathrm{pivot}` for subsequent runs (see `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01brf.html#accuracy>`__).
**io_manager** : FileObjManager, optional
Manager for I/O in this routine.
**Returns**
**a** : float, ndarray, shape :math:`\left(\textit{licn}\right)`
The nonzero elements in the :math:`LU` factorization. The array must **not** be changed by you between a call of ``real_gen_sparse_lu`` and a call of :meth:`linsys.real_sparse_fac_solve <naginterfaces.library.linsys.real_sparse_fac_solve>`.
**irn** : int, ndarray, shape :math:`\left(\textit{lirn}\right)`
:math:`\mathrm{irn}` is overwritten and is not needed for subsequent calls of :meth:`real_gen_sparse_lu_reuse` or :meth:`linsys.real_sparse_fac_solve <naginterfaces.library.linsys.real_sparse_fac_solve>`.
**comm** : dict, communication object
Information about the factorization for subsequent communication to :meth:`real_gen_sparse_lu_reuse` or :meth:`linsys.real_sparse_fac_solve <naginterfaces.library.linsys.real_sparse_fac_solve>`.
**increase** : None or float
If :math:`\mathrm{grow} = \mathbf{True}`, :math:`\mathrm{increase}` contains an estimate (an upper bound) of the increase in size of elements encountered during the factorization (see :math:`\mathrm{grow}`).
.. _f01br-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
Matrix is structurally singular -- decomposition aborted :math:`\mathrm{RANK} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`1`)
Matrix is structurally singular -- decomposition aborted.
(`errno` :math:`2`)
Matrix is numerically singular -- decomposition aborted.
(`errno` :math:`3`)
:math:`\textit{lirn}` too small. Decomposition aborted at stage :math:`\langle\mathit{\boldsymbol{value}}\rangle` in block :math:`\langle\mathit{\boldsymbol{value}}\rangle` with first row :math:`\langle\mathit{\boldsymbol{value}}\rangle` and last row :math:`\langle\mathit{\boldsymbol{value}}\rangle`. To continue set :math:`\textit{lirn}` to at least :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
:math:`\textit{lirn}` too small. Decomposition aborted at stage :math:`\langle\mathit{\boldsymbol{value}}\rangle` in block :math:`\langle\mathit{\boldsymbol{value}}\rangle` with first row :math:`\langle\mathit{\boldsymbol{value}}\rangle` and last row :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`4`)
:math:`\textit{licn}` much too small. Decomposition aborted at stage :math:`\langle\mathit{\boldsymbol{value}}\rangle` in block :math:`\langle\mathit{\boldsymbol{value}}\rangle` with first row :math:`\langle\mathit{\boldsymbol{value}}\rangle` and last row :math:`\langle\mathit{\boldsymbol{value}}\rangle`. To continue set :math:`\textit{licn}` to at least :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`4`)
:math:`\textit{licn}` much too small. Decomposition aborted at stage :math:`\langle\mathit{\boldsymbol{value}}\rangle` in block :math:`\langle\mathit{\boldsymbol{value}}\rangle` with first row :math:`\langle\mathit{\boldsymbol{value}}\rangle` and last row :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`5`)
:math:`\textit{licn}` too small. Decomposition aborted at stage :math:`\langle\mathit{\boldsymbol{value}}\rangle` in block :math:`\langle\mathit{\boldsymbol{value}}\rangle` with first row :math:`\langle\mathit{\boldsymbol{value}}\rangle` and last row :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`5`)
:math:`\textit{licn}` too small. Decomposition aborted at stage :math:`\langle\mathit{\boldsymbol{value}}\rangle` in block :math:`\langle\mathit{\boldsymbol{value}}\rangle` with first row :math:`\langle\mathit{\boldsymbol{value}}\rangle` and last row :math:`\langle\mathit{\boldsymbol{value}}\rangle`. To continue set :math:`\textit{licn}` to at least :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`5`)
:math:`\textit{licn}` too small. For successful decomposition set :math:`\textit{licn}` to at least :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`6`)
:math:`\textit{licn}` and :math:`\textit{lirn}` too small. Decomposition aborted at stage :math:`\langle\mathit{\boldsymbol{value}}\rangle` in block :math:`\langle\mathit{\boldsymbol{value}}\rangle` with first row :math:`\langle\mathit{\boldsymbol{value}}\rangle` and last row :math:`\langle\mathit{\boldsymbol{value}}\rangle`. To continue set :math:`\textit{lirn}` to at least :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`6`)
:math:`\textit{licn}` and :math:`\textit{lirn}` too small. Decomposition aborted at stage :math:`\langle\mathit{\boldsymbol{value}}\rangle` in block :math:`\langle\mathit{\boldsymbol{value}}\rangle` with first row :math:`\langle\mathit{\boldsymbol{value}}\rangle` and last row :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`7`)
:math:`\textit{licn}` not big enough for permutation -- increase by :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`8`)
On entry, :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{n} > 0`.
(`errno` :math:`9`)
On entry, :math:`\mathrm{nz} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nz} > 0`.
(`errno` :math:`10`)
On entry, :math:`\textit{licn} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{nz} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{licn}\geq \mathrm{nz}`.
(`errno` :math:`11`)
On entry, :math:`\textit{lirn} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{nz} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{lirn}\geq \mathrm{nz}`.
(`errno` :math:`12`)
On entry, :math:`\mathrm{irn}[I-1]` or :math:`\mathrm{icn}[I-1]` is out of range: :math:`I = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{a}[I-1] = \langle\mathit{\boldsymbol{value}}\rangle` :math:`\mathrm{irn}[I-1] = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{icn}[I-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`13`)
On entry, duplicate elements found -- see advisory messages.
(`errno` :math:`14`)
On entry, :math:`\mathrm{warnlev} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{warnlev} = 0` or :math:`1`.
(`errno` :math:`15`)
On entry, :math:`\mathrm{errlev} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{errlev} = 0` or :math:`1`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`-2`)
Matrix is numerically singular -- decomposition completed.
(`errno` :math:`-1`)
Matrix is structurally singular -- decomposition completed.
.. _f01br-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
Given a real sparse matrix :math:`A`, ``real_gen_sparse_lu`` may be used to obtain the :math:`LU` factorization of a permutation of :math:`A`,
.. math::
PAQ = LU
where :math:`P` and :math:`Q` are permutation matrices, :math:`L` is unit lower triangular and :math:`U` is upper triangular.
The function uses a sparse variant of Gaussian elimination, and the pivotal strategy is designed to compromise between maintaining sparsity and controlling loss of accuracy through round-off.
Optionally the function first permutes the matrix into block lower triangular form and then only factorizes the diagonal blocks.
For some matrices this gives a considerable saving in storage and execution time.
Extensive data checks are made; duplicated nonzeros can be accumulated.
The factorization is intended to be used by :meth:`linsys.real_sparse_fac_solve <naginterfaces.library.linsys.real_sparse_fac_solve>` to solve sparse systems of linear equations :math:`Ax = b` or :math:`A^\mathrm{T}x = b`.
If several matrices of the same sparsity pattern are to be factorized, :meth:`real_gen_sparse_lu_reuse` should be used for the second and subsequent matrices.
The method is fully described in Duff (1977).
A more recent algorithm for the same calculation is provided by :meth:`sparse.direct_real_gen_lu <naginterfaces.library.sparse.direct_real_gen_lu>`.
.. _f01br-py2-py-references:
**References**
Duff, I S, 1977, `MA28 -- a set of Fortran subroutines for sparse unsymmetric linear equations`, AERE Report R8730, HMSO
"""
raise NotImplementedError
[docs]def real_gen_sparse_lu_reuse(warnlev, a, ivect, jvect, comm, grow, eta=0.0001, abort=True, io_manager=None):
r"""
``real_gen_sparse_lu_reuse`` factorizes a real sparse matrix using the pivotal sequence previously obtained by :meth:`real_gen_sparse_lu` when a matrix of the same sparsity pattern was factorized.
.. _f01bs-py2-py-doc:
For full information please refer to the NAG Library document for f01bs
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01bsf.html
.. _f01bs-py2-py-parameters:
**Parameters**
**warnlev** : int
Setting :math:`\mathrm{warnlev} = 0` disables output of warning messages during the process of the computation. Setting :math:`\mathrm{warnlev} = 1` enables these messages.
**a** : float, array-like, shape :math:`\left(\textit{licn}\right)`
:math:`\mathrm{a}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,\textit{nz}`, must contain the nonzero elements of the sparse matrix :math:`A`. They can be in any order since ``real_gen_sparse_lu_reuse`` will reorder them.
**ivect** : int, array-like, shape :math:`\left(\textit{nz}\right)`
:math:`\mathrm{ivect}[\textit{i}-1]` and :math:`\mathrm{jvect}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,\textit{nz}`, must contain the row index and the column index respectively of the nonzero element stored in :math:`\mathrm{a}[i-1]`.
**jvect** : int, array-like, shape :math:`\left(\textit{nz}\right)`
:math:`\mathrm{ivect}[\textit{i}-1]` and :math:`\mathrm{jvect}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,\textit{nz}`, must contain the row index and the column index respectively of the nonzero element stored in :math:`\mathrm{a}[i-1]`.
**comm** : dict, communication object
Communication structure.
This argument must have been initialized by a prior call to :meth:`real_gen_sparse_lu`.
**grow** : bool
If :math:`\mathrm{grow} = \mathbf{True}`, then on exit :math:`\mathrm{w}[0]` contains an estimate (an upper bound) of the increase in size of elements encountered during the factorization. If the matrix is well-scaled (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01bsf.html#fcomments>`__), then a high value for :math:`\mathrm{w}[0]` indicates that the :math:`LU` factorization may be inaccurate and you should be wary of the results and perhaps increase the argument :math:`\textit{pivot}` for subsequent runs (see `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01bsf.html#accuracy>`__).
**eta** : float, optional
The relative pivot threshold below which an error diagnostic is provoked and :math:`\textit{errno}` is set to :math:`\mathrm{errno}` = 7. If :math:`\mathrm{eta}` is greater than :math:`1.0`, then no check on pivot size is made.
**abort** : bool, optional
If :math:`\mathrm{abort} = \mathbf{True}`, ``real_gen_sparse_lu_reuse`` exits immediately (with :math:`\mathrm{errno}` = 8) if it finds duplicate elements in the input matrix.
If :math:`\mathrm{abort} = \mathbf{False}`, ``real_gen_sparse_lu_reuse`` proceeds using a value equal to the sum of the duplicate elements.
In either case details of each duplicate element are output on the file object associated with the advisory I/O unit (see :class:`~naginterfaces.base.utils.FileObjManager`), unless suppressed by the value of :math:`\textit{errno}` on entry.
**io_manager** : FileObjManager, optional
Manager for I/O in this routine.
**Returns**
**a** : float, ndarray, shape :math:`\left(\textit{licn}\right)`
The nonzero elements in the :math:`LU` factorization. The array must **not** be changed by you between a call of ``real_gen_sparse_lu_reuse`` and a call of :meth:`linsys.real_sparse_fac_solve <naginterfaces.library.linsys.real_sparse_fac_solve>`.
**w** : float, ndarray, shape :math:`\left(n\right)`
If :math:`\mathrm{grow} = \mathbf{True}`, :math:`\mathrm{w}[0]` contains an estimate (an upper bound) of the increase in size of elements encountered during the factorization (see :math:`\mathrm{grow}`); the rest of the array is used as workspace.
If :math:`\mathrm{grow} = \mathbf{False}`, the array is not used.
**rpmin** : float
If :math:`\mathrm{eta}` is less than :math:`1.0`, then :math:`\mathrm{rpmin}` gives the smallest ratio of the pivot to the largest element in the row of the corresponding upper triangular factor thus monitoring the stability of the factorization. If :math:`\mathrm{rpmin}` is very small it may be advisable to perform a new factorization using :meth:`real_gen_sparse_lu`.
.. _f01bs-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n > 0`.
(`errno` :math:`2`)
On entry, :math:`\textit{nz} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{nz} > 0`.
(`errno` :math:`3`)
On entry, :math:`\textit{licn} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{nz} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{licn}\geq \textit{nz}`.
(`errno` :math:`4`)
On entry, :math:`{\textit{irn}}[I-1]` in :meth:`real_gen_sparse_lu` or :math:`\mathrm{comm}\ ['icn'][I-1]` is out of range: :math:`I = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{a}[I-1] = \langle\mathit{\boldsymbol{value}}\rangle` :math:`{\textit{irn}}[I-1] = \langle\mathit{\boldsymbol{value}}\rangle` in :meth:`real_gen_sparse_lu`, :math:`\mathrm{comm}\ ['icn'][I-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`5`)
Nonzero element (:math:`\langle\mathit{\boldsymbol{value}}\rangle`, :math:`\langle\mathit{\boldsymbol{value}}\rangle`) was not in L/U pattern.
(`errno` :math:`5`)
Nonzero element (:math:`\langle\mathit{\boldsymbol{value}}\rangle`, :math:`\langle\mathit{\boldsymbol{value}}\rangle`) in zero off-diagonal block.
(`errno` :math:`6`)
Numerical singularity in row :math:`\langle\mathit{\boldsymbol{value}}\rangle` - decomposition aborted.
(`errno` :math:`8`)
On entry, duplicate elements found -- see advisory messages.
(`errno` :math:`9`)
On entry, :math:`\mathrm{warnlev} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{warnlev} = 0` or :math:`1`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`7`)
Subthreshold pivot in row :math:`\langle\mathit{\boldsymbol{value}}\rangle` - decomposition completed.
.. _f01bs-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``real_gen_sparse_lu_reuse`` accepts as input a real sparse matrix of the same sparsity pattern as a matrix previously factorized by a call of :meth:`real_gen_sparse_lu`.
It first applies to the matrix the same permutations as were used by :meth:`real_gen_sparse_lu`, both for permutation to block triangular form and for pivoting, and then performs Gaussian elimination to obtain the :math:`LU` factorization of the diagonal blocks.
Extensive data checks are made; duplicated nonzeros can be accumulated.
The factorization is intended to be used by :meth:`linsys.real_sparse_fac_solve <naginterfaces.library.linsys.real_sparse_fac_solve>` to solve sparse systems of linear equations :math:`Ax = b` or :math:`A^\mathrm{T}x = b`.
``real_gen_sparse_lu_reuse`` is much faster than :meth:`real_gen_sparse_lu` and in some applications it is expected that there will be many calls of ``real_gen_sparse_lu_reuse`` for each call of :meth:`real_gen_sparse_lu`.
The method is fully described in Duff (1977).
A more recent algorithm for the same calculation is provided by :meth:`sparse.direct_real_gen_lu <naginterfaces.library.sparse.direct_real_gen_lu>`.
.. _f01bs-py2-py-references:
**References**
Duff, I S, 1977, `MA28 -- a set of Fortran subroutines for sparse unsymmetric linear equations`, AERE Report R8730, HMSO
"""
raise NotImplementedError
[docs]def real_symm_posdef_fac(k, a):
r"""
``real_symm_posdef_fac`` performs a :math:`ULDL^\mathrm{T}U^\mathrm{T}` decomposition of a real symmetric positive definite band matrix.
.. _f01bu-py2-py-doc:
For full information please refer to the NAG Library document for f01bu
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01buf.html
.. _f01bu-py2-py-parameters:
**Parameters**
**k** : int
:math:`k`, the change-over point in the decomposition.
**a** : float, array-like, shape :math:`\left(\textit{m1}, n\right)`
The upper triangle of the :math:`n\times n` symmetric band matrix :math:`A`, with the diagonal of the matrix stored in the :math:`\left(m+1\right)`\ th row of the array, and the :math:`m` superdiagonals within the band stored in the first :math:`m` rows of the array. Each column of the matrix is stored in the corresponding column of the array. For example, if :math:`n = 6` and :math:`m = 2`, the storage scheme is
.. math::
\begin{array}{llllll}\text{*}&\text{*}&a_{13}&a_{24}&a_{35}&a_{46}\\\text{*}&a_{12}&a_{23}&a_{34}&a_{45}&a_{56}\\a_{11}&a_{22}&a_{33}&a_{44}&a_{55}&a_{66}\end{array}
Elements in the top left corner of the array are not used. The matrix elements within the band can be assigned to the correct elements of the array using the following code:
::
for j in range(A.shape[1]):
for i in range(max(0, j+1-m1), j+1):
a[i-j+m1-1, j] = A[i, j]
**Returns**
**a** : float, ndarray, shape :math:`\left(\textit{m1}, n\right)`
:math:`A` is overwritten by the corresponding elements of :math:`L`, :math:`D` and :math:`U`.
.. _f01bu-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{k} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{k}\leq n`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{k} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{m1}-1 = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{k}\geq \textit{m1}-1`.
(`errno` :math:`2`)
The matrix :math:`A` is not positive definite.
(`errno` :math:`3`)
The matrix :math:`A` is not positive definite.
.. _f01bu-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
The symmetric positive definite matrix :math:`A`, of order :math:`n` and bandwidth :math:`2m+1`, is divided into the leading principal sub-matrix of order :math:`k` and its complement, where :math:`m\leq k\leq n`.
A :math:`UDU^\mathrm{T}` decomposition of the latter and an :math:`LDL^\mathrm{T}` decomposition of the former are obtained by means of a sequence of elementary transformations, where :math:`U` is unit upper triangular, :math:`L` is unit lower triangular and :math:`D` is diagonal.
Thus if :math:`k = n`, an :math:`LDL^\mathrm{T}` decomposition of :math:`A` is obtained.
This function is specifically designed to precede :meth:`real_symm_posdef_geneig` for the transformation of the symmetric-definite eigenproblem :math:`Ax = \lambda Bx` by the method of Crawford where :math:`A` and :math:`B` are of band form.
In this context, :math:`k` is chosen to be close to :math:`n/2` and the decomposition is applied to the matrix :math:`B`.
.. _f01bu-py2-py-references:
**References**
Wilkinson, J H, 1965, `The Algebraic Eigenvalue Problem`, Oxford University Press, Oxford
Wilkinson, J H and Reinsch, C, 1971, `Handbook for Automatic Computation II, Linear Algebra`, Springer--Verlag
"""
raise NotImplementedError
[docs]def real_symm_posdef_geneig(k, a, b):
r"""
``real_symm_posdef_geneig`` transforms the generalized symmetric-definite eigenproblem :math:`Ax = \lambda \mathrm{b}x` to the equivalent standard eigenproblem :math:`Cy = \lambda y`, where :math:`A`, :math:`\mathrm{b}` and :math:`C` are symmetric band matrices and :math:`\mathrm{b}` is positive definite. :math:`\mathrm{b}` must have been decomposed by :meth:`real_symm_posdef_fac`.
.. _f01bv-py2-py-doc:
For full information please refer to the NAG Library document for f01bv
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01bvf.html
.. _f01bv-py2-py-parameters:
**Parameters**
**k** : int
:math:`k`, the change-over point in the transformations. It must be the same as the value used by :meth:`real_symm_posdef_fac` in the decomposition of :math:`B`.
`Suggested value`: the optimum value is the multiple of :math:`m_A` nearest to :math:`n/2`.
**a** : float, array-like, shape :math:`\left(\textit{ma1}, n\right)`
The upper triangle of the :math:`n\times n` symmetric band matrix :math:`A`, with the diagonal of the matrix stored in the :math:`\left(m_A+1\right)`\ th row of the array, and the :math:`m_A` superdiagonals within the band stored in the first :math:`m_A` rows of the array. Each column of the matrix is stored in the corresponding column of the array. For example, if :math:`n = 6` and :math:`m_A = 2`, the storage scheme is
.. math::
\begin{array}{cccccc}\text{*}&\text{*}&a_{13}&a_{24}&a_{35}&a_{46}\\\text{*}&a_{12}&a_{23}&a_{34}&a_{45}&a_{56}\\a_{11}&a_{22}&a_{33}&a_{44}&a_{55}&a_{66}\end{array}
Elements in the top left corner of the array need not be set. The matrix elements within the band can be assigned to the correct elements of the array using the following code:
::
for j in range(A.shape[1]):
for i in range(max(0, j+1-ma1), j+1):
a[i-j+ma1-1, j] = A[i, j]
**b** : float, array-like, shape :math:`\left(\textit{mb1}, n\right)`
The elements of the decomposition of matrix :math:`B` as returned by :meth:`real_symm_posdef_fac`.
**Returns**
**a** : float, ndarray, shape :math:`\left(\textit{ma1}, n\right)`
Is overwritten by the corresponding elements of :math:`C`.
**b** : float, ndarray, shape :math:`\left(\textit{mb1}, n\right)`
The elements of :math:`\mathrm{b}` will have been permuted.
.. _f01bv-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\textit{mb1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{ma1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{mb1}\leq \textit{ma1}`.
.. _f01bv-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
:math:`A` is a symmetric band matrix of order :math:`n` and bandwidth :math:`2m_A+1`.
The positive definite symmetric band matrix :math:`B`, of order :math:`n` and bandwidth :math:`2m_B+1`, must have been previously decomposed by :meth:`real_symm_posdef_fac` as :math:`ULDL^\mathrm{T}U^\mathrm{T}`. ``real_symm_posdef_geneig`` applies :math:`U`, :math:`L` and :math:`D` to :math:`A`, :math:`m_A` rows at a time, restoring the band form of :math:`A` at each stage by plane rotations.
The argument :math:`k` defines the change-over point in the decomposition of :math:`B` as used by :meth:`real_symm_posdef_fac` and is also used as a change-over point in the transformations applied by this function.
For maximum efficiency, :math:`k` should be chosen to be the multiple of :math:`m_A` nearest to :math:`n/2`.
The resulting symmetric band matrix :math:`C` is overwritten on :math:`\mathrm{a}`.
The eigenvalues of :math:`C`, and thus of the original problem, may be found using :meth:`lapackeig.dsbtrd <naginterfaces.library.lapackeig.dsbtrd>` and :meth:`lapackeig.dsterf <naginterfaces.library.lapackeig.dsterf>`.
For selected eigenvalues, use :meth:`lapackeig.dsbtrd <naginterfaces.library.lapackeig.dsbtrd>` and :meth:`lapackeig.dstebz <naginterfaces.library.lapackeig.dstebz>`.
.. _f01bv-py2-py-references:
**References**
Crawford, C R, 1973, `Reduction of a band-symmetric generalized eigenvalue problem`, Comm. ACM (16), 41--44
"""
raise NotImplementedError
[docs]def real_gen_matmul(b, c, opt):
r"""
``real_gen_matmul`` returns with the result of the multiplication of two matrices :math:`B` and :math:`C` in the matrix :math:`A`, with the option to overwrite :math:`B` or :math:`C`.
.. _f01ck-py2-py-doc:
For full information please refer to the NAG Library document for f01ck
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01ckf.html
.. _f01ck-py2-py-parameters:
**Parameters**
**b** : float, array-like, shape :math:`\left(n, m\right)`
The :math:`n\times m` matrix :math:`B`.
**c** : float, array-like, shape :math:`\left(m, p\right)`
The :math:`m\times p` matrix :math:`C`.
**opt** : int
The value of :math:`\mathrm{opt}` determines which array is to contain the final result.
:math:`\mathrm{opt} = 1`
:math:`\mathrm{a}` must be distinct from :math:`\mathrm{b}` and :math:`\mathrm{c}` and, on exit, contains the result. :math:`\mathrm{b}` and :math:`\mathrm{c}` need not be distinct in this case.
:math:`\mathrm{opt} = 2`
:math:`\mathrm{b}` must be distinct from :math:`\mathrm{c}` and on exit, contains the result. :math:`\mathrm{a}` is not used in this case and need not be distinct from :math:`\mathrm{b}` or :math:`\mathrm{c}`.
:math:`\mathrm{opt} = 3`
:math:`\mathrm{c}` must be distinct from :math:`\mathrm{b}` and on exit, contains the result. :math:`\mathrm{a}` is not used in this case and need not be distinct from :math:`\mathrm{b}` or :math:`\mathrm{c}`.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, p\right)`
If :math:`\mathrm{opt} = 1`, :math:`\mathrm{a}` contains the result of the matrix multiplication.
**b** : float, ndarray, shape :math:`\left(n, m\right)`
If :math:`\mathrm{opt} = 2`, :math:`\mathrm{b}` contains the result of the multiplication.
**c** : float, ndarray, shape :math:`\left(m, p\right)`
If :math:`\mathrm{opt} = 3`, :math:`\mathrm{c}` contains the result of the multiplication.
.. _f01ck-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`p = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`p\geq 1`.
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 1`.
(`errno` :math:`1`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq 1`.
(`errno` :math:`2`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`p = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{opt} = 2`, :math:`m = p`.
(`errno` :math:`3`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{opt} = 3`, :math:`n = m`.
.. _f01ck-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
The :math:`n\times m` matrix :math:`B` is post-multiplied by the :math:`m\times p` matrix :math:`C`.
If :math:`\mathrm{opt} = 1` the result is formed in the :math:`n\times p` matrix :math:`A`.
If :math:`\mathrm{opt} = 2`, :math:`m` must equal :math:`p`, and the result is written back to :math:`B`.
If :math:`\mathrm{opt} = 3`, :math:`n` must equal :math:`m`, and the result is written back to :math:`C`.
"""
raise NotImplementedError
[docs]def real_gen_trans_inplace(a, m, n):
r"""
``real_gen_trans_inplace`` transposes a rectangular matrix in-situ.
.. _f01cr-py2-py-doc:
For full information please refer to the NAG Library document for f01cr
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01crf.html
.. _f01cr-py2-py-parameters:
**Parameters**
**a** : float, ndarray, shape :math:`\left(\textit{mn}\right)`, modified in place
`On entry`: the elements of the :math:`m\times n` matrix :math:`A`, stored by columns.
`On exit`: the elements of the transpose matrix, also stored by columns.
**m** : int
:math:`m`, the number of rows of the matrix :math:`A`.
**n** : int
:math:`n`, the number of columns of the matrix :math:`A`.
.. _f01cr-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`i < 0`)
A serious internal error has occurred in ``real_gen_trans_inplace``.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{mn} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{mn} = \mathrm{m}\times \mathrm{n}`.
.. _f01cr-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``real_gen_trans_inplace`` requires that the elements of an :math:`m\times n` matrix :math:`A` are stored consecutively by columns in a one-dimensional array.
It reorders the elements so that on exit the array holds the transpose of :math:`A` stored in the same way.
For example, if :math:`m = 4` and :math:`n = 3`, on entry the array must hold:
.. math::
a_{11}\quad \text{ }\quad a_{21}\quad \text{ }\quad a_{31}\quad \text{ }\quad a_{41}\quad \text{ }\quad a_{12}\quad \text{ }\quad a_{22}\quad \text{ }\quad a_{32}\quad \text{ }\quad a_{42}\quad \text{ }\quad a_{13}\quad \text{ }\quad a_{23}\quad \text{ }\quad a_{33}\quad \text{ }\quad a_{43}
and on exit it holds
.. math::
a_{11}\quad \text{ }\quad a_{12}\quad \text{ }\quad a_{13}\quad \text{ }\quad a_{21}\quad \text{ }\quad a_{22}\quad \text{ }\quad a_{23}\quad \text{ }\quad a_{31}\quad \text{ }\quad a_{32}\quad \text{ }\quad a_{33}\quad \text{ }\quad a_{41}\quad \text{ }\quad a_{42}\quad \text{ }\quad a_{43}\text{.}
.. _f01cr-py2-py-references:
**References**
Cate, E G and Twigg, D W, 1977, `Algorithm 513: Analysis of in-situ transposition`, ACM Trans. Math. Software (3), 104--110
"""
raise NotImplementedError
[docs]def real_addsub(transa, transb, m, n, alpha, a, beta, b):
r"""
``real_addsub`` adds two `float` matrices, each one optionally transposed and multiplied by a scalar.
.. _f01ct-py2-py-doc:
For full information please refer to the NAG Library document for f01ct
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01ctf.html
.. _f01ct-py2-py-parameters:
**Parameters**
**transa** : str, length 1
:math:`\mathrm{transa}` and :math:`\mathrm{transb}` must specify whether or not the matrix :math:`A` and the matrix :math:`B`, respectively, are to be transposed before addition.
:math:`\mathrm{transa}` or :math:`\mathrm{transb} = \texttt{'N'}`
The matrix will not be transposed.
:math:`\mathrm{transa}` or :math:`\mathrm{transb} = \texttt{'T'}` or :math:`\texttt{'C'}`
The matrix will be transposed.
**transb** : str, length 1
:math:`\mathrm{transa}` and :math:`\mathrm{transb}` must specify whether or not the matrix :math:`A` and the matrix :math:`B`, respectively, are to be transposed before addition.
:math:`\mathrm{transa}` or :math:`\mathrm{transb} = \texttt{'N'}`
The matrix will not be transposed.
:math:`\mathrm{transa}` or :math:`\mathrm{transb} = \texttt{'T'}` or :math:`\texttt{'C'}`
The matrix will be transposed.
**m** : int
:math:`m`, the number of rows of the matrices :math:`A` and :math:`B` or their transposes. Also the number of rows of the matrix :math:`C`.
**n** : int
:math:`n`, the number of columns of the matrices :math:`A` and :math:`B` or their transposes. Also the number of columns of the matrix :math:`C`.
**alpha** : float
The scalar :math:`\alpha`, by which matrix :math:`A` is multiplied before addition.
**a** : float, array-like, shape :math:`\left(:, :\right)`
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{transa}=\texttt{'N'}`: :math:`\mathrm{m}`; otherwise: :math:`\mathrm{n}`.
Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{transa}=\texttt{'N'}`: :math:`\mathrm{n}`; otherwise: :math:`\mathrm{m}`.
If :math:`\alpha = 0.0`, the elements of array :math:`\mathrm{a}` need not be assigned. If :math:`\alpha \neq 0.0`, then if :math:`\mathrm{transa} = \texttt{'N'}`, the leading :math:`m\times n` part of :math:`\mathrm{a}` must contain the matrix :math:`A`, otherwise the leading :math:`n\times m` part of :math:`\mathrm{a}` must contain the matrix :math:`A`.
**beta** : float
The scalar :math:`\beta`, by which matrix :math:`B` is multiplied before addition.
**b** : float, array-like, shape :math:`\left(:, :\right)`
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{transb}=\texttt{'N'}`: :math:`\mathrm{m}`; otherwise: :math:`\mathrm{n}`.
Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{transb}=\texttt{'N'}`: :math:`\mathrm{n}`; otherwise: :math:`\mathrm{m}`.
If :math:`\beta = 0.0`, the elements of array :math:`\mathrm{b}` need not be assigned. If :math:`\beta \neq 0.0`, then if :math:`\mathrm{transa} = \texttt{'N'}`, the leading :math:`m\times n` part of :math:`\mathrm{b}` must contain the matrix :math:`B`, otherwise the leading :math:`n\times m` part of :math:`\mathrm{b}` must contain the matrix :math:`B`.
**Returns**
**c** : float, ndarray, shape :math:`\left(\mathrm{m}, \mathrm{n}\right)`
The elements of the :math:`m\times n` matrix :math:`C`.
.. _f01ct-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{transb} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{transb} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{transa} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{transa} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m}\geq 0` and :math:`\mathrm{n}\geq 0`.
(`errno` :math:`3`)
On entry, :math:`\textit{lda} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{transa} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\textit{lda}\geq \mathrm{max}\left(1, \mathrm{n}\right)`.
(`errno` :math:`3`)
On entry, :math:`\textit{lda} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{transa} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\textit{lda}\geq \mathrm{max}\left(1, \mathrm{m}\right)`.
(`errno` :math:`4`)
On entry, :math:`\textit{ldb} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{transb} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\textit{ldb}\geq \mathrm{max}\left(1, \mathrm{n}\right)`.
(`errno` :math:`4`)
On entry, :math:`\textit{ldb} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{transb} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\textit{ldb}\geq \mathrm{max}\left(1, \mathrm{m}\right)`.
.. _f01ct-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``real_addsub`` performs one of the operations
:math:`C \mathrel{:=} \alpha A+\beta B`,
:math:`C \mathrel{:=} \alpha A^\mathrm{T}+\beta B`,
:math:`C \mathrel{:=} \alpha A+\beta B^\mathrm{T}` or
:math:`C \mathrel{:=} \alpha A^\mathrm{T}+\beta B^\mathrm{T}`,
where :math:`A`, :math:`B` and :math:`C` are matrices, and :math:`\alpha` and :math:`\beta` are scalars.
For efficiency, the function contains special code for the cases when one or both of :math:`\alpha`, :math:`\beta` is equal to zero, unity or minus unity.
The matrices, or their transposes, must be compatible for addition. :math:`A` and :math:`B` are either :math:`m\times n` or :math:`n\times m` matrices, depending on whether they are to be transposed before addition. :math:`C` is an :math:`m\times n` matrix.
"""
raise NotImplementedError
[docs]def complex_addsub(transa, transb, m, n, alpha, a, beta, b):
r"""
``complex_addsub`` adds two complex matrices, each one optionally transposed and multiplied by a scalar.
.. _f01cw-py2-py-doc:
For full information please refer to the NAG Library document for f01cw
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01cwf.html
.. _f01cw-py2-py-parameters:
**Parameters**
**transa** : str, length 1
:math:`\mathrm{transa}` and :math:`\mathrm{transb}` must specify whether or not the matrix :math:`A` and the matrix :math:`B`, respectively, are to be transposed before addition.
:math:`\mathrm{transa}` or :math:`\mathrm{transb} = \texttt{'N'}`
The matrix will not be transposed.
:math:`\mathrm{transa}` or :math:`\mathrm{transb} = \texttt{'T'}`
The matrix will be transposed.
:math:`\mathrm{transa}` or :math:`\mathrm{transb} = \texttt{'C'}`
The matrix will be transposed and conjugated.
**transb** : str, length 1
:math:`\mathrm{transa}` and :math:`\mathrm{transb}` must specify whether or not the matrix :math:`A` and the matrix :math:`B`, respectively, are to be transposed before addition.
:math:`\mathrm{transa}` or :math:`\mathrm{transb} = \texttt{'N'}`
The matrix will not be transposed.
:math:`\mathrm{transa}` or :math:`\mathrm{transb} = \texttt{'T'}`
The matrix will be transposed.
:math:`\mathrm{transa}` or :math:`\mathrm{transb} = \texttt{'C'}`
The matrix will be transposed and conjugated.
**m** : int
:math:`m`, the number of rows of the matrices :math:`A` and :math:`B` or their transposes. Also the number of rows of the matrix :math:`C`.
**n** : int
:math:`n`, the number of columns of the matrices :math:`A` and :math:`B` or their transposes. Also the number of columns of the matrix :math:`C`.
**alpha** : complex
The scalar :math:`\alpha`, by which matrix :math:`A` is multiplied before addition.
**a** : complex, array-like, shape :math:`\left(:, :\right)`
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{transa}=\texttt{'N'}`: :math:`\mathrm{m}`; otherwise: :math:`\mathrm{n}`.
Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{alpha}\neq 0\text{ and }\mathrm{transa}=\texttt{'N'}`: :math:`\mathrm{n}`; if :math:`\mathrm{alpha}\neq 0\text{ and }\mathrm{transa}\text{ in } (\texttt{'T'}, \texttt{'C'})`: :math:`\mathrm{m}`; if :math:`\mathrm{alpha}=0`: :math:`1`; otherwise: :math:`0`.
The matrix :math:`A`. If :math:`\alpha = 0`, the array :math:`\mathrm{a}` is not referenced.
**beta** : complex
The scalar :math:`\beta`, by which matrix :math:`B` is multiplied before addition.
**b** : complex, array-like, shape :math:`\left(:, :\right)`
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{transb}=\texttt{'N'}`: :math:`\mathrm{m}`; otherwise: :math:`\mathrm{n}`.
Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{beta}\neq 0\text{ and }\mathrm{transb}=\texttt{'N'}`: :math:`\mathrm{n}`; if :math:`\mathrm{beta}\neq 0\text{ and }\mathrm{transb}\text{ in } (\texttt{'T'}, \texttt{'C'})`: :math:`\mathrm{m}`; if :math:`\mathrm{beta}=0`: :math:`1`; otherwise: :math:`0`.
The matrix :math:`B`. If :math:`\beta = 0`, the array :math:`\mathrm{b}` is not referenced.
**Returns**
**c** : complex, ndarray, shape :math:`\left(\mathrm{m}, \mathrm{n}\right)`
The elements of the :math:`m\times n` matrix :math:`C`.
.. _f01cw-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{transb} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{transb} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{transa} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{transa} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m}\geq 0` and :math:`\mathrm{n}\geq 0`.
(`errno` :math:`3`)
On entry, :math:`\textit{lda} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{transa} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\textit{lda}\geq \mathrm{max}\left(1, \mathrm{n}\right)`.
(`errno` :math:`3`)
On entry, :math:`\textit{lda} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{transa} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\textit{lda}\geq \mathrm{max}\left(1, \mathrm{m}\right)`.
(`errno` :math:`4`)
On entry, :math:`\textit{ldb} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{transb} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\textit{ldb}\geq \mathrm{max}\left(1, \mathrm{n}\right)`.
(`errno` :math:`4`)
On entry, :math:`\textit{ldb} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{transb} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\textit{ldb}\geq \mathrm{max}\left(1, \mathrm{m}\right)`.
.. _f01cw-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``complex_addsub`` performs one of the operations
:math:`C \mathrel{:=} \alpha A+\beta B`,
:math:`C \mathrel{:=} \alpha A^\mathrm{T}+\beta B`,
:math:`C \mathrel{:=} \alpha A^\mathrm{H}+\beta B`,
:math:`C \mathrel{:=} \alpha A+\beta B^\mathrm{T}`,
:math:`C \mathrel{:=} \alpha A^\mathrm{T}+\beta B^\mathrm{T}`,
:math:`C \mathrel{:=} \alpha A^\mathrm{H}+\beta B^\mathrm{T}`,
:math:`C \mathrel{:=} \alpha A+\beta B^\mathrm{H}`,
:math:`C \mathrel{:=} \alpha A^\mathrm{T}+\beta B^\mathrm{H}` or
:math:`C \mathrel{:=} \alpha A^\mathrm{H}+\beta B^\mathrm{H}`,
where :math:`A`, :math:`B` and :math:`C` are matrices, :math:`\alpha` and :math:`\beta` are scalars, :math:`T` denotes transposition and :math:`H` denotes conjugate transposition.
For efficiency, the function contains special code for the cases when one or both of :math:`\alpha`, :math:`\beta` is equal to zero, unity or minus unity.
The matrices, or their transposes, must be compatible for addition. :math:`A` and :math:`B` are either :math:`m\times n` or :math:`n\times m` matrices, depending on whether they are to be transposed before addition. :math:`C` is an :math:`m\times n` matrix.
"""
raise NotImplementedError
[docs]def real_tri_matmul(uplo, transa, transb, alpha, a, b, beta, c=None):
r"""
``real_tri_matmul`` performs one of the matrix-matrix operations
.. math::
\begin{array}{ll}C←\alpha AB+\beta C\text{,}&C←\alpha A^\mathrm{T}B+\beta C\text{,}\\C←\alpha AB^\mathrm{T}+\beta C\quad \text{ or}&C←\alpha A^\mathrm{T}B^\mathrm{T}+\beta C\text{,}\end{array}
where :math:`A`, :math:`B` and :math:`C` are real triangular matrices, and :math:`\alpha` and :math:`\beta` are real scalars.
.. _f01df-py2-py-doc:
For full information please refer to the NAG Library document for f01df
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01dff.html
.. _f01df-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Specifies whether :math:`C` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`C` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`C` is lower triangular.
**transa** : str, length 1
Specifies whether the operation involves :math:`A` or :math:`A^\mathrm{T}`.
:math:`\mathrm{transa} = \texttt{'N'}`
The operation involves :math:`A`.
:math:`\mathrm{transa} = \texttt{'T'}` or :math:`\texttt{'C'}`
The operation involves :math:`A^\mathrm{T}`.
**transb** : str, length 1
Specifies whether the operation involves :math:`B` or :math:`B^\mathrm{T}`.
:math:`\mathrm{transb} = \texttt{'N'}`
The operation involves :math:`B`.
:math:`\mathrm{transb} = \texttt{'T'}` or :math:`\texttt{'C'}`
The operation involves :math:`B^\mathrm{T}`.
**alpha** : float
The scalar :math:`\alpha`.
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` triangular matrix :math:`A`.
**b** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` triangular matrix :math:`B`.
**beta** : float
The scalar :math:`\beta`.
**c** : None or float, array-like, shape :math:`\left(n, n\right)`, optional
The :math:`n\times n` matrix :math:`C`.
If :math:`\mathrm{beta} = 0`, :math:`\mathrm{c}` need not be set and may be **None**.
**Returns**
**c** : float, ndarray, shape :math:`\left(n, n\right)`
The triangular part of :math:`C`, as specified by :math:`\mathrm{uplo}`, is updated.
.. _f01df-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{uplo} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{transa} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{transa} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{transb} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{transb} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`4`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
.. _f01df-py2-py-notes:
**Notes**
``real_tri_matmul`` computes the triangular matrix product :math:`C = \alpha \mathrm{op}\left(A\right)\mathrm{op}\left(B\right)+\beta C`, where :math:`\mathrm{op}\left(A\right)`, :math:`\mathrm{op}\left(B\right)`, and :math:`C` are all upper triangular or all lower triangular matrices, and where :math:`\mathrm{op}\left(A\right)` is either :math:`A` or :math:`A^\mathrm{T}`.
"""
raise NotImplementedError
[docs]def real_tri_matmul_inplace(side, uplo, transa, alpha, a, b):
r"""
``real_tri_matmul_inplace`` performs one of the matrix-matrix operations
.. math::
\begin{array}{ll}B←\alpha AB\text{,}&B←\alpha A^\mathrm{T}B\text{,}\\B←\alpha BA\quad \text{ or}&B←\alpha BA^\mathrm{T}\text{,}\end{array}
where :math:`A` and :math:`B` are real triangular matrices, and :math:`\alpha` is a real scalar.
.. _f01dg-py2-py-doc:
For full information please refer to the NAG Library document for f01dg
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01dgf.html
.. _f01dg-py2-py-parameters:
**Parameters**
**side** : str, length 1
Specifies whether :math:`B` is operated on from the left or the right.
:math:`\mathrm{side} = \texttt{'L'}`
:math:`B` is pre-multiplied from the left.
:math:`\mathrm{side} = \texttt{'R'}`
:math:`B` is post-multiplied from the right.
**uplo** : str, length 1
Specifies whether :math:`A` and :math:`B` are upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` and :math:`B` are upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` and :math:`B` are lower triangular.
**transa** : str, length 1
Specifies whether the operation involves :math:`A` or :math:`A^\mathrm{T}`.
:math:`\mathrm{transa} = \texttt{'N'}`
The operation involves :math:`A`.
:math:`\mathrm{transa} = \texttt{'T'}` or :math:`\texttt{'C'}`
The operation involves :math:`A^\mathrm{T}`.
**alpha** : float
The scalar :math:`\alpha`.
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` triangular matrix :math:`A`.
**b** : float, ndarray, shape :math:`\left(n, n\right)`, modified in place
`On entry`: the :math:`n\times n` triangular matrix :math:`B`.
If :math:`\mathrm{alpha} = 0`, :math:`\mathrm{b}` need not be set.
`On exit`: :math:`B` is overwritten.
.. _f01dg-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{side} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{side} = \texttt{'L'}` or :math:`\texttt{'R'}`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{uplo} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{transa} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{transa} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`4`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
.. _f01dg-py2-py-notes:
**Notes**
``real_tri_matmul_inplace`` computes the matrix product :math:`B = \alpha AB` or :math:`B = \alpha BA` for two upper triangular or two lower triangular matrices.
The storage method for matrices :math:`A` and :math:`B` must match (e.g., :math:`A` and :math:`B` must both be upper triangular or lower triangular matrices).
When the transpose of the input matrix :math:`A` is used during computation, the solution matrix :math:`B` is a general matrix.
Otherwise, the solution matrix :math:`B` is a triangular matrix with the storage method identified by the input argument :math:`\mathrm{uplo}`.
"""
raise NotImplementedError
[docs]def complex_tri_matmul(uplo, transa, transb, alpha, a, b, beta, c=None):
r"""
``complex_tri_matmul`` performs one of the matrix-matrix operations
.. math::
\begin{array}{lll}C←\alpha AB+\beta C\text{,}&C←\alpha A^\mathrm{T}B+\beta C\text{,}&C←\alpha A^\mathrm{H}B+\beta C\text{,}\\C←\alpha AB^\mathrm{T}+\beta C\text{,}&C←\alpha A^\mathrm{T}B^\mathrm{T}+\beta C\text{,}&C←\alpha A^\mathrm{H}B^\mathrm{T}+\beta C\text{,}\\C←\alpha AB^\mathrm{H}+\beta C\text{,}&C←\alpha A^\mathrm{T}B^\mathrm{H}+\beta C\quad \text{ or}&C←\alpha A^\mathrm{H}B^\mathrm{H}+\beta C\text{,}\end{array}
where :math:`A`, :math:`B`, and :math:`C` are complex triangular matrices, and :math:`\alpha` and :math:`\beta` are complex scalars.
.. _f01dt-py2-py-doc:
For full information please refer to the NAG Library document for f01dt
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01dtf.html
.. _f01dt-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Specifies whether :math:`C` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`C` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`C` is lower triangular.
**transa** : str, length 1
Specifies whether the operation involves :math:`A`, :math:`A^\mathrm{T}` or :math:`A^\mathrm{H}`.
:math:`\mathrm{transa} = \texttt{'N'}`
The operation involves :math:`A`.
:math:`\mathrm{transa} = \texttt{'T'}`
The operation involves :math:`A^\mathrm{T}`.
:math:`\mathrm{transa} = \texttt{'C'}`
The operation involves :math:`A^\mathrm{H}`.
**transb** : str, length 1
Specifies whether the operation involves :math:`B`, :math:`B^\mathrm{T}` or :math:`B^\mathrm{H}`.
:math:`\mathrm{transb} = \texttt{'N'}`
The operation involves :math:`B`.
:math:`\mathrm{transb} = \texttt{'T'}`
The operation involves :math:`B^\mathrm{T}`.
:math:`\mathrm{transb} = \texttt{'C'}`
The operation involves :math:`B^\mathrm{H}`.
**alpha** : complex
The scalar :math:`\alpha`.
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` triangular matrix :math:`A`.
**b** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` triangular matrix :math:`B`.
**beta** : complex
The scalar :math:`\beta`.
**c** : None or complex, array-like, shape :math:`\left(n, n\right)`, optional
The :math:`n\times n` matrix :math:`C`.
If :math:`\mathrm{beta} = 0`, :math:`\mathrm{c}` need not be set and may be **None**.
**Returns**
**c** : complex, ndarray, shape :math:`\left(n, n\right)`
The triangular part of :math:`C`, as specified by :math:`\mathrm{uplo}`, is updated.
.. _f01dt-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{uplo} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{transa} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{transa} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{transb} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{transb} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`4`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
.. _f01dt-py2-py-notes:
**Notes**
``complex_tri_matmul`` computes the triangular matrix product :math:`C = \alpha \mathrm{op}\left(A\right)\mathrm{op}\left(B\right)+\beta C`, where :math:`\mathrm{op}\left(A\right)`, :math:`\mathrm{op}\left(B\right)`, and :math:`C` are all upper triangular or all lower triangular matrices, and where :math:`\mathrm{op}\left(A\right)` is either :math:`A`, :math:`A^\mathrm{T}`, or :math:`A^\mathrm{H}`.
"""
raise NotImplementedError
[docs]def complex_tri_matmul_inplace(side, uplo, transa, alpha, a, b):
r"""
``complex_tri_matmul_inplace`` performs one of the matrix-matrix operations
.. math::
\begin{array}{lll}B←\alpha AB\text{,}&B←\alpha A^\mathrm{T}B\text{,}&B←\alpha A^\mathrm{H}B\text{,}\\B←\alpha BA\text{,}&B←\alpha BA^\mathrm{T}\quad \text{ or}&B←\alpha BA^\mathrm{H}\text{,}\end{array}
where :math:`A` and :math:`B` are complex triangular matrices, and :math:`\alpha` is a complex scalar.
.. _f01du-py2-py-doc:
For full information please refer to the NAG Library document for f01du
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01duf.html
.. _f01du-py2-py-parameters:
**Parameters**
**side** : str, length 1
Specifies whether :math:`B` is operated on from the left or the right.
:math:`\mathrm{side} = \texttt{'L'}`
:math:`B` is pre-multiplied from the left.
:math:`\mathrm{side} = \texttt{'R'}`
:math:`B` is post-multiplied from the right.
**uplo** : str, length 1
Specifies whether :math:`A` and :math:`B` are upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` and :math:`B` are upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` and :math:`B` are lower triangular.
**transa** : str, length 1
Specifies whether the operation involves :math:`A`, :math:`A^\mathrm{T}` or :math:`A^\mathrm{H}`.
:math:`\mathrm{transa} = \texttt{'N'}`
The operation involves :math:`A`.
:math:`\mathrm{transa} = \texttt{'T'}`
The operation involves :math:`A^\mathrm{T}`.
:math:`\mathrm{transa} = \texttt{'C'}`
The operation involves :math:`A^\mathrm{H}`.
**alpha** : complex
The scalar :math:`\alpha`.
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` triangular matrix :math:`A`.
**b** : complex, ndarray, shape :math:`\left(n, n\right)`, modified in place
`On entry`: the :math:`n\times n` triangular matrix :math:`B`.
If :math:`\mathrm{alpha} = 0`, :math:`\mathrm{b}` need not be set.
`On exit`: :math:`B` is overwritten.
.. _f01du-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{side} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{side} = \texttt{'L'}` or :math:`\texttt{'R'}`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{uplo} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{transa} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{transa} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`4`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
.. _f01du-py2-py-notes:
**Notes**
``complex_tri_matmul_inplace`` computes the matrix product :math:`B = \alpha AB` or :math:`B = \alpha BA` for two upper triangular or two lower triangular matrices.
The storage method for matrices :math:`A` and :math:`B` must match (e.g., :math:`A` and :math:`B` must both be upper triangular or lower triangular matrices).
When the transpose or the conjugate transpose of the input matrix :math:`A` is used during computation, the solution matrix :math:`B` is a general matrix.
Otherwise, the solution matrix :math:`B` is a triangular matrix with the storage method identified by the input parameter :math:`\mathrm{uplo}`.
"""
raise NotImplementedError
[docs]def real_gen_matrix_exp(a):
r"""
``real_gen_matrix_exp`` computes the matrix exponential, :math:`e^A`, of a real :math:`n\times n` matrix :math:`A`.
.. _f01ec-py2-py-doc:
For full information please refer to the NAG Library document for f01ec
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01ecf.html
.. _f01ec-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix exponential :math:`e^A`.
.. _f01ec-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`1`)
The linear equations to be solved for the Padé approximant are singular; it is likely that this function has been called incorrectly.
(`errno` :math:`2`)
The linear equations to be solved are nearly singular and the Padé approximant probably has no correct figures; it is likely that this function has been called incorrectly.
(`errno` :math:`4`)
An unexpected internal error has occurred. Please contact `NAG <https://www.nag.com>`__.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`3`)
The arithmetic precision is higher than that used for the Padé approximant computed matrix exponential.
.. _f01ec-py2-py-notes:
**Notes**
:math:`e^A` is computed using a Padé approximant and the scaling and squaring method described in Al--Mohy and Higham (2009).
.. _f01ec-py2-py-references:
**References**
Al--Mohy, A H and Higham, N J, 2009, `A new scaling and squaring algorithm for the matrix exponential`, SIAM J. Matrix Anal. (31(3)), 970--989
Higham, N J, 2005, `The scaling and squaring method for the matrix exponential revisited`, SIAM J. Matrix Anal. Appl. (26(4)), 1179--1193
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
Moler, C B and Van Loan, C F, 2003, `Nineteen dubious ways to compute the exponential of a matrix, twenty-five years later`, SIAM Rev. (45), 3--49
"""
raise NotImplementedError
[docs]def real_symm_matrix_exp(uplo, a):
r"""
``real_symm_matrix_exp`` computes the matrix exponential, :math:`e^A`, of a real symmetric :math:`n\times n` matrix :math:`A`.
.. _f01ed-py2-py-doc:
For full information please refer to the NAG Library document for f01ed
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01edf.html
.. _f01ed-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Indicates whether the upper or lower triangular part of :math:`A` is stored.
:math:`\mathrm{uplo} = \texttt{'U'}`
The upper triangular part of :math:`A` is stored.
:math:`\mathrm{uplo} = \texttt{'L'}`
The lower triangular part of :math:`A` is stored.
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` symmetric matrix :math:`A`.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
If no exception or warning is raised, the upper or lower triangular part of the :math:`n\times n` matrix exponential, :math:`e^A`.
.. _f01ed-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-3`)
An internal error occurred when computing the spectral factorization. Please contact `NAG <https://www.nag.com>`__.
(`errno` :math:`-2`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-1`)
On entry, :math:`\mathrm{uplo} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{uplo} = \texttt{'L'}` or :math:`\texttt{'U'}`.
(`errno` :math:`i > 0`)
The computation of the spectral factorization failed to converge.
.. _f01ed-py2-py-notes:
**Notes**
:math:`e^A` is computed using a spectral factorization of :math:`A`
.. math::
A = QDQ^\mathrm{T}\text{,}
where :math:`D` is the diagonal matrix whose diagonal elements, :math:`d_i`, are the eigenvalues of :math:`A`, and :math:`Q` is an orthogonal matrix whose columns are the eigenvectors of :math:`A`. :math:`e^A` is then given by
.. math::
e^A = Qe^DQ^\mathrm{T}\text{,}
where :math:`e^D` is the diagonal matrix whose :math:`i`\ th diagonal element is :math:`e^{{d_i}}`.
See for example Section 4.5 of Higham (2008).
.. _f01ed-py2-py-references:
**References**
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
Moler, C B and Van Loan, C F, 2003, `Nineteen dubious ways to compute the exponential of a matrix, twenty-five years later`, SIAM Rev. (45), 3--49
"""
raise NotImplementedError
[docs]def real_symm_matrix_fun(uplo, a, f, data=None):
r"""
``real_symm_matrix_fun`` computes the matrix function, :math:`f\left(A\right)`, of a real symmetric :math:`n\times n` matrix :math:`A`. :math:`f\left(A\right)` must also be a real symmetric matrix.
.. _f01ef-py2-py-doc:
For full information please refer to the NAG Library document for f01ef
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01eff.html
.. _f01ef-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of the matrix :math:`A` is stored.
If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of the matrix :math:`A` is stored.
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` symmetric matrix :math:`A`.
**f** : callable fx = f(x, data=None)
The function :math:`\mathrm{f}` evaluates :math:`f\left(z_i\right)` at a number of points :math:`z_i`.
**Parameters**
**x** : float, ndarray, shape :math:`\left(n\right)`
The :math:`n` points :math:`x_1,x_2,\ldots,x_n` at which the function :math:`f` is to be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**fx** : float, array-like, shape :math:`\left(n\right)`
The :math:`n` function values. :math:`\mathrm{fx}[\textit{i}-1]` should return the value :math:`f\left(x_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n`.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
If no exception or warning is raised, the upper or lower triangular part of the :math:`n\times n` matrix function, :math:`f\left(A\right)`.
.. _f01ef-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-3`)
An internal error occurred when computing the spectral factorization. Please contact `NAG <https://www.nag.com>`__.
(`errno` :math:`-2`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-1`)
On entry, :math:`\mathrm{uplo} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{uplo} = \texttt{'L'}` or :math:`\texttt{'U'}`.
(`errno` :math:`i > 0`)
The computation of the spectral factorization failed to converge.
**Warns**
**NagCallbackTerminateWarning**
(`errno` :math:`-6`)
Termination requested in :math:`\mathrm{f}`.
.. _f01ef-py2-py-notes:
**Notes**
:math:`f\left(A\right)` is computed using a spectral factorization of :math:`A`
.. math::
A = QDQ^\mathrm{T}\text{,}
where :math:`D` is the diagonal matrix whose diagonal elements, :math:`d_i`, are the eigenvalues of :math:`A`, and :math:`Q` is an orthogonal matrix whose columns are the eigenvectors of :math:`A`. :math:`f\left(A\right)` is then given by
.. math::
f\left(A\right) = Qf\left(D\right)Q^\mathrm{T}\text{,}
where :math:`f\left(D\right)` is the diagonal matrix whose :math:`i`\ th diagonal element is :math:`f\left(d_i\right)`.
See for example Section 4.5 of Higham (2008). :math:`f\left(d_i\right)` is assumed to be real.
.. _f01ef-py2-py-references:
**References**
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def real_gen_matrix_log(a):
r"""
``real_gen_matrix_log`` computes the principal matrix logarithm, :math:`\log\left(A\right)`, of a real :math:`n\times n` matrix :math:`A`, with no eigenvalues on the closed negative real line.
.. _f01ej-py2-py-doc:
For full information please refer to the NAG Library document for f01ej
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01ejf.html
.. _f01ej-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` principal matrix logarithm, :math:`\log\left(A\right)`.
**imnorm** : float
If the function has given a reliable answer then :math:`\mathrm{imnorm} = 0.0`. If :math:`\mathrm{imnorm}` differs from :math:`0.0` by more than unit roundoff (as returned by :meth:`machine.precision <naginterfaces.library.machine.precision>`) then the computed matrix logarithm is unreliable.
.. _f01ej-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`1`)
:math:`A` is singular so the logarithm cannot be computed.
(`errno` :math:`2`)
:math:`A` was found to have eigenvalues on the negative real line. The principal logarithm is not defined in this case. :meth:`complex_gen_matrix_log` can be used to find a complex non-principal logarithm.
(`errno` :math:`4`)
An unexpected internal error occurred. Please contact `NAG <https://www.nag.com>`__.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`3`)
The arithmetic precision is higher than that used for the Padé approximant computed matrix logarithm.
.. _f01ej-py2-py-notes:
**Notes**
Any nonsingular matrix :math:`A` has infinitely many logarithms.
For a matrix with no eigenvalues on the closed negative real line, the principal logarithm is the unique logarithm whose spectrum lies in the strip :math:`\left\{{z:{-\pi } < \mathrm{Im}\left({\left(z\right) < \pi }\right)}\right\}`.
:math:`\log\left(A\right)` is computed using the inverse scaling and squaring algorithm for the matrix logarithm described in Al--Mohy and Higham (2011), adapted to real matrices by Al--Mohy `et al.` (2012).
.. _f01ej-py2-py-references:
**References**
Al--Mohy, A H and Higham, N J, 2011, `Improved inverse scaling and squaring algorithms for the matrix logarithm`, SIAM J. Sci. Comput. (34(4)), C152--C169
Al--Mohy, A H, Higham, N J and Relton, S D, 2012, `Computing the Fréchet derivative of the matrix logarithm and estimating the condition number`, SIAM J. Sci. Comput. (35(4)), C394--C410
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def real_gen_matrix_fun_std(fun, a):
r"""
``real_gen_matrix_fun_std`` computes the matrix exponential, sine, cosine, sinh or cosh, of a real :math:`n\times n` matrix :math:`A` using the Schur--Parlett algorithm.
.. _f01ek-py2-py-doc:
For full information please refer to the NAG Library document for f01ek
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01ekf.html
.. _f01ek-py2-py-parameters:
**Parameters**
**fun** : str
Indicates which matrix function will be computed.
:math:`\mathrm{fun} = \text{‘EXP'}`
The matrix exponential, :math:`e^A`, will be computed.
:math:`\mathrm{fun} = \text{‘SIN'}`
The matrix sine, :math:`\sin\left(A\right)`, will be computed.
:math:`\mathrm{fun} = \text{‘COS'}`
The matrix cosine, :math:`\cos\left(A\right)`, will be computed.
:math:`\mathrm{fun} = \text{‘SINH'}`
The hyperbolic matrix sine, :math:`\sinh\left(A\right)`, will be computed.
:math:`\mathrm{fun} = \text{‘COSH'}`
The hyperbolic matrix cosine, :math:`\cosh\left(A\right)`, will be computed.
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix, :math:`f\left(A\right)`.
**imnorm** : float
If :math:`A` has complex eigenvalues, ``real_gen_matrix_fun_std`` will use complex arithmetic to compute the matrix function. The imaginary part is discarded at the end of the computation, because it will theoretically vanish. :math:`\mathrm{imnorm}` contains the :math:`1`-norm of the imaginary part, which should be used to check that the routine has given a reliable answer.
If :math:`A` has real eigenvalues, ``real_gen_matrix_fun_std`` uses real arithmetic and :math:`\mathrm{imnorm} = 0`.
.. _f01ek-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-2`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-1`)
Input argument :math:`\mathrm{fun}` is invalid.
(`errno` :math:`1`)
A Taylor series failed to converge.
(`errno` :math:`2`)
An unexpected internal error occurred when evaluating the function at a point. Please contact `NAG <https://www.nag.com>`__.
(`errno` :math:`3`)
There was an error whilst reordering the Schur form of :math:`A`.
**Note:** this failure should not occur and suggests that the function has been called incorrectly.
(`errno` :math:`4`)
The function was unable to compute the Schur decomposition of :math:`A`.
**Note:** this failure should not occur and suggests that the function has been called incorrectly.
(`errno` :math:`5`)
An unexpected internal error occurred. Please contact `NAG <https://www.nag.com>`__.
(`errno` :math:`6`)
The linear equations to be solved are nearly singular and the Padé approximant used to compute the exponential may have no correct figures.
**Note:** this failure should not occur and suggests that the function has been called incorrectly.
.. _f01ek-py2-py-notes:
**Notes**
:math:`f\left(A\right)`, where :math:`f` is either the exponential, sine, cosine, sinh or cosh, is computed using the Schur--Parlett algorithm described in Higham (2008) and Davies and Higham (2003).
.. _f01ek-py2-py-references:
**References**
Davies, P I and Higham, N J, 2003, `A Schur--Parlett algorithm for computing matrix functions`, SIAM J. Matrix Anal. Appl. (25(2)), 464--485
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def real_gen_matrix_fun_num(a, f, data=None):
r"""
``real_gen_matrix_fun_num`` computes the matrix function, :math:`f\left(A\right)`, of a real :math:`n\times n` matrix :math:`A`.
Numerical differentiation is used to evaluate the derivatives of :math:`f` when they are required.
.. _f01el-py2-py-doc:
For full information please refer to the NAG Library document for f01el
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01elf.html
.. _f01el-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**f** : callable fz = f(z, data=None)
The function :math:`\mathrm{f}` evaluates :math:`f\left(z_i\right)` at a number of points :math:`z_i`.
**Parameters**
**z** : complex, ndarray, shape :math:`\left(\textit{nz}\right)`
The :math:`n_z` points :math:`z_1,z_2,\ldots,z_{n_z}` at which the function :math:`f` is to be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**fz** : complex, array-like, shape :math:`\left(\textit{nz}\right)`
The :math:`n_z` function values. :math:`\mathrm{fz}[\textit{i}-1]` should return the value :math:`f\left(z_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n_z`. If :math:`z_i` lies on the real line, then so must :math:`f\left(z_i\right)`.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix, :math:`f\left(A\right)`.
**imnorm** : float
If :math:`A` has complex eigenvalues, ``real_gen_matrix_fun_num`` will use complex arithmetic to compute :math:`f\left(A\right)`. The imaginary part is discarded at the end of the computation, because it will theoretically vanish. :math:`\mathrm{imnorm}` contains the :math:`1`-norm of the imaginary part, which should be used to check that the routine has given a reliable answer.
If :math:`\mathrm{a}` has real eigenvalues, ``real_gen_matrix_fun_num`` uses real arithmetic and :math:`\mathrm{imnorm} = 0`.
.. _f01el-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`1`)
A Taylor series failed to converge after :math:`40` terms. Further Taylor series coefficients can no longer reliably be obtained by numerical differentiation.
(`errno` :math:`3`)
There was an error whilst reordering the Schur form of :math:`A`.
**Note:** this failure should not occur and suggests that the function has been called incorrectly.
(`errno` :math:`4`)
The function was unable to compute the Schur decomposition of :math:`A`.
**Note:** this failure should not occur and suggests that the function has been called incorrectly.
(`errno` :math:`5`)
An unexpected internal error occurred. Please contact `NAG <https://www.nag.com>`__.
**Warns**
**NagCallbackTerminateWarning**
(`errno` :math:`2`)
Termination requested in :math:`\mathrm{f}`.
.. _f01el-py2-py-notes:
**Notes**
:math:`f\left(A\right)` is computed using the Schur--Parlett algorithm described in Higham (2008) and Davies and Higham (2003).
The coefficients of the Taylor series used in the algorithm are evaluated using the numerical differentiation algorithm of Lyness and Moler (1967).
The scalar function :math:`f` is supplied via function :math:`\mathrm{f}` which evaluates :math:`f\left(z_i\right)` at a number of points :math:`z_i`.
.. _f01el-py2-py-references:
**References**
Davies, P I and Higham, N J, 2003, `A Schur--Parlett algorithm for computing matrix functions`, SIAM J. Matrix Anal. Appl. (25(2)), 464--485
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
Lyness, J N and Moler, C B, 1967, `Numerical differentiation of analytic functions`, SIAM J. Numer. Anal. (4(2)), 202--210
"""
raise NotImplementedError
[docs]def real_gen_matrix_fun_usd(a, f, data=None):
r"""
``real_gen_matrix_fun_usd`` computes the matrix function, :math:`f\left(A\right)`, of a real :math:`n\times n` matrix :math:`A`, using analytical derivatives of :math:`f` you have supplied.
.. _f01em-py2-py-doc:
For full information please refer to the NAG Library document for f01em
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01emf.html
.. _f01em-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**f** : callable fz = f(m, z, data=None)
Given an integer :math:`m`, the function :math:`\mathrm{f}` evaluates :math:`f^{\left(m\right)}\left(z_i\right)` at a number of points :math:`z_i`.
**Parameters**
**m** : int
The order, :math:`m`, of the derivative required.
If :math:`\mathrm{m} = 0`, :math:`f\left(z_i\right)` should be returned.
For :math:`\mathrm{m} > 0`, :math:`f^{\left(m\right)}\left(z_i\right)` should be returned.
**z** : complex, ndarray, shape :math:`\left(\textit{nz}\right)`
The :math:`n_z` points :math:`z_1,z_2,\ldots,z_{n_z}` at which the function :math:`f` is to be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**fz** : complex, array-like, shape :math:`\left(\textit{nz}\right)`
The :math:`n_z` function or derivative values. :math:`\mathrm{fz}[\textit{i}-1]` should return the value :math:`f^{\left(m\right)}\left(z_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n_z`. If :math:`z_i` lies on the real line, then so must :math:`f^{\left(m\right)}\left(z_i\right)`.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix, :math:`f\left(A\right)`.
**imnorm** : float
If :math:`A` has complex eigenvalues, ``real_gen_matrix_fun_usd`` will use complex arithmetic to compute :math:`f\left(A\right)`. The imaginary part is discarded at the end of the computation, because it will theoretically vanish. :math:`\mathrm{imnorm}` contains the :math:`1`-norm of the imaginary part, which should be used to check that the function has given a reliable answer.
If :math:`A` has real eigenvalues, ``real_gen_matrix_fun_usd`` uses real arithmetic and :math:`\mathrm{imnorm} = 0`.
.. _f01em-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`1`)
A Taylor series failed to converge.
(`errno` :math:`3`)
There was an error whilst reordering the Schur form of :math:`A`.
**Note:** this failure should not occur and suggests that the function has been called incorrectly.
(`errno` :math:`4`)
The routine was unable to compute the Schur decomposition of :math:`A`.
**Note:** this failure should not occur and suggests that the function has been called incorrectly.
(`errno` :math:`5`)
An unexpected internal error occurred. Please contact `NAG <https://www.nag.com>`__.
**Warns**
**NagCallbackTerminateWarning**
(`errno` :math:`2`)
Termination requested in :math:`\mathrm{f}`.
.. _f01em-py2-py-notes:
**Notes**
:math:`f\left(A\right)` is computed using the Schur--Parlett algorithm described in Higham (2008) and Davies and Higham (2003).
The scalar function :math:`f`, and the derivatives of :math:`f`, are returned by the function :math:`\mathrm{f}` which, given an integer :math:`m`, should evaluate :math:`f^{\left(m\right)}\left(z_{\textit{i}}\right)` at a number of (generally complex) points :math:`z_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n_z`.
For any :math:`z` on the real line, :math:`f\left(z\right)` must also be real. ``real_gen_matrix_fun_usd`` is, therefore, appropriate for functions that can be evaluated on the complex plane and whose derivatives, of arbitrary order, can also be evaluated on the complex plane.
.. _f01em-py2-py-references:
**References**
Davies, P I and Higham, N J, 2003, `A Schur--Parlett algorithm for computing matrix functions`, SIAM J. Matrix Anal. Appl. (25(2)), 464--485
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
See Also
--------
:meth:`naginterfaces.library.examples.matop.real_gen_matrix_fun_usd_ex.main`
"""
raise NotImplementedError
[docs]def real_gen_matrix_sqrt(a):
r"""
``real_gen_matrix_sqrt`` computes the principal matrix square root, :math:`A^{{1/2}}`, of a real :math:`n\times n` matrix :math:`A`.
.. _f01en-py2-py-doc:
For full information please refer to the NAG Library document for f01en
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01enf.html
.. _f01en-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
Contains, if no exception or warning is raised, the :math:`n\times n` principal matrix square root, :math:`A^{{1/2}}`. Alternatively, if :math:`\mathrm{errno}` = 1, contains an :math:`n\times n` non-principal square root of :math:`A`.
.. _f01en-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`2`)
:math:`A` has a defective vanishing eigenvalue. The square root cannot be found in this case.
(`errno` :math:`3`)
:math:`A` has a negative real eigenvalue. The principal square root is not defined. :meth:`complex_gen_matrix_sqrt` can be used to return a complex, non-principal square root.
(`errno` :math:`4`)
An internal error occurred. It is likely that the function was called incorrectly.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
:math:`A` has a semisimple vanishing eigenvalue. A non-principal square root is returned.
.. _f01en-py2-py-notes:
**Notes**
A square root of a matrix :math:`A` is a solution :math:`X` to the equation :math:`X^2 = A`.
A nonsingular matrix has multiple square roots.
For a matrix with no eigenvalues on the closed negative real line, the principal square root, denoted by :math:`A^{{1/2}}`, is the unique square root whose eigenvalues lie in the open right half-plane.
:math:`A^{{1/2}}` is computed using the algorithm described in Higham (1987).
This is a real arithmetic version of the algorithm of Björck and Hammarling (1983).
In addition a blocking scheme described in Deadman `et al.` (2013) is used.
.. _f01en-py2-py-references:
**References**
Björck, Å and Hammarling, S, 1983, `A Schur method for the square root of a matrix`, Linear Algebra Appl. (52/53), 127--140
Deadman, E, Higham, N J and Ralha, R, 2013, `Blocked Schur Algorithms for Computing the Matrix Square Root`, `Applied Parallel and Scientific Computing: 11th International Conference, (PARA 2012, Helsinki, Finland)`, P. Manninen and P. Öster, Eds, Lecture Notes in Computer Science (7782), 171--181, Springer--Verlag
Higham, N J, 1987, `Computing real square roots of a real matrix`, Linear Algebra Appl. (88/89), 405--430
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def real_tri_matrix_sqrt(a):
r"""
``real_tri_matrix_sqrt`` computes the principal matrix square root, :math:`A^{{1/2}}`, of a real upper quasi-triangular :math:`n\times n` matrix :math:`A`.
.. _f01ep-py2-py-doc:
For full information please refer to the NAG Library document for f01ep
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01epf.html
.. _f01ep-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` upper quasi-triangular matrix :math:`A`.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` principal matrix square root :math:`A^{{1/2}}`.
.. _f01ep-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`1`)
:math:`A` has negative or vanishing eigenvalues. The principal square root is not defined in this case. :meth:`real_gen_matrix_sqrt` or :meth:`complex_gen_matrix_sqrt` may be able to provide further information.
(`errno` :math:`2`)
An internal error occurred. It is likely that the function was called incorrectly.
.. _f01ep-py2-py-notes:
**Notes**
A square root of a matrix :math:`A` is a solution :math:`X` to the equation :math:`X^2 = A`.
A nonsingular matrix has multiple square roots.
For a matrix with no eigenvalues on the closed negative real line, the principal square root, denoted by :math:`A^{{1/2}}`, is the unique square root whose eigenvalues lie in the open right half-plane.
``real_tri_matrix_sqrt`` computes :math:`A^{{1/2}}`, where :math:`A` is an upper quasi-triangular matrix, with :math:`1\times 1` and :math:`2\times 2` blocks on the diagonal.
Such matrices arise from the Schur factorization of a real general matrix, as computed by :meth:`lapackeig.dhseqr <naginterfaces.library.lapackeig.dhseqr>`, for example. ``real_tri_matrix_sqrt`` does not require :math:`A` to be in the canonical Schur form described in :meth:`lapackeig.dhseqr <naginterfaces.library.lapackeig.dhseqr>`, it merely requires :math:`A` to be upper quasi-triangular. :math:`A^{{1/2}}` then has the same block triangular structure as :math:`A`.
The algorithm used by ``real_tri_matrix_sqrt`` is described in Higham (1987).
In addition a blocking scheme described in Deadman `et al.` (2013) is used.
.. _f01ep-py2-py-references:
**References**
Björck, Å and Hammarling, S, 1983, `A Schur method for the square root of a matrix`, Linear Algebra Appl. (52/53), 127--140
Deadman, E, Higham, N J and Ralha, R, 2013, `Blocked Schur Algorithms for Computing the Matrix Square Root`, `Applied Parallel and Scientific Computing: 11th International Conference, (PARA 2012, Helsinki, Finland)`, P. Manninen and P. Öster, Eds, Lecture Notes in Computer Science (7782), 171--181, Springer--Verlag
Higham, N J, 1987, `Computing real square roots of a real matrix`, Linear Algebra Appl. (88/89), 405--430
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def real_gen_matrix_pow(a, p):
r"""
``real_gen_matrix_pow`` computes the principal real power :math:`A^p`, for arbitrary :math:`p`, of a real :math:`n\times n` matrix :math:`A`.
.. _f01eq-py2-py-doc:
For full information please refer to the NAG Library document for f01eq
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01eqf.html
.. _f01eq-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**p** : float
The required power of :math:`A`.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`p`\ th power, :math:`A^p`.
.. _f01eq-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`1`)
:math:`A` has eigenvalues on the negative real line. The principal :math:`p`\ th power is not defined. :meth:`complex_gen_matrix_pow` can be used to find a complex, non-principal :math:`p`\ th power.
(`errno` :math:`2`)
:math:`A` is singular so the :math:`p`\ th power cannot be computed.
(`errno` :math:`4`)
An unexpected internal error occurred. This failure should not occur and suggests that the function has been called incorrectly.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`3`)
:math:`A^p` has been computed using an IEEE double precision Padé approximant, although the arithmetic precision is higher than IEEE double precision.
.. _f01eq-py2-py-notes:
**Notes**
For a matrix :math:`A` with no eigenvalues on the closed negative real line, :math:`A^p` (:math:`p \in \mathbb{R}`) can be defined as
.. math::
A^p = \mathrm{exp}\left(p\log\left(A\right)\right)
where :math:`\log\left(A\right)` is the principal logarithm of :math:`A` (the unique logarithm whose spectrum lies in the strip :math:`\left\{z:{-\pi } < \mathrm{Im}\left(z\right) < \pi \right\}`).
:math:`A^p` is computed using the real version of the Schur--Padé algorithm described in Higham and Lin (2011) and Higham and Lin (2013).
The real number :math:`p` is expressed as :math:`p = q+r` where :math:`q \in \left(-1, 1\right)` and :math:`r \in ℤ`.
Then :math:`A^p = A^qA^r`.
The integer power :math:`A^r` is found using a combination of binary powering and, if necessary, matrix inversion.
The fractional power :math:`A^q` is computed, entirely in real arithmetic, using a real Schur decomposition and a Padé approximant.
.. _f01eq-py2-py-references:
**References**
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
Higham, N J and Lin, L, 2011, `A Schur--Padé algorithm for fractional powers of a matrix`, SIAM J. Matrix Anal. Appl. (32(3)), 1056--1078
Higham, N J and Lin, L, 2013, `An improved Schur--Padé algorithm for fractional powers of a matrix and their Fréchet derivatives`, SIAM J. Matrix Anal. Appl. (34(3)), 1341--1360
"""
raise NotImplementedError
[docs]def complex_gen_matrix_exp(a):
r"""
``complex_gen_matrix_exp`` computes the matrix exponential, :math:`e^A`, of a complex :math:`n\times n` matrix :math:`A`.
.. _f01fc-py2-py-doc:
For full information please refer to the NAG Library document for f01fc
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01fcf.html
.. _f01fc-py2-py-parameters:
**Parameters**
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
With no exception or warning is raised, the :math:`n\times n` matrix exponential :math:`e^A`.
.. _f01fc-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`1`)
The linear equations to be solved for the Padé approximant are singular; it is likely that this function has been called incorrectly.
(`errno` :math:`2`)
The linear equations to be solved are nearly singular and the Padé approximant probably has no correct figures; it is likely that this function has been called incorrectly.
(`errno` :math:`4`)
An unexpected internal error has occurred. Please contact `NAG <https://www.nag.com>`__.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`3`)
The arithmetic precision is higher than that used for the Padé approximant computed matrix exponential.
.. _f01fc-py2-py-notes:
**Notes**
:math:`e^A` is computed using a Padé approximant and the scaling and squaring method described in Al--Mohy and Higham (2009).
.. _f01fc-py2-py-references:
**References**
Al--Mohy, A H and Higham, N J, 2009, `A new scaling and squaring algorithm for the matrix exponential`, SIAM J. Matrix Anal. (31(3)), 970--989
Higham, N J, 2005, `The scaling and squaring method for the matrix exponential revisited`, SIAM J. Matrix Anal. Appl. (26(4)), 1179--1193
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
Moler, C B and Van Loan, C F, 2003, `Nineteen dubious ways to compute the exponential of a matrix, twenty-five years later`, SIAM Rev. (45), 3--49
"""
raise NotImplementedError
[docs]def complex_herm_matrix_exp(uplo, a):
r"""
``complex_herm_matrix_exp`` computes the matrix exponential, :math:`e^A`, of a complex Hermitian :math:`n\times n` matrix :math:`A`.
.. _f01fd-py2-py-doc:
For full information please refer to the NAG Library document for f01fd
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01fdf.html
.. _f01fd-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of the matrix :math:`A` is stored.
If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of the matrix :math:`A` is stored.
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` Hermitian matrix :math:`A`.
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
If no exception or warning is raised, the upper or lower triangular part of the :math:`n\times n` matrix exponential, :math:`e^A`.
.. _f01fd-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-3`)
An internal error occurred when computing the spectral factorization. Please contact `NAG <https://www.nag.com>`__.
(`errno` :math:`-2`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-1`)
On entry, :math:`\mathrm{uplo} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{uplo} = \texttt{'L'}` or :math:`\texttt{'U'}`.
(`errno` :math:`i > 0`)
The computation of the spectral factorization failed to converge.
.. _f01fd-py2-py-notes:
**Notes**
:math:`e^A` is computed using a spectral factorization of :math:`A`
.. math::
A = QDQ^\mathrm{H}\text{,}
where :math:`D` is the diagonal matrix whose diagonal elements, :math:`d_i`, are the eigenvalues of :math:`A`, and :math:`Q` is a unitary matrix whose columns are the eigenvectors of :math:`A`. :math:`e^A` is then given by
.. math::
e^A = Qe^DQ^\mathrm{H}\text{,}
where :math:`e^D` is the diagonal matrix whose :math:`i`\ th diagonal element is :math:`e^{d_i}`.
See for example Section 4.5 of Higham (2008).
.. _f01fd-py2-py-references:
**References**
Higham, N J, 2005, `The scaling and squaring method for the matrix exponential revisited`, SIAM J. Matrix Anal. Appl. (26(4)), 1179--1193
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
Moler, C B and Van Loan, C F, 2003, `Nineteen dubious ways to compute the exponential of a matrix, twenty-five years later`, SIAM Rev. (45), 3--49
"""
raise NotImplementedError
[docs]def complex_herm_matrix_fun(uplo, a, f, data=None):
r"""
``complex_herm_matrix_fun`` computes the matrix function, :math:`f\left(A\right)`, of a complex Hermitian :math:`n\times n` matrix :math:`A`. :math:`f\left(A\right)` must also be a complex Hermitian matrix.
.. _f01ff-py2-py-doc:
For full information please refer to the NAG Library document for f01ff
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01fff.html
.. _f01ff-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of the matrix :math:`A` is stored.
If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of the matrix :math:`A` is stored.
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` Hermitian matrix :math:`A`.
**f** : callable fx = f(x, data=None)
The function :math:`\mathrm{f}` evaluates :math:`f\left(z_i\right)` at a number of points :math:`z_i`.
**Parameters**
**x** : float, ndarray, shape :math:`\left(n\right)`
The :math:`n` points :math:`x_1,x_2,\ldots,x_n` at which the function :math:`f` is to be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**fx** : float, array-like, shape :math:`\left(n\right)`
The :math:`n` function values. :math:`\mathrm{fx}[\textit{i}-1]` should return the value :math:`f\left(x_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n`.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
If no exception or warning is raised, the upper or lower triangular part of the :math:`n\times n` matrix function, :math:`f\left(A\right)`.
.. _f01ff-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-3`)
An internal error occurred when computing the spectral factorization. Please contact `NAG <https://www.nag.com>`__.
(`errno` :math:`-2`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-1`)
On entry, :math:`\mathrm{uplo} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{uplo} = \texttt{'L'}` or :math:`\texttt{'U'}`.
(`errno` :math:`i > 0`)
The computation of the spectral factorization failed to converge.
**Warns**
**NagCallbackTerminateWarning**
(`errno` :math:`-6`)
Termination requested in :math:`\mathrm{f}`.
.. _f01ff-py2-py-notes:
**Notes**
:math:`f\left(A\right)` is computed using a spectral factorization of :math:`A`
.. math::
A = QDQ^\mathrm{H}\text{,}
where :math:`D` is the real diagonal matrix whose diagonal elements, :math:`d_i`, are the eigenvalues of :math:`A`, :math:`Q` is a unitary matrix whose columns are the eigenvectors of :math:`A` and :math:`Q^\mathrm{H}` is the conjugate transpose of :math:`Q`. :math:`f\left(A\right)` is then given by
.. math::
f\left(A\right) = Qf\left(D\right)Q^\mathrm{H}\text{,}
where :math:`f\left(D\right)` is the diagonal matrix whose :math:`i`\ th diagonal element is :math:`f\left(d_i\right)`.
See for example Section 4.5 of Higham (2008). :math:`f\left(d_i\right)` is assumed to be real.
.. _f01ff-py2-py-references:
**References**
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def complex_gen_matrix_log(a):
r"""
``complex_gen_matrix_log`` computes the principal matrix logarithm, :math:`\log\left(A\right)`, of a complex :math:`n\times n` matrix :math:`A`, with no eigenvalues on the closed negative real line.
.. _f01fj-py2-py-doc:
For full information please refer to the NAG Library document for f01fj
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01fjf.html
.. _f01fj-py2-py-parameters:
**Parameters**
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` principal matrix logarithm, :math:`\log\left(A\right)`, unless :math:`\mathrm{errno}` = 2, in which case a non-principal logarithm is returned.
.. _f01fj-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`1`)
:math:`A` is singular so the logarithm cannot be computed.
(`errno` :math:`4`)
An unexpected internal error has occurred. Please contact `NAG <https://www.nag.com>`__.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`2`)
:math:`A` was found to have eigenvalues on the negative real line. The principal logarithm is not defined in this case, so a non-principal logarithm was returned.
(`errno` :math:`3`)
The arithmetic precision is higher than that used for the Padé approximant computed matrix logarithm.
.. _f01fj-py2-py-notes:
**Notes**
Any nonsingular matrix :math:`A` has infinitely many logarithms.
For a matrix with no eigenvalues on the closed negative real line, the principal logarithm is the unique logarithm whose spectrum lies in the strip :math:`\left\{{z:{-\pi } < \mathrm{Im}\left({\left(z\right) < \pi }\right)}\right\}`.
If :math:`A` is nonsingular but has eigenvalues on the negative real line, the principal logarithm is not defined, but ``complex_gen_matrix_log`` will return a non-principal logarithm.
:math:`\log\left(A\right)` is computed using the inverse scaling and squaring algorithm for the matrix logarithm described in Al--Mohy and Higham (2011).
.. _f01fj-py2-py-references:
**References**
Al--Mohy, A H and Higham, N J, 2011, `Improved inverse scaling and squaring algorithms for the matrix logarithm`, SIAM J. Sci. Comput. (34(4)), C152--C169
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def complex_gen_matrix_fun_std(fun, a):
r"""
``complex_gen_matrix_fun_std`` computes the matrix exponential, sine, cosine, sinh or cosh, of a complex :math:`n\times n` matrix :math:`A` using the Schur--Parlett algorithm.
.. _f01fk-py2-py-doc:
For full information please refer to the NAG Library document for f01fk
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01fkf.html
.. _f01fk-py2-py-parameters:
**Parameters**
**fun** : str
Indicates which matrix function will be computed.
:math:`\mathrm{fun} = \text{‘EXP'}`
The matrix exponential, :math:`e^A`, will be computed.
:math:`\mathrm{fun} = \text{‘SIN'}`
The matrix sine, :math:`\sin\left(A\right)`, will be computed.
:math:`\mathrm{fun} = \text{‘COS'}`
The matrix cosine, :math:`\cos\left(A\right)`, will be computed.
:math:`\mathrm{fun} = \text{‘SINH'}`
The hyperbolic matrix sine, :math:`\sinh\left(A\right)`, will be computed.
:math:`\mathrm{fun} = \text{‘COSH'}`
The hyperbolic matrix cosine, :math:`\cosh\left(A\right)`, will be computed.
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix, :math:`f\left(A\right)`.
.. _f01fk-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-2`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-1`)
Input argument :math:`\mathrm{fun}` is invalid.
(`errno` :math:`1`)
A Taylor series failed to converge.
(`errno` :math:`2`)
An unexpected internal error occurred when evaluating the function at a point. Please contact `NAG <https://www.nag.com>`__.
(`errno` :math:`3`)
There was an error whilst reordering the Schur form of :math:`A`.
**Note:** this failure should not occur and suggests that the function has been called incorrectly.
(`errno` :math:`4`)
The function was unable to compute the Schur decomposition of :math:`A`.
**Note:** this failure should not occur and suggests that the function has been called incorrectly.
(`errno` :math:`5`)
An unexpected internal error occurred. Please contact `NAG <https://www.nag.com>`__.
(`errno` :math:`6`)
The linear equations to be solved are nearly singular and the Padé approximant used to compute the exponential may have no correct figures.
**Note:** this failure should not occur and suggests that the function has been called incorrectly.
.. _f01fk-py2-py-notes:
**Notes**
:math:`f\left(A\right)`, where :math:`f` is either the exponential, sine, cosine, sinh or cosh, is computed using the Schur--Parlett algorithm described in Higham (2008) and Davies and Higham (2003).
.. _f01fk-py2-py-references:
**References**
Davies, P I and Higham, N J, 2003, `A Schur--Parlett algorithm for computing matrix functions`, SIAM J. Matrix Anal. Appl. (25(2)), 464--485
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def complex_gen_matrix_fun_num(a, f, data=None):
r"""
``complex_gen_matrix_fun_num`` computes the matrix function, :math:`f\left(A\right)`, of a complex :math:`n\times n` matrix :math:`A`.
Numerical differentiation is used to evaluate the derivatives of :math:`f` when they are required.
.. _f01fl-py2-py-doc:
For full information please refer to the NAG Library document for f01fl
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01flf.html
.. _f01fl-py2-py-parameters:
**Parameters**
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**f** : callable fz = f(z, data=None)
The function :math:`\mathrm{f}` evaluates :math:`f\left(z_i\right)` at a number of points :math:`z_i`.
**Parameters**
**z** : complex, ndarray, shape :math:`\left(\textit{nz}\right)`
The :math:`n_z` points :math:`z_1,z_2,\ldots,z_{n_z}` at which the function :math:`f` is to be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**fz** : complex, array-like, shape :math:`\left(\textit{nz}\right)`
The :math:`n_z` function values. :math:`\mathrm{fz}[\textit{i}-1]` should return the value :math:`f\left(z_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n_z`.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix, :math:`f\left(A\right)`.
.. _f01fl-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`1`)
A Taylor series failed to converge after :math:`40` terms. Further Taylor series coefficients can no longer reliably be obtained by numerical differentiation.
(`errno` :math:`3`)
There was an error whilst reordering the Schur form of :math:`A`.
**Note:** this failure should not occur and suggests that the function has been called incorrectly.
(`errno` :math:`4`)
The function was unable to compute the Schur decomposition of :math:`A`.
**Note:** this failure should not occur and suggests that the function has been called incorrectly.
(`errno` :math:`5`)
An unexpected internal error occurred. Please contact `NAG <https://www.nag.com>`__.
**Warns**
**NagCallbackTerminateWarning**
(`errno` :math:`2`)
Termination requested in :math:`\mathrm{f}`.
.. _f01fl-py2-py-notes:
**Notes**
:math:`f\left(A\right)` is computed using the Schur--Parlett algorithm described in Higham (2008) and Davies and Higham (2003).
The coefficients of the Taylor series used in the algorithm are evaluated using the numerical differentiation algorithm of Lyness and Moler (1967).
The scalar function :math:`f` is supplied via function :math:`\mathrm{f}` which evaluates :math:`f\left(z_i\right)` at a number of points :math:`z_i`.
.. _f01fl-py2-py-references:
**References**
Davies, P I and Higham, N J, 2003, `A Schur--Parlett algorithm for computing matrix functions`, SIAM J. Matrix Anal. Appl. (25(2)), 464--485
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
Lyness, J N and Moler, C B, 1967, `Numerical differentiation of analytic functions`, SIAM J. Numer. Anal. (4(2)), 202--210
"""
raise NotImplementedError
[docs]def complex_gen_matrix_fun_usd(a, f, data=None):
r"""
``complex_gen_matrix_fun_usd`` computes the matrix function, :math:`f\left(A\right)`, of a complex :math:`n\times n` matrix :math:`A`, using analytical derivatives of :math:`f` you have supplied.
.. _f01fm-py2-py-doc:
For full information please refer to the NAG Library document for f01fm
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01fmf.html
.. _f01fm-py2-py-parameters:
**Parameters**
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**f** : callable fz = f(m, z, data=None)
Given an integer :math:`m`, the function :math:`\mathrm{f}` evaluates :math:`f^{\left(m\right)}\left(z_i\right)` at a number of points :math:`z_i`.
**Parameters**
**m** : int
The order, :math:`m`, of the derivative required.
If :math:`\mathrm{m} = 0`, :math:`f\left(z_i\right)` should be returned.
For :math:`\mathrm{m} > 0`, :math:`f^{\left(m\right)}\left(z_i\right)` should be returned.
**z** : complex, ndarray, shape :math:`\left(\textit{nz}\right)`
The :math:`n_z` points :math:`z_1,z_2,\ldots,z_{n_z}` at which the function :math:`f` is to be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**fz** : complex, array-like, shape :math:`\left(\textit{nz}\right)`
The :math:`n_z` function or derivative values. :math:`\mathrm{fz}[\textit{i}-1]` should return the value :math:`f^{\left(m\right)}\left(z_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n_z`.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix, :math:`f\left(A\right)`.
.. _f01fm-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`1`)
A Taylor series failed to converge.
(`errno` :math:`3`)
There was an error whilst reordering the Schur form of :math:`A`.
**Note:** this failure should not occur and suggests that the function has been called incorrectly.
(`errno` :math:`4`)
The function was unable to compute the Schur decomposition of :math:`A`.
**Note:** this failure should not occur and suggests that the function has been called incorrectly.
(`errno` :math:`5`)
An unexpected internal error occurred. Please contact `NAG <https://www.nag.com>`__.
**Warns**
**NagCallbackTerminateWarning**
(`errno` :math:`2`)
Termination requested in :math:`\mathrm{f}`.
.. _f01fm-py2-py-notes:
**Notes**
:math:`f\left(A\right)` is computed using the Schur--Parlett algorithm described in Higham (2008) and Davies and Higham (2003).
The scalar function :math:`f`, and the derivatives of :math:`f`, are returned by the function :math:`\mathrm{f}` which, given an integer :math:`m`, should evaluate :math:`f^{\left(m\right)}\left(z_{\textit{i}}\right)` at a number of points :math:`z_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n_z`, on the complex plane. ``complex_gen_matrix_fun_usd`` is, therefore, appropriate for functions that can be evaluated on the complex plane and whose derivatives, of arbitrary order, can also be evaluated on the complex plane.
.. _f01fm-py2-py-references:
**References**
Davies, P I and Higham, N J, 2003, `A Schur--Parlett algorithm for computing matrix functions`, SIAM J. Matrix Anal. Appl. (25(2)), 464--485
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def complex_gen_matrix_sqrt(a):
r"""
``complex_gen_matrix_sqrt`` computes the principal matrix square root, :math:`A^{{1/2}}`, of a complex :math:`n\times n` matrix :math:`A`.
.. _f01fn-py2-py-doc:
For full information please refer to the NAG Library document for f01fn
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01fnf.html
.. _f01fn-py2-py-parameters:
**Parameters**
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
Contains, if no exception or warning is raised, the :math:`n\times n` principal matrix square root, :math:`A^{{1/2}}`. Alternatively, if :math:`\mathrm{errno}` = 1, contains an :math:`n\times n` non-principal square root of :math:`A`.
.. _f01fn-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`2`)
:math:`A` has a defective vanishing eigenvalue. The square root cannot be found in this case.
(`errno` :math:`3`)
An internal error occurred. It is likely that the function was called incorrectly.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
:math:`A` has a negative or semisimple vanishing eigenvalue. A non-principal square root is returned.
.. _f01fn-py2-py-notes:
**Notes**
A square root of a matrix :math:`A` is a solution :math:`X` to the equation :math:`X^2 = A`.
A nonsingular matrix has multiple square roots.
For a matrix with no eigenvalues on the closed negative real line, the principal square root, denoted by :math:`A^{{1/2}}`, is the unique square root whose eigenvalues lie in the open right half-plane.
:math:`A^{{1/2}}` is computed using the algorithm described in Björck and Hammarling (1983).
In addition a blocking scheme described in Deadman `et al.` (2013) is used.
.. _f01fn-py2-py-references:
**References**
Björck, Å and Hammarling, S, 1983, `A Schur method for the square root of a matrix`, Linear Algebra Appl. (52/53), 127--140
Deadman, E, Higham, N J and Ralha, R, 2013, `Blocked Schur Algorithms for Computing the Matrix Square Root`, `Applied Parallel and Scientific Computing: 11th International Conference, (PARA 2012, Helsinki, Finland)`, P. Manninen and P. Öster, Eds, Lecture Notes in Computer Science (7782), 171--181, Springer--Verlag
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def complex_tri_matrix_sqrt(a):
r"""
``complex_tri_matrix_sqrt`` computes the principal matrix square root, :math:`A^{{1/2}}`, of a complex upper triangular :math:`n\times n` matrix :math:`A`.
.. _f01fp-py2-py-doc:
For full information please refer to the NAG Library document for f01fp
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01fpf.html
.. _f01fp-py2-py-parameters:
**Parameters**
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` upper triangular matrix :math:`A`.
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
Contains, if no exception or warning is raised, the :math:`n\times n` principal matrix square root, :math:`A^{{1/2}}`. Alternatively, if :math:`\mathrm{errno}` = 1, contains an :math:`n\times n` non-principal square root of :math:`A`.
.. _f01fp-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`2`)
:math:`A` has a defective vanishing eigenvalue. The square root cannot be found in this case.
(`errno` :math:`3`)
An internal error occurred. It is likely that the function was called incorrectly.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
:math:`A` has negative or semisimple, vanishing eigenvalues. The principal square root is not defined in this case; a non-principal square root is returned.
.. _f01fp-py2-py-notes:
**Notes**
A square root of a matrix :math:`A` is a solution :math:`X` to the equation :math:`X^2 = A`.
A nonsingular matrix has multiple square roots.
For a matrix with no eigenvalues on the closed negative real line, the principal square root, denoted by :math:`A^{{1/2}}`, is the unique square root whose eigenvalues lie in the open right half-plane.
``complex_tri_matrix_sqrt`` computes :math:`A^{{1/2}}`, where :math:`A` is an upper triangular matrix. :math:`A^{{1/2}}` is also upper triangular.
The algorithm used by ``complex_tri_matrix_sqrt`` is described in Björck and Hammarling (1983).
In addition a blocking scheme described in Deadman `et al.` (2013) is used.
.. _f01fp-py2-py-references:
**References**
Björck, Å and Hammarling, S, 1983, `A Schur method for the square root of a matrix`, Linear Algebra Appl. (52/53), 127--140
Deadman, E, Higham, N J and Ralha, R, 2013, `Blocked Schur Algorithms for Computing the Matrix Square Root`, `Applied Parallel and Scientific Computing: 11th International Conference, (PARA 2012, Helsinki, Finland)`, P. Manninen and P. Öster, Eds, Lecture Notes in Computer Science (7782), 171--181, Springer--Verlag
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def complex_gen_matrix_pow(a, p):
r"""
``complex_gen_matrix_pow`` computes an abitrary real power :math:`A^p` of a complex :math:`n\times n` matrix :math:`A`.
.. _f01fq-py2-py-doc:
For full information please refer to the NAG Library document for f01fq
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01fqf.html
.. _f01fq-py2-py-parameters:
**Parameters**
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**p** : float
The required power of :math:`A`.
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
If no exception or warning is raised, the :math:`n\times n` matrix :math:`p`\ th power, :math:`A^p`. Alternatively, if :math:`\mathrm{errno}` = 1, contains an :math:`n\times n` non-principal power of :math:`A`.
.. _f01fq-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`2`)
:math:`A` is singular so the :math:`p`\ th power cannot be computed.
(`errno` :math:`4`)
An unexpected internal error occurred. This failure should not occur and suggests that the function has been called incorrectly.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
:math:`A` has eigenvalues on the negative real line. The principal :math:`p`\ th power is not defined so a non-principal power is returned.
(`errno` :math:`3`)
:math:`A^p` has been computed using an IEEE double precision Padé approximant, although the arithmetic precision is higher than IEEE double precision.
.. _f01fq-py2-py-notes:
**Notes**
For a matrix :math:`A` with no eigenvalues on the closed negative real line, :math:`A^p` (:math:`p \in \mathbb{R}`) can be defined as
.. math::
A^p = \mathrm{exp}\left(p\log\left(A\right)\right)
where :math:`\log\left(A\right)` is the principal logarithm of :math:`A` (the unique logarithm whose spectrum lies in the strip :math:`\left\{z:{-\pi } < \mathrm{Im}\left(z\right) < \pi \right\}`).
:math:`A^p` is computed using the Schur--Padé algorithm described in Higham and Lin (2011) and Higham and Lin (2013).
The real number :math:`p` is expressed as :math:`p = q+r` where :math:`q \in \left(-1, 1\right)` and :math:`r \in ℤ`.
Then :math:`A^p = A^qA^r`.
The integer power :math:`A^r` is found using a combination of binary powering and, if necessary, matrix inversion.
The fractional power :math:`A^q` is computed using a Schur decomposition and a Padé approximant.
.. _f01fq-py2-py-references:
**References**
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
Higham, N J and Lin, L, 2011, `A Schur--Padé algorithm for fractional powers of a matrix`, SIAM J. Matrix Anal. Appl. (32(3)), 1056--1078
Higham, N J and Lin, L, 2013, `An improved Schur--Padé algorithm for fractional powers of a matrix and their Fréchet derivatives`, SIAM J. Matrix Anal. Appl. (34(3)), 1341--1360
"""
raise NotImplementedError
[docs]def real_gen_matrix_actexp(a, b, t):
r"""
``real_gen_matrix_actexp`` computes the action of the matrix exponential :math:`e^{{tA}}`, on the matrix :math:`B`, where :math:`A` is a real :math:`n\times n` matrix, :math:`B` is a real :math:`n\times m` matrix and :math:`t` is a real scalar.
.. _f01ga-py2-py-doc:
For full information please refer to the NAG Library document for f01ga
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01gaf.html
.. _f01ga-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**b** : float, array-like, shape :math:`\left(n, m\right)`
The :math:`n\times m` matrix :math:`B`.
**t** : float
The scalar :math:`t`.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
:math:`A` is overwritten during the computation.
**b** : float, ndarray, shape :math:`\left(n, m\right)`
The :math:`n\times m` matrix :math:`e^{{tA}}B`.
.. _f01ga-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-2`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq 0`.
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`2`)
:math:`e^{{tA}}B` has been computed using an IEEE double precision Taylor series, although the arithmetic precision is higher than IEEE double precision.
.. _f01ga-py2-py-notes:
**Notes**
:math:`e^{{tA}}B` is computed using the algorithm described in Al--Mohy and Higham (2011) which uses a truncated Taylor series to compute the product :math:`e^{{tA}}B` without explicitly forming :math:`e^{{tA}}`.
.. _f01ga-py2-py-references:
**References**
Al--Mohy, A H and Higham, N J, 2011, `Computing the action of the matrix exponential, with an application to exponential integrators`, SIAM J. Sci. Statist. Comput. (33(2)), 488-511
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def real_gen_matrix_actexp_rcomm(irevcm, b, t, b2, x, y, p, r, z, comm, tr=0.0):
r"""
``real_gen_matrix_actexp_rcomm`` computes the action of the matrix exponential :math:`e^{{tA}}`, on the matrix :math:`B`, where :math:`A` is a real :math:`n\times n` matrix, :math:`B` is a real :math:`n\times m` matrix and :math:`t` is a real scalar.
It uses reverse communication for evaluating matrix products, so that the matrix :math:`A` is not accessed explicitly.
.. _f01gb-py2-py-doc:
For full information please refer to the NAG Library document for f01gb
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01gbf.html
.. _f01gb-py2-py-parameters:
**Parameters**
**irevcm** : int
`On initial entry`: must be set to :math:`0`.
**b** : float, ndarray, shape :math:`\left(n, m\right)`, modified in place
`On initial entry`: the :math:`n\times m` matrix :math:`B`.
`On intermediate exit`: if :math:`\mathrm{irevcm} = 1`, contains the :math:`n\times m` matrix :math:`B`.
`On intermediate entry`: must not be changed.
`On final exit`: the :math:`n\times m` matrix :math:`e^{{tA}}B`.
**t** : float
The scalar :math:`t`.
**b2** : float, ndarray, shape :math:`\left(n, m\right)`, modified in place
`On initial entry`: need not be set.
`On intermediate entry`: if :math:`\mathrm{irevcm} = 1`, must contain :math:`AB`.
`On final exit`: the array is undefined.
**x** : float, ndarray, shape :math:`\left(n, 2\right)`, modified in place
`On initial entry`: need not be set.
`On intermediate exit`: if :math:`\mathrm{irevcm} = 2`, contains the current :math:`n\times 2` matrix :math:`X`.
`On intermediate entry`: if :math:`\mathrm{irevcm} = 3`, must contain :math:`A^\mathrm{T}Y`.
`On final exit`: the array is undefined.
**y** : float, ndarray, shape :math:`\left(n, 2\right)`, modified in place
`On initial entry`: need not be set.
`On intermediate exit`: if :math:`\mathrm{irevcm} = 3`, contains the current :math:`n\times 2` matrix :math:`Y`.
`On intermediate entry`: if :math:`\mathrm{irevcm} = 2`, must contain :math:`AX`.
`On final exit`: the array is undefined.
**p** : float, ndarray, shape :math:`\left(n\right)`, modified in place
`On initial entry`: need not be set.
`On intermediate entry`: if :math:`\mathrm{irevcm} = 4`, must contain :math:`Az`.
`On final exit`: the array is undefined.
**r** : float, ndarray, shape :math:`\left(n\right)`, modified in place
`On initial entry`: need not be set.
`On intermediate entry`: if :math:`\mathrm{irevcm} = 5`, must contain :math:`A^\mathrm{T}z`.
`On final exit`: the array is undefined.
**z** : float, ndarray, shape :math:`\left(n\right)`, modified in place
`On initial entry`: need not be set.
`On intermediate exit`: if :math:`\mathrm{irevcm} = 4` or :math:`5`, contains the vector :math:`z`.
`On intermediate entry`: must not be changed.
`On final exit`: the array is undefined.
**comm** : dict, communication object, modified in place
Communication structure.
`On initial entry`: need not be set.
**tr** : float, optional
The trace of :math:`A`. If this is not available then any number can be supplied (:math:`0.0` is a reasonable default); however, in the trivial case, :math:`n = 1`, the result :math:`e^{{\mathrm{tr}t}}B` is immediately returned in the first row of :math:`B`. See `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01gbf.html#fcomments>`__.
**Returns**
**irevcm** : int
`On intermediate exit`: :math:`\mathrm{irevcm} = 1`, :math:`2`, :math:`3`, :math:`4` or :math:`5`. The calling program must:
(a) if :math:`\mathrm{irevcm} = 1`: evaluate :math:`B_2 = AB`, where :math:`B_2` is an :math:`n\times m` matrix, and store the result in :math:`\mathrm{b2}`;
if :math:`\mathrm{irevcm} = 2`: evaluate :math:`Y = AX`, where :math:`X` and :math:`Y` are :math:`n\times 2` matrices, and store the result in :math:`\mathrm{y}`;
if :math:`\mathrm{irevcm} = 3`: evaluate :math:`X = A^\mathrm{T}Y` and store the result in :math:`\mathrm{x}`;
if :math:`\mathrm{irevcm} = 4`: evaluate :math:`p = Az` and store the result in :math:`\mathrm{p}`;
if :math:`\mathrm{irevcm} = 5`: evaluate :math:`r = A^\mathrm{T}z` and store the result in :math:`\mathrm{r}`.
(#) call ``real_gen_matrix_actexp_rcomm`` again with all other parameters unchanged.
`On final exit`: :math:`\mathrm{irevcm} = 0`.
.. _f01gb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-3`)
On initial entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq 0`.
(`errno` :math:`-2`)
On initial entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-1`)
On intermediate re-entry, :math:`\mathrm{irevcm} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{irevcm} = 1`, :math:`2`, :math:`3`, :math:`4` or :math:`5`.
(`errno` :math:`-1`)
On initial entry, :math:`\mathrm{irevcm} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{irevcm} = 0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`2`)
:math:`e^{{tA}}B` has been computed using an IEEE double precision Taylor series, although the arithmetic precision is higher than IEEE double precision.
.. _f01gb-py2-py-notes:
**Notes**
:math:`e^{{tA}}B` is computed using the algorithm described in Al--Mohy and Higham (2011) which uses a truncated Taylor series to compute the :math:`e^{{tA}}B` without explicitly forming :math:`e^{{tA}}`.
The algorithm does not explicity need to access the elements of :math:`A`; it only requires the result of matrix multiplications of the form :math:`AX` or :math:`A^\mathrm{T}Y`.
A reverse communication interface is used, in which control is returned to the calling program whenever a matrix product is required.
.. _f01gb-py2-py-references:
**References**
Al--Mohy, A H and Higham, N J, 2011, `Computing the action of the matrix exponential, with an application to exponential integrators`, SIAM J. Sci. Statist. Comput. (33(2)), 488-511
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def complex_gen_matrix_actexp(a, b, t):
r"""
``complex_gen_matrix_actexp`` computes the action of the matrix exponential :math:`e^{{tA}}`, on the matrix :math:`B`, where :math:`A` is a complex :math:`n\times n` matrix, :math:`B` is a complex :math:`n\times m` matrix and :math:`t` is a complex scalar.
.. _f01ha-py2-py-doc:
For full information please refer to the NAG Library document for f01ha
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01haf.html
.. _f01ha-py2-py-parameters:
**Parameters**
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**b** : complex, array-like, shape :math:`\left(n, m\right)`
The :math:`n\times m` matrix :math:`B`.
**t** : complex
The scalar :math:`t`.
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
:math:`A` is overwritten during the computation.
**b** : complex, ndarray, shape :math:`\left(n, m\right)`
The :math:`n\times m` matrix :math:`e^{{tA}}B`.
.. _f01ha-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-2`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq 0`.
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`2`)
:math:`e^{{tA}}B` has been computed using an IEEE double precision Taylor series, although the arithmetic precision is higher than IEEE double precision.
.. _f01ha-py2-py-notes:
**Notes**
:math:`e^{{tA}}B` is computed using the algorithm described in Al--Mohy and Higham (2011) which uses a truncated Taylor series to compute the product :math:`e^{{tA}}B` without explicitly forming :math:`e^{{tA}}`.
.. _f01ha-py2-py-references:
**References**
Al--Mohy, A H and Higham, N J, 2011, `Computing the action of the matrix exponential, with an application to exponential integrators`, SIAM J. Sci. Statist. Comput. (33(2)), 488-511
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def complex_gen_matrix_actexp_rcomm(irevcm, b, t, b2, x, y, p, r, z, comm, tr=0.0):
r"""
``complex_gen_matrix_actexp_rcomm`` computes the action of the matrix exponential :math:`e^{{tA}}`, on the matrix :math:`B`, where :math:`A` is a complex :math:`n\times n` matrix, :math:`B` is a complex :math:`n\times m` matrix and :math:`t` is a complex scalar.
It uses reverse communication for evaluating matrix products, so that the matrix :math:`A` is not accessed explicitly.
.. _f01hb-py2-py-doc:
For full information please refer to the NAG Library document for f01hb
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01hbf.html
.. _f01hb-py2-py-parameters:
**Parameters**
**irevcm** : int
`On initial entry`: must be set to :math:`0`.
**b** : complex, ndarray, shape :math:`\left(n, m\right)`, modified in place
`On initial entry`: the :math:`n\times m` matrix :math:`B`.
`On intermediate exit`: if :math:`\mathrm{irevcm} = 1`, contains the :math:`n\times m` matrix :math:`B`.
`On intermediate entry`: must not be changed.
`On final exit`: the :math:`n\times m` matrix :math:`e^{{tA}}B`.
**t** : complex
The scalar :math:`t`.
**b2** : complex, ndarray, shape :math:`\left(n, m\right)`, modified in place
`On initial entry`: need not be set.
`On intermediate entry`: if :math:`\mathrm{irevcm} = 1`, must contain :math:`AB`.
`On final exit`: the array is undefined.
**x** : complex, ndarray, shape :math:`\left(n, 2\right)`, modified in place
`On initial entry`: need not be set.
`On intermediate exit`: if :math:`\mathrm{irevcm} = 2`, contains the current :math:`n\times 2` matrix :math:`X`.
`On intermediate entry`: if :math:`\mathrm{irevcm} = 3`, must contain :math:`A^\mathrm{H}Y`.
`On final exit`: the array is undefined.
**y** : complex, ndarray, shape :math:`\left(n, 2\right)`, modified in place
`On initial entry`: need not be set.
`On intermediate exit`: if :math:`\mathrm{irevcm} = 3`, contains the current :math:`n\times 2` matrix :math:`Y`.
`On intermediate entry`: if :math:`\mathrm{irevcm} = 2`, must contain :math:`AX`.
`On final exit`: the array is undefined.
**p** : complex, ndarray, shape :math:`\left(n\right)`, modified in place
`On initial entry`: need not be set.
`On intermediate entry`: if :math:`\mathrm{irevcm} = 4`, must contain :math:`Az`.
`On final exit`: the array is undefined.
**r** : complex, ndarray, shape :math:`\left(n\right)`, modified in place
`On initial entry`: need not be set.
`On intermediate entry`: if :math:`\mathrm{irevcm} = 5`, must contain :math:`A^\mathrm{H}z`.
`On final exit`: the array is undefined.
**z** : complex, ndarray, shape :math:`\left(n\right)`, modified in place
`On initial entry`: need not be set.
`On intermediate exit`: if :math:`\mathrm{irevcm} = 4` or :math:`5`, contains the vector :math:`z`.
`On intermediate entry`: must not be changed.
`On final exit`: the array is undefined.
**comm** : dict, communication object, modified in place
Communication structure.
`On initial entry`: need not be set.
**tr** : complex, optional
The trace of :math:`A`. If this is not available then any number can be supplied (:math:`0.0` is a reasonable default); however, in the trivial case, :math:`n = 1`, the result :math:`e^{{\mathrm{tr}t}}B` is immediately returned in the first row of :math:`B`. See `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01hbf.html#fcomments>`__.
**Returns**
**irevcm** : int
`On intermediate exit`: :math:`\mathrm{irevcm} = 1`, :math:`2`, :math:`3`, :math:`4` or :math:`5`. The calling program must:
(a) if :math:`\mathrm{irevcm} = 1`: evaluate :math:`B_2 = AB`, where :math:`B_2` is an :math:`n\times m` matrix, and store the result in :math:`\mathrm{b2}`;
if :math:`\mathrm{irevcm} = 2`: evaluate :math:`Y = AX`, where :math:`X` and :math:`Y` are :math:`n\times 2` matrices, and store the result in :math:`\mathrm{y}`;
if :math:`\mathrm{irevcm} = 3`: evaluate :math:`X = A^\mathrm{H}Y` and store the result in :math:`\mathrm{x}`;
if :math:`\mathrm{irevcm} = 4`: evaluate :math:`p = Az` and store the result in :math:`\mathrm{p}`;
if :math:`\mathrm{irevcm} = 5`: evaluate :math:`r = A^\mathrm{H}z` and store the result in :math:`\mathrm{r}`.
(#) call ``complex_gen_matrix_actexp_rcomm`` again with all other parameters unchanged.
`On final exit`: :math:`\mathrm{irevcm} = 0`.
.. _f01hb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-3`)
On initial entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq 0`.
(`errno` :math:`-2`)
On initial entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-1`)
On intermediate re-entry, :math:`\mathrm{irevcm} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{irevcm} = 1`, :math:`2`, :math:`3`, :math:`4` or :math:`5`.
(`errno` :math:`-1`)
On initial entry, :math:`\mathrm{irevcm} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{irevcm} = 0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`2`)
:math:`e^{{tA}}B` has been computed using an IEEE double precision Taylor series, although the arithmetic precision is higher than IEEE double precision.
.. _f01hb-py2-py-notes:
**Notes**
:math:`e^{{tA}}B` is computed using the algorithm described in Al--Mohy and Higham (2011) which uses a truncated Taylor series to compute the :math:`e^{{tA}}B` without explicitly forming :math:`e^{{tA}}`.
The algorithm does not explicity need to access the elements of :math:`A`; it only requires the result of matrix multiplications of the form :math:`AX` or :math:`A^\mathrm{H}Y`.
A reverse communication interface is used, in which control is returned to the calling program whenever a matrix product is required.
.. _f01hb-py2-py-references:
**References**
Al--Mohy, A H and Higham, N J, 2011, `Computing the action of the matrix exponential, with an application to exponential integrators`, SIAM J. Sci. Statist. Comput. (33(2)), 488-511
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def real_gen_matrix_cond_std(fun, a):
r"""
``real_gen_matrix_cond_std`` computes an estimate of the absolute condition number of a matrix function :math:`f` at a real :math:`n\times n` matrix :math:`A` in the :math:`1`-norm, where :math:`f` is either the exponential, logarithm, sine, cosine, hyperbolic sine (sinh) or hyperbolic cosine (cosh).
The evaluation of the matrix function, :math:`f\left(A\right)`, is also returned.
.. _f01ja-py2-py-doc:
For full information please refer to the NAG Library document for f01ja
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01jaf.html
.. _f01ja-py2-py-parameters:
**Parameters**
**fun** : str
Indicates which matrix function will be used.
:math:`\mathrm{fun} = \text{‘EXP'}`
The matrix exponential, :math:`e^A`, will be used.
:math:`\mathrm{fun} = \text{‘SIN'}`
The matrix sine, :math:`\sin\left(A\right)`, will be used.
:math:`\mathrm{fun} = \text{‘COS'}`
The matrix cosine, :math:`\cos\left(A\right)`, will be used.
:math:`\mathrm{fun} = \text{‘SINH'}`
The hyperbolic matrix sine, :math:`\sinh\left(A\right)`, will be used.
:math:`\mathrm{fun} = \text{‘COSH'}`
The hyperbolic matrix cosine, :math:`\cosh\left(A\right)`, will be used.
:math:`\mathrm{fun} = \text{‘LOG'}`
The matrix logarithm, :math:`\log\left(A\right)`, will be used.
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix, :math:`f\left(A\right)`.
**conda** : float
An estimate of the absolute condition number of :math:`f` at :math:`A`.
**norma** : float
The :math:`1`-norm of :math:`A`.
**normfa** : float
The :math:`1`-norm of :math:`f\left(A\right)`.
.. _f01ja-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-2`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-1`)
Input argument number :math:`\langle\mathit{\boldsymbol{value}}\rangle` is invalid.
(`errno` :math:`1`)
An internal error occurred when evaluating the matrix function :math:`f\left(A\right)`. Please contact `NAG <https://www.nag.com>`__.
(`errno` :math:`2`)
An internal error occurred when estimating the norm of the Fréchet derivative of :math:`f` at :math:`A`. Please contact `NAG <https://www.nag.com>`__.
.. _f01ja-py2-py-notes:
**Notes**
The absolute condition number of :math:`f` at :math:`A`, :math:`\mathrm{cond}_{\mathrm{abs}}\left(f, A\right)` is given by the norm of the Fréchet derivative of :math:`f`, :math:`L\left(A\right)`, which is defined by
.. math::
\left\lVert L\left(X\right)\right\rVert :=\mathrm{max}_{{E\neq 0}}\frac{\left\lVert L\left(X, E\right)\right\rVert }{\left\lVert E\right\rVert }\text{,}
where :math:`L\left(X, E\right)` is the Fréchet derivative in the direction :math:`E`. :math:`L\left(X, E\right)` is linear in :math:`E` and can, therefore, be written as
.. math::
\mathrm{vec}\left(L\left(X, E\right)\right) = K\left(X\right)\mathrm{vec}\left(E\right)\text{,}
where the :math:`\mathrm{vec}` operator stacks the columns of a matrix into one vector, so that :math:`K\left(X\right)` is :math:`n^2\times n^2`. ``real_gen_matrix_cond_std`` computes an estimate :math:`\gamma` such that :math:`\gamma \leq \left\lVert K\left(X\right)\right\rVert_1`, where :math:`\left\lVert K\left(X\right)\right\rVert_1 \in \left[{n^{-1}\left\lVert L\left(X\right)\right\rVert_1}, {n\left\lVert L\left(X\right)\right\rVert_1}\right]`.
The relative condition number can then be computed via
.. math::
\mathrm{cond}_{\mathrm{rel}}\left(f, A\right) = \frac{{\mathrm{cond}_{\mathrm{abs}}\left(f, A\right)\left\lVert A\right\rVert_1}}{\left\lVert f\left(A\right)\right\rVert_1}\text{.}
The algorithm used to find :math:`\gamma` is detailed in Section 3.4 of Higham (2008).
.. _f01ja-py2-py-references:
**References**
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def real_gen_matrix_cond_num(a, f, data=None):
r"""
``real_gen_matrix_cond_num`` computes an estimate of the absolute condition number of a matrix function :math:`f` at a real :math:`n\times n` matrix :math:`A` in the :math:`1`-norm.
Numerical differentiation is used to evaluate the derivatives of :math:`f` when they are required.
.. _f01jb-py2-py-doc:
For full information please refer to the NAG Library document for f01jb
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01jbf.html
.. _f01jb-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**f** : callable fz = f(z, data=None)
The function :math:`\mathrm{f}` evaluates :math:`f\left(z_i\right)` at a number of points :math:`z_i`.
**Parameters**
**z** : complex, ndarray, shape :math:`\left(\textit{nz}\right)`
The :math:`n_z` points :math:`z_1,z_2,\ldots,z_{n_z}` at which the function :math:`f` is to be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**fz** : complex, array-like, shape :math:`\left(\textit{nz}\right)`
The :math:`n_z` function values. :math:`\mathrm{fz}[\textit{i}-1]` should return the value :math:`f\left(z_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n_z`. If :math:`z_i` lies on the real line, then so must :math:`f\left(z_i\right)`.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix, :math:`f\left(A\right)`.
**conda** : float
An estimate of the absolute condition number of :math:`f` at :math:`A`.
**norma** : float
The :math:`1`-norm of :math:`A`.
**normfa** : float
The :math:`1`-norm of :math:`f\left(A\right)`.
.. _f01jb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`1`)
An internal error occurred when estimating the norm of the Fréchet derivative of :math:`f` at :math:`A`. Please contact `NAG <https://www.nag.com>`__.
(`errno` :math:`2`)
An internal error occurred when evaluating the matrix function :math:`f\left(A\right)`. You can investigate further by calling :meth:`real_gen_matrix_fun_num` with the matrix :math:`A` and the function :math:`f`.
**Warns**
**NagCallbackTerminateWarning**
(`errno` :math:`3`)
Termination requested in :math:`\mathrm{f}`.
.. _f01jb-py2-py-notes:
**Notes**
The absolute condition number of :math:`f` at :math:`A`, :math:`\mathrm{cond}_{\mathrm{abs}}\left(f, A\right)` is given by the norm of the Fréchet derivative of :math:`f`, :math:`L\left(A\right)`, which is defined by
.. math::
\left\lVert L\left(X\right)\right\rVert :=\mathrm{max}_{{E\neq 0}}\frac{\left\lVert L\left(X, E\right)\right\rVert }{\left\lVert E\right\rVert }\text{,}
where :math:`L\left(X, E\right)` is the Fréchet derivative in the direction :math:`E`. :math:`L\left(X, E\right)` is linear in :math:`E` and can, therefore, be written as
.. math::
\mathrm{vec}\left(L\left(X, E\right)\right) = K\left(X\right)\mathrm{vec}\left(E\right)\text{,}
where the :math:`\mathrm{vec}` operator stacks the columns of a matrix into one vector, so that :math:`K\left(X\right)` is :math:`n^2\times n^2`. ``real_gen_matrix_cond_num`` computes an estimate :math:`\gamma` such that :math:`\gamma \leq \left\lVert K\left(X\right)\right\rVert_1`, where :math:`\left\lVert K\left(X\right)\right\rVert_1 \in \left[{n^{-1}\left\lVert L\left(X\right)\right\rVert_1}, {n\left\lVert L\left(X\right)\right\rVert_1}\right]`.
The relative condition number can then be computed via
.. math::
\mathrm{cond}_{\mathrm{rel}}\left(f, A\right) = \frac{{\mathrm{cond}_{\mathrm{abs}}\left(f, A\right)\left\lVert A\right\rVert_1}}{\left\lVert f\left(A\right)\right\rVert_1}\text{.}
The algorithm used to find :math:`\gamma` is detailed in Section 3.4 of Higham (2008).
The function :math:`f` is supplied via function :math:`\mathrm{f}` which evaluates :math:`f\left(z_i\right)` at a number of points :math:`z_i`.
.. _f01jb-py2-py-references:
**References**
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def real_gen_matrix_cond_usd(a, f, data=None):
r"""
``real_gen_matrix_cond_usd`` computes an estimate of the absolute condition number of a matrix function :math:`f` at a real :math:`n\times n` matrix :math:`A` in the :math:`1`-norm, using analytical derivatives of :math:`f` you have supplied.
.. _f01jc-py2-py-doc:
For full information please refer to the NAG Library document for f01jc
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01jcf.html
.. _f01jc-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**f** : callable fz = f(m, z, data=None)
Given an integer :math:`m`, the function :math:`\mathrm{f}` evaluates :math:`f^{\left(m\right)}\left(z_i\right)` at a number of points :math:`z_i`.
**Parameters**
**m** : int
The order, :math:`m`, of the derivative required.
If :math:`\mathrm{m} = 0`, :math:`f\left(z_i\right)` should be returned.
For :math:`\mathrm{m} > 0`, :math:`f^{\left(m\right)}\left(z_i\right)` should be returned.
**z** : complex, ndarray, shape :math:`\left(\textit{nz}\right)`
The :math:`n_z` points :math:`z_1,z_2,\ldots,z_{n_z}` at which the function :math:`f` is to be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**fz** : complex, array-like, shape :math:`\left(\textit{nz}\right)`
The :math:`n_z` function or derivative values. :math:`\mathrm{fz}[\textit{i}-1]` should return the value :math:`f^{\left(m\right)}\left(z_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n_z`. If :math:`z_i` lies on the real line, then so must :math:`f^{\left(m\right)}\left(z_i\right)`.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix, :math:`f\left(A\right)`.
**conda** : float
An estimate of the absolute condition number of :math:`f` at :math:`A`.
**norma** : float
The :math:`1`-norm of :math:`A`.
**normfa** : float
The :math:`1`-norm of :math:`f\left(A\right)`.
.. _f01jc-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`1`)
An internal error occurred when estimating the norm of the Fréchet derivative of :math:`f` at :math:`A`. Please contact `NAG <https://www.nag.com>`__.
(`errno` :math:`2`)
An internal error occurred when evaluating the matrix function :math:`f\left(A\right)`. You can investigate further by calling :meth:`real_gen_matrix_fun_usd` with the matrix :math:`A` and the function :math:`f`.
**Warns**
**NagCallbackTerminateWarning**
(`errno` :math:`3`)
Termination requested in :math:`\mathrm{f}`.
.. _f01jc-py2-py-notes:
**Notes**
The absolute condition number of :math:`f` at :math:`A`, :math:`\mathrm{cond}_{\mathrm{abs}}\left(f, A\right)` is given by the norm of the Fréchet derivative of :math:`f`, :math:`L\left(A\right)`, which is defined by
.. math::
\left\lVert L\left(X\right)\right\rVert :=\mathrm{max}_{{E\neq 0}}\frac{\left\lVert L\left(X, E\right)\right\rVert }{\left\lVert E\right\rVert }\text{,}
where :math:`L\left(X, E\right)` is the Fréchet derivative in the direction :math:`E`. :math:`L\left(X, E\right)` is linear in :math:`E` and can, therefore, be written as
.. math::
\mathrm{vec}\left(L\left(X, E\right)\right) = K\left(X\right)\mathrm{vec}\left(E\right)\text{,}
where the :math:`\mathrm{vec}` operator stacks the columns of a matrix into one vector, so that :math:`K\left(X\right)` is :math:`n^2\times n^2`. ``real_gen_matrix_cond_usd`` computes an estimate :math:`\gamma` such that :math:`\gamma \leq \left\lVert K\left(X\right)\right\rVert_1`, where :math:`\left\lVert K\left(X\right)\right\rVert_1 \in \left[{n^{-1}\left\lVert L\left(X\right)\right\rVert_1}, {n\left\lVert L\left(X\right)\right\rVert_1}\right]`.
The relative condition number can then be computed via
.. math::
\mathrm{cond}_{\mathrm{rel}}\left(f, A\right) = \frac{{\mathrm{cond}_{\mathrm{abs}}\left(f, A\right)\left\lVert A\right\rVert_1}}{\left\lVert f\left(A\right)\right\rVert_1}\text{.}
The algorithm used to find :math:`\gamma` is detailed in Section 3.4 of Higham (2008).
The function :math:`f`, and the derivatives of :math:`f`, are returned by function :math:`\mathrm{f}` which, given an integer :math:`m`, evaluates :math:`f^{\left(m\right)}\left(z_{\textit{i}}\right)` at a number of (generally complex) points :math:`z_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n_z`.
For any :math:`z` on the real line, :math:`f\left(z\right)` must also be real. ``real_gen_matrix_cond_usd`` is, therefore, appropriate for functions that can be evaluated on the complex plane and whose derivatives, of arbitrary order, can also be evaluated on the complex plane.
.. _f01jc-py2-py-references:
**References**
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def real_gen_matrix_cond_sqrt(a):
r"""
``real_gen_matrix_cond_sqrt`` computes an estimate of the relative condition number :math:`\kappa_{A^{{1/2}}}` and a bound on the relative residual, in the Frobenius norm, for the square root of a real :math:`n\times n` matrix :math:`A`.
The principal square root, :math:`A^{{1/2}}`, of :math:`A` is also returned.
.. _f01jd-py2-py-doc:
For full information please refer to the NAG Library document for f01jd
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01jdf.html
.. _f01jd-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
Contains, if no exception or warning is raised, the :math:`n\times n` principal matrix square root, :math:`A^{{1/2}}`. Alternatively, if :math:`\mathrm{errno}` = 1, contains an :math:`n\times n` non-principal square root of :math:`A`.
**alpha** : float
An estimate of the stability of the relative residual for the computed principal (if no exception or warning is raised) or non-principal (if :math:`\mathrm{errno}` = 1) matrix square root, :math:`\alpha`.
**condsa** : float
An estimate of the relative condition number, in the Frobenius norm, of the principal (if no exception or warning is raised) or non-principal (if :math:`\mathrm{errno}` = 1) matrix square root at :math:`A`, :math:`\kappa_{A^{{1/2}}}`.
.. _f01jd-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`2`)
:math:`A` has a defective vanishing eigenvalue. The square root and condition number cannot be found in this case.
(`errno` :math:`3`)
:math:`A` has a negative real eigenvalue. The principal square root is not defined. :meth:`complex_gen_matrix_cond_sqrt` can be used to return a complex, non-principal square root.
(`errno` :math:`4`)
An error occurred when computing the matrix square root. Consequently, :math:`\mathrm{alpha}` and :math:`\mathrm{condsa}` could not be computed. It is likely that the function was called incorrectly.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
:math:`A` has a semisimple vanishing eigenvalue. A non-principal square root was returned.
(`errno` :math:`5`)
An error occurred when computing the condition number. The matrix square root was still returned but you should use :meth:`real_gen_matrix_sqrt` to check if it is the principal matrix square root.
.. _f01jd-py2-py-notes:
**Notes**
For a matrix with no eigenvalues on the closed negative real line, the principal matrix square root, :math:`A^{{1/2}}`, of :math:`A` is the unique square root with eigenvalues in the right half-plane.
The Fréchet derivative of a matrix function :math:`A^{{1/2}}` in the direction of the matrix :math:`E` is the linear function mapping :math:`E` to :math:`L\left(A, E\right)` such that
.. math::
\left(A+E\right)^{{1/2}}-A^{{1/2}}-L\left(A, E\right) = o\left(\left\lVert A\right\rVert \right)\text{.}
The absolute condition number is given by the norm of the Fréchet derivative which is defined by
.. math::
\left\lVert L\left(A\right)\right\rVert :=\mathrm{max}_{{E\neq 0}}\frac{\left\lVert L\left(A, E\right)\right\rVert }{\left\lVert E\right\rVert }\text{.}
The Fréchet derivative is linear in :math:`E` and can, therefore, be written as
.. math::
\mathrm{vec}\left(L\left(A, E\right)\right) = K\left(A\right)\mathrm{vec}\left(E\right)\text{,}
where the :math:`\mathrm{vec}` operator stacks the columns of a matrix into one vector, so that :math:`K\left(A\right)` is :math:`n^2\times n^2`.
``real_gen_matrix_cond_sqrt`` uses Algorithm 3.20 from Higham (2008) to compute an estimate :math:`\gamma` such that :math:`\gamma \leq \left\lVert K\left(X\right)\right\rVert_F`.
The quantity of :math:`\gamma` provides a good approximation to :math:`\left\lVert L\left(A\right)\right\rVert_F`.
The relative condition number, :math:`\kappa_{A^{{1/2}}}`, is then computed via
.. math::
\kappa_{A^{{1/2}}} = \frac{{\left\lVert L\left(A\right)\right\rVert_F\left\lVert A\right\rVert_F}}{{\left\lVert A^{{1/2}}\right\rVert_F}}\text{.}
:math:`\kappa_{A^{{1/2}}}` is returned in the argument :math:`\mathrm{condsa}`.
:math:`A^{{1/2}}` is computed using the algorithm described in Higham (1987).
This is a real arithmetic version of the algorithm of Björck and Hammarling (1983).
In addition, a blocking scheme described in Deadman `et al.` (2013) is used.
The computed quantity :math:`\alpha` is a measure of the stability of the relative residual (see `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01jdf.html#accuracy>`__).
It is computed via
.. math::
\alpha = \frac{\left\lVert A^{{1/2}}\right\rVert_F^2}{\left\lVert A\right\rVert_F}\text{.}
.. _f01jd-py2-py-references:
**References**
Björck, Å and Hammarling, S, 1983, `A Schur method for the square root of a matrix`, Linear Algebra Appl. (52/53), 127--140
Deadman, E, Higham, N J and Ralha, R, 2013, `Blocked Schur Algorithms for Computing the Matrix Square Root`, `Applied Parallel and Scientific Computing: 11th International Conference, (PARA 2012, Helsinki, Finland)`, P. Manninen and P. Öster, Eds, Lecture Notes in Computer Science (7782), 171--181, Springer--Verlag
Higham, N J, 1987, `Computing real square roots of a real matrix`, Linear Algebra Appl. (88/89), 405--430
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def real_gen_matrix_cond_pow(a, p):
r"""
``real_gen_matrix_cond_pow`` computes an estimate of the relative condition number :math:`\kappa_{A^p}` of the :math:`p`\ th power (where :math:`p` is real) of a real :math:`n\times n` matrix :math:`A`, in the :math:`1`-norm.
The principal matrix power :math:`A^p` is also returned.
.. _f01je-py2-py-doc:
For full information please refer to the NAG Library document for f01je
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01jef.html
.. _f01je-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**p** : float
The required power of :math:`A`.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` principal matrix :math:`p`\ th power, :math:`A^p`.
**condpa** : float
If the function exits successfully or :math:`\mathrm{errno}` = 3, an estimate of the relative condition number of the matrix :math:`p`\ th power, :math:`\kappa_{A^p}`. Alternatively, if :math:`\mathrm{errno}` = 4, the absolute condition number of the matrix :math:`p`\ th power.
.. _f01je-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`1`)
:math:`A` has eigenvalues on the negative real line. The principal :math:`p`\ th power is not defined in this case; :meth:`complex_gen_matrix_cond_pow` can be used to find a complex, non-principal :math:`p`\ th power.
(`errno` :math:`2`)
:math:`A` is singular so the :math:`p`\ th power cannot be computed.
(`errno` :math:`4`)
The relative condition number is infinite. The absolute condition number was returned instead.
(`errno` :math:`5`)
An unexpected internal error occurred. This failure should not occur and suggests that the function has been called incorrectly.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`3`)
:math:`A^p` has been computed using an IEEE double precision Padé approximant, although the arithmetic precision is higher than IEEE double precision.
.. _f01je-py2-py-notes:
**Notes**
For a matrix :math:`A` with no eigenvalues on the closed negative real line, :math:`A^p` (:math:`p \in \mathbb{R}`) can be defined as
.. math::
A^p = \mathrm{exp}\left(p\log\left(A\right)\right)
where :math:`\log\left(A\right)` is the principal logarithm of :math:`A` (the unique logarithm whose spectrum lies in the strip :math:`\left\{z:{-\pi } < \mathrm{Im}\left(z\right) < \pi \right\}`).
The Fréchet derivative of the matrix :math:`p`\ th power of :math:`A` is the unique linear mapping :math:`E⟼L\left(A, E\right)` such that for any matrix :math:`E`
.. math::
\left(A+E\right)^p-A^p-L\left(A, E\right) = o\left(\left\lVert E\right\rVert \right)\text{.}
The derivative describes the first-order effect of perturbations in :math:`A` on the matrix power :math:`A^p`.
The relative condition number of the matrix :math:`p`\ th power can be defined by
.. math::
\kappa_{A^p} = \frac{{\left\lVert L\left(A\right)\right\rVert \left\lVert A\right\rVert }}{\left\lVert A^p\right\rVert }\text{,}
where :math:`\left\lVert L\left(A\right)\right\rVert` is the norm of the Fréchet derivative of the matrix power at :math:`A`.
``real_gen_matrix_cond_pow`` uses the algorithms of Higham and Lin (2011) and Higham and Lin (2013) to compute :math:`\kappa_{A^p}` and :math:`A^p`.
The real number :math:`p` is expressed as :math:`p = q+r` where :math:`q \in \left(-1, 1\right)` and :math:`r \in ℤ`.
Then :math:`A^p = A^qA^r`.
The integer power :math:`A^r` is found using a combination of binary powering and, if necessary, matrix inversion.
The fractional power :math:`A^q` is computed using a Schur decomposition, a Padé approximant and the scaling and squaring method.
To obtain an estimate of :math:`\kappa_{A^p}`, ``real_gen_matrix_cond_pow`` first estimates :math:`\left\lVert L\left(A\right)\right\rVert` by computing an estimate :math:`\gamma` of a quantity :math:`K \in \left[{n^{-1}\left\lVert L\left(A\right)\right\rVert_1}, {n\left\lVert L\left(A\right)\right\rVert_1}\right]`, such that :math:`\gamma \leq K`.
This requires multiple Fréchet derivatives to be computed.
Fréchet derivatives of :math:`A^q` are obtained by differentiating the Padé approximant.
Fréchet derivatives of :math:`A^p` are then computed using a combination of the chain rule and the product rule for Fréchet derivatives.
.. _f01je-py2-py-references:
**References**
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
Higham, N J and Lin, L, 2011, `A Schur--Padé algorithm for fractional powers of a matrix`, SIAM J. Matrix Anal. Appl. (32(3)), 1056--1078
Higham, N J and Lin, L, 2013, `An improved Schur--Padé algorithm for fractional powers of a matrix and their Fréchet derivatives`, SIAM J. Matrix Anal. Appl. (34(3)), 1341--1360
"""
raise NotImplementedError
[docs]def real_gen_matrix_frcht_pow(a, e, p):
r"""
``real_gen_matrix_frcht_pow`` computes the Fréchet derivative :math:`L\left(A, E\right)` of the :math:`p`\ th power (where :math:`p` is real) of the real :math:`n\times n` matrix :math:`A` applied to the real :math:`n\times n` matrix :math:`E`.
The principal matrix power :math:`A^p` is also returned.
.. _f01jf-py2-py-doc:
For full information please refer to the NAG Library document for f01jf
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01jff.html
.. _f01jf-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**e** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`E`.
**p** : float
The required power of :math:`A`.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` principal matrix :math:`p`\ th power, :math:`A^p`.
**e** : float, ndarray, shape :math:`\left(n, n\right)`
The Fréchet derivative :math:`L\left(A, E\right)`.
.. _f01jf-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`1`)
:math:`A` has eigenvalues on the negative real line. The principal :math:`p`\ th power is not defined in this case; :meth:`complex_gen_matrix_frcht_pow` can be used to find a complex, non-principal :math:`p`\ th power.
(`errno` :math:`2`)
:math:`A` is singular so the :math:`p`\ th power cannot be computed.
(`errno` :math:`4`)
An unexpected internal error occurred. This failure should not occur and suggests that the function has been called incorrectly.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`3`)
:math:`A^p` has been computed using an IEEE double precision Padé approximant, although the arithmetic precision is higher than IEEE double precision.
.. _f01jf-py2-py-notes:
**Notes**
For a matrix :math:`A` with no eigenvalues on the closed negative real line, :math:`A^p` (:math:`p \in \mathbb{R}`) can be defined as
.. math::
A^p = \mathrm{exp}\left(p\log\left(A\right)\right)
where :math:`\log\left(A\right)` is the principal logarithm of :math:`A` (the unique logarithm whose spectrum lies in the strip :math:`\left\{z:{-\pi } < \mathrm{Im}\left(z\right) < \pi \right\}`).
The Fréchet derivative of the matrix :math:`p`\ th power of :math:`A` is the unique linear mapping :math:`E⟼L\left(A, E\right)` such that for any matrix :math:`E`
.. math::
\left(A+E\right)^p-A^p-L\left(A, E\right) = o\left(\left\lVert E\right\rVert \right)\text{.}
The derivative describes the first-order effect of perturbations in :math:`A` on the matrix power :math:`A^p`.
``real_gen_matrix_frcht_pow`` uses the algorithms of Higham and Lin (2011) and Higham and Lin (2013) to compute :math:`A^p` and :math:`L\left(A, E\right)`.
The real number :math:`p` is expressed as :math:`p = q+r` where :math:`q \in \left(-1, 1\right)` and :math:`r \in ℤ`.
Then :math:`A^p = A^qA^r`.
The integer power :math:`A^r` is found using a combination of binary powering and, if necessary, matrix inversion.
The fractional power :math:`A^q` is computed using a Schur decomposition, a Padé approximant and the scaling and squaring method.
The Padé approximant is differentiated in order to obtain the Fréchet derivative of :math:`A^q` and :math:`L\left(A, E\right)` is then computed using a combination of the chain rule and the product rule for Fréchet derivatives.
.. _f01jf-py2-py-references:
**References**
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
Higham, N J and Lin, L, 2011, `A Schur--Padé algorithm for fractional powers of a matrix`, SIAM J. Matrix Anal. Appl. (32(3)), 1056--1078
Higham, N J and Lin, L, 2013, `An improved Schur--Padé algorithm for fractional powers of a matrix and their Fréchet derivatives`, SIAM J. Matrix Anal. Appl. (34(3)), 1341--1360
"""
raise NotImplementedError
[docs]def real_gen_matrix_cond_exp(a):
r"""
``real_gen_matrix_cond_exp`` computes an estimate of the relative condition number :math:`\kappa_{\mathrm{exp}}\left(A\right)` of the exponential of a real :math:`n\times n` matrix :math:`A`, in the :math:`1`-norm.
The matrix exponential :math:`e^A` is also returned.
.. _f01jg-py2-py-doc:
For full information please refer to the NAG Library document for f01jg
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01jgf.html
.. _f01jg-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix exponential :math:`e^A`.
**condea** : float
An estimate of the relative condition number of the matrix exponential :math:`\kappa_{\mathrm{exp}}\left(A\right)`.
.. _f01jg-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`1`)
The linear equations to be solved for the Padé approximant are singular; it is likely that this function has been called incorrectly.
(`errno` :math:`3`)
An unexpected internal error has occurred. Please contact `NAG <https://www.nag.com>`__.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`2`)
The arithmetic precision is higher than that used for the Padé approximant computed matrix exponential.
.. _f01jg-py2-py-notes:
**Notes**
The Fréchet derivative of the matrix exponential of :math:`A` is the unique linear mapping :math:`E⟼L\left(A, E\right)` such that for any matrix :math:`E`
.. math::
e^{{A+E}}-e^A-L\left(A, E\right) = o\left(\left\lVert E\right\rVert \right)\text{.}
The derivative describes the first-order effect of perturbations in :math:`A` on the exponential :math:`e^A`.
The relative condition number of the matrix exponential can be defined by
.. math::
\kappa_{\mathrm{exp}}\left(A\right) = \frac{{\left\lVert L\left(A\right)\right\rVert \left\lVert A\right\rVert }}{\left\lVert \mathrm{exp}\left(A\right)\right\rVert }\text{,}
where :math:`\left\lVert L\left(A\right)\right\rVert` is the norm of the Fréchet derivative of the matrix exponential at :math:`A`.
To obtain the estimate of :math:`\kappa_{\mathrm{exp}}\left(A\right)`, ``real_gen_matrix_cond_exp`` first estimates :math:`\left\lVert L\left(A\right)\right\rVert` by computing an estimate :math:`\gamma` of a quantity :math:`K \in \left[{n^{-1}\left\lVert L\left(A\right)\right\rVert_1}, {n\left\lVert L\left(A\right)\right\rVert_1}\right]`, such that :math:`\gamma \leq K`.
The algorithms used to compute :math:`\kappa_{\mathrm{exp}}\left(A\right)` are detailed in the Al--Mohy and Higham (2009a) and Al--Mohy and Higham (2009b).
The matrix exponential :math:`e^A` is computed using a Padé approximant and the scaling and squaring method.
The Padé approximant is differentiated to obtain the Fréchet derivatives :math:`L\left(A, E\right)` which are used to estimate the condition number.
.. _f01jg-py2-py-references:
**References**
Al--Mohy, A H and Higham, N J, 2009, `A new scaling and squaring algorithm for the matrix exponential`, SIAM J. Matrix Anal. (31(3)), 970--989
Al--Mohy, A H and Higham, N J, 2009, `Computing the Fréchet derivative of the matrix exponential, with an application to condition number estimation`, SIAM J. Matrix Anal. Appl. (30(4)), 1639--1657
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
Moler, C B and Van Loan, C F, 2003, `Nineteen dubious ways to compute the exponential of a matrix, twenty-five years later`, SIAM Rev. (45), 3--49
"""
raise NotImplementedError
[docs]def real_gen_matrix_frcht_exp(a, e):
r"""
``real_gen_matrix_frcht_exp`` computes the Fréchet derivative :math:`L\left(A, E\right)` of the matrix exponential of a real :math:`n\times n` matrix :math:`A` applied to the real :math:`n\times n` matrix :math:`E`.
The matrix exponential :math:`e^A` is also returned.
.. _f01jh-py2-py-doc:
For full information please refer to the NAG Library document for f01jh
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01jhf.html
.. _f01jh-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**e** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`E`
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix exponential :math:`e^A`.
**e** : float, ndarray, shape :math:`\left(n, n\right)`
The Fréchet derivative :math:`L\left(A, E\right)`
.. _f01jh-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`1`)
The linear equations to be solved for the Padé approximant are singular; it is likely that this function has been called incorrectly.
(`errno` :math:`3`)
An unexpected internal error has occurred. Please contact `NAG <https://www.nag.com>`__.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`2`)
The arithmetic precision is higher than that used for the Padé approximant computed matrix exponential.
.. _f01jh-py2-py-notes:
**Notes**
The Fréchet derivative of the matrix exponential of :math:`A` is the unique linear mapping :math:`E⟼L\left(A, E\right)` such that for any matrix :math:`E`
.. math::
e^{{A+E}}-e^A-L\left(A, E\right) = o\left(\left\lVert E\right\rVert \right)\text{.}
The derivative describes the first-order effect of perturbations in :math:`A` on the exponential :math:`e^A`.
``real_gen_matrix_frcht_exp`` uses the algorithms of Al--Mohy and Higham (2009a) and Al--Mohy and Higham (2009b) to compute :math:`e^A` and :math:`L\left(A, E\right)`.
The matrix exponential :math:`e^A` is computed using a Padé approximant and the scaling and squaring method.
The Padé approximant is then differentiated in order to obtain the Fréchet derivative :math:`L\left(A, E\right)`.
.. _f01jh-py2-py-references:
**References**
Al--Mohy, A H and Higham, N J, 2009, `A new scaling and squaring algorithm for the matrix exponential`, SIAM J. Matrix Anal. (31(3)), 970--989
Al--Mohy, A H and Higham, N J, 2009, `Computing the Fréchet derivative of the matrix exponential, with an application to condition number estimation`, SIAM J. Matrix Anal. Appl. (30(4)), 1639--1657
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
Moler, C B and Van Loan, C F, 2003, `Nineteen dubious ways to compute the exponential of a matrix, twenty-five years later`, SIAM Rev. (45), 3--49
"""
raise NotImplementedError
[docs]def real_gen_matrix_cond_log(a):
r"""
``real_gen_matrix_cond_log`` computes an estimate of the relative condition number :math:`\kappa_{\mathrm{log}}\left(A\right)` of the logarithm of a real :math:`n\times n` matrix :math:`A`, in the :math:`1`-norm.
The principal matrix logarithm :math:`\log\left(A\right)` is also returned.
.. _f01jj-py2-py-doc:
For full information please refer to the NAG Library document for f01jj
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01jjf.html
.. _f01jj-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` principal matrix logarithm, :math:`\log\left(A\right)`.
**condla** : float
With the function exits successfully or :math:`\mathrm{errno}` = 3, an estimate of the relative condition number of the matrix logarithm, :math:`\kappa_{\mathrm{log}}\left(A\right)`. Alternatively, if :math:`\mathrm{errno}` = 4, contains the absolute condition number of the matrix logarithm.
.. _f01jj-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`1`)
:math:`A` is singular so the logarithm cannot be computed.
(`errno` :math:`2`)
:math:`A` has eigenvalues on the negative real line. The principal logarithm is not defined in this case; :meth:`complex_gen_matrix_cond_log` can be used to return a complex, non-principal log.
(`errno` :math:`5`)
An unexpected internal error occurred. This failure should not occur and suggests that the function has been called incorrectly.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`3`)
:math:`\log\left(A\right)` has been computed using an IEEE double precision Padé approximant, although the arithmetic precision is higher than IEEE double precision.
(`errno` :math:`4`)
The relative condition number is infinite. The absolute condition number was returned instead.
.. _f01jj-py2-py-notes:
**Notes**
For a matrix with no eigenvalues on the closed negative real line, the principal matrix logarithm :math:`\log\left(A\right)` is the unique logarithm whose spectrum lies in the strip :math:`\left\{{z:{-\pi } < \mathrm{Im}\left({\left(z\right) < \pi }\right)}\right\}`.
The Fréchet derivative of the matrix logarithm of :math:`A` is the unique linear mapping :math:`E⟼L\left(A, E\right)` such that for any matrix :math:`E`
.. math::
\log\left(A+E\right)-\log\left(A\right)-L\left(A, E\right) = o\left(\left\lVert E\right\rVert \right)\text{.}
The derivative describes the first order effect of perturbations in :math:`A` on the logarithm :math:`\log\left(A\right)`.
The relative condition number of the matrix logarithm can be defined by
.. math::
\kappa_{\mathrm{log}}\left(A\right) = \frac{{\left\lVert L\left(A\right)\right\rVert \left\lVert A\right\rVert }}{\left\lVert \log\left(A\right)\right\rVert }\text{,}
where :math:`\left\lVert L\left(A\right)\right\rVert` is the norm of the Fréchet derivative of the matrix logarithm at :math:`A`.
To obtain the estimate of :math:`\kappa_{\mathrm{log}}\left(A\right)`, ``real_gen_matrix_cond_log`` first estimates :math:`\left\lVert L\left(A\right)\right\rVert` by computing an estimate :math:`\gamma` of a quantity :math:`K \in \left[{n^{-1}\left\lVert L\left(A\right)\right\rVert_1}, {n\left\lVert L\left(A\right)\right\rVert_1}\right]`, such that :math:`\gamma \leq K`.
The algorithms used to compute :math:`\kappa_{\mathrm{log}}\left(A\right)` and :math:`\log\left(A\right)` are based on a Schur decomposition, the inverse scaling and squaring method and Padé approximants.
Further details can be found in Al--Mohy and Higham (2011) and Al--Mohy `et al.` (2012).
.. _f01jj-py2-py-references:
**References**
Al--Mohy, A H and Higham, N J, 2011, `Improved inverse scaling and squaring algorithms for the matrix logarithm`, SIAM J. Sci. Comput. (34(4)), C152--C169
Al--Mohy, A H, Higham, N J and Relton, S D, 2012, `Computing the Fréchet derivative of the matrix logarithm and estimating the condition number`, SIAM J. Sci. Comput. (35(4)), C394--C410
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def real_gen_matrix_frcht_log(a, e):
r"""
``real_gen_matrix_frcht_log`` computes the Fréchet derivative :math:`L\left(A, E\right)` of the matrix logarithm of the real :math:`n\times n` matrix :math:`A` applied to the real :math:`n\times n` matrix :math:`E`.
The principal matrix logarithm :math:`\log\left(A\right)` is also returned.
.. _f01jk-py2-py-doc:
For full information please refer to the NAG Library document for f01jk
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01jkf.html
.. _f01jk-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**e** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`E`
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` principal matrix logarithm, :math:`\log\left(A\right)`.
**e** : float, ndarray, shape :math:`\left(n, n\right)`
The Fréchet derivative :math:`L\left(A, E\right)`
.. _f01jk-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`1`)
:math:`A` is singular so the logarithm cannot be computed.
(`errno` :math:`2`)
:math:`A` has eigenvalues on the negative real line. The principal logarithm is not defined in this case; :meth:`complex_gen_matrix_frcht_log` can be used to return a complex, non-principal log.
(`errno` :math:`4`)
An unexpected internal error occurred. This failure should not occur and suggests that the function has been called incorrectly.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`3`)
:math:`\log\left(A\right)` has been computed using an IEEE double precision Padé approximant, although the arithmetic precision is higher than IEEE double precision.
.. _f01jk-py2-py-notes:
**Notes**
For a matrix with no eigenvalues on the closed negative real line, the principal matrix logarithm :math:`\log\left(A\right)` is the unique logarithm whose spectrum lies in the strip :math:`\left\{{z:{-\pi } < \mathrm{Im}\left({\left(z\right) < \pi }\right)}\right\}`.
The Fréchet derivative of the matrix logarithm of :math:`A` is the unique linear mapping :math:`E⟼L\left(A, E\right)` such that for any matrix :math:`E`
.. math::
\log\left(A+E\right)-\log\left(A\right)-L\left(A, E\right) = o\left(\left\lVert E\right\rVert \right)\text{.}
The derivative describes the first order effect of perturbations in :math:`A` on the logarithm :math:`\log\left(A\right)`.
``real_gen_matrix_frcht_log`` uses the algorithm of Al--Mohy `et al.` (2012) to compute :math:`\log\left(A\right)` and :math:`L\left(A, E\right)`.
The principal matrix logarithm :math:`\log\left(A\right)` is computed using a Schur decomposition, a Padé approximant and the inverse scaling and squaring method.
The Padé approximant is then differentiated in order to obtain the Fréchet derivative :math:`L\left(A, E\right)`.
.. _f01jk-py2-py-references:
**References**
Al--Mohy, A H and Higham, N J, 2011, `Improved inverse scaling and squaring algorithms for the matrix logarithm`, SIAM J. Sci. Comput. (34(4)), C152--C169
Al--Mohy, A H, Higham, N J and Relton, S D, 2012, `Computing the Fréchet derivative of the matrix logarithm and estimating the condition number`, SIAM J. Sci. Comput. (35(4)), C394--C410
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def complex_gen_matrix_cond_std(fun, a):
r"""
``complex_gen_matrix_cond_std`` computes an estimate of the absolute condition number of a matrix function :math:`f` of a complex :math:`n\times n` matrix :math:`A` in the :math:`1`-norm, where :math:`f` is either the exponential, logarithm, sine, cosine, hyperbolic sine (sinh) or hyperbolic cosine (cosh).
The evaluation of the matrix function, :math:`f\left(A\right)`, is also returned.
.. _f01ka-py2-py-doc:
For full information please refer to the NAG Library document for f01ka
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01kaf.html
.. _f01ka-py2-py-parameters:
**Parameters**
**fun** : str
Indicates which matrix function will be used.
:math:`\mathrm{fun} = \text{‘EXP'}`
The matrix exponential, :math:`e^A`, will be used.
:math:`\mathrm{fun} = \text{‘SIN'}`
The matrix sine, :math:`\sin\left(A\right)`, will be used.
:math:`\mathrm{fun} = \text{‘COS'}`
The matrix cosine, :math:`\cos\left(A\right)`, will be used.
:math:`\mathrm{fun} = \text{‘SINH'}`
The hyperbolic matrix sine, :math:`\sinh\left(A\right)`, will be used.
:math:`\mathrm{fun} = \text{‘COSH'}`
The hyperbolic matrix cosine, :math:`\cosh\left(A\right)`, will be used.
:math:`\mathrm{fun} = \text{‘LOG'}`
The matrix logarithm, :math:`\log\left(A\right)`, will be used.
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix, :math:`f\left(A\right)`.
**conda** : float
An estimate of the absolute condition number of :math:`f` at :math:`A`.
**norma** : float
The :math:`1`-norm of :math:`A`.
**normfa** : float
The :math:`1`-norm of :math:`f\left(A\right)`.
.. _f01ka-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-2`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-1`)
Input argument number :math:`\langle\mathit{\boldsymbol{value}}\rangle` is invalid.
(`errno` :math:`1`)
An internal error occurred when estimating the norm of the Fréchet derivative of :math:`f` at :math:`A`. Please contact `NAG <https://www.nag.com>`__.
(`errno` :math:`2`)
An internal error occurred when evaluating the matrix function :math:`f\left(A\right)`. You can investigate further by calling :meth:`complex_gen_matrix_exp`, :meth:`complex_gen_matrix_log` or :meth:`complex_gen_matrix_fun_std` with the matrix :math:`A`.
.. _f01ka-py2-py-notes:
**Notes**
The absolute condition number of :math:`f` at :math:`A`, :math:`\mathrm{cond}_{\mathrm{abs}}\left(f, A\right)` is given by the norm of the Fréchet derivative of :math:`f`, :math:`L\left(A\right)`, which is defined by
.. math::
\left\lVert L\left(X\right)\right\rVert :=\mathrm{max}_{{E\neq 0}}\frac{\left\lVert L\left(X, E\right)\right\rVert }{\left\lVert E\right\rVert }\text{,}
where :math:`L\left(X, E\right)` is the Fréchet derivative in the direction :math:`E`. :math:`L\left(X, E\right)` is linear in :math:`E` and can, therefore, be written as
.. math::
\mathrm{vec}\left(L\left(X, E\right)\right) = K\left(X\right)\mathrm{vec}\left(E\right)\text{,}
where the :math:`\mathrm{vec}` operator stacks the columns of a matrix into one vector, so that :math:`K\left(X\right)` is :math:`n^2\times n^2`. ``complex_gen_matrix_cond_std`` computes an estimate :math:`\gamma` such that :math:`\gamma \leq \left\lVert K\left(X\right)\right\rVert_1`, where :math:`\left\lVert K\left(X\right)\right\rVert_1 \in \left[{n^{-1}\left\lVert L\left(X\right)\right\rVert_1}, {n\left\lVert L\left(X\right)\right\rVert_1}\right]`.
The relative condition number can then be computed via
.. math::
\mathrm{cond}_{\mathrm{rel}}\left(f, A\right) = \frac{{\mathrm{cond}_{\mathrm{abs}}\left(f, A\right)\left\lVert A\right\rVert_1}}{\left\lVert f\left(A\right)\right\rVert_1}\text{.}
The algorithm used to find :math:`\gamma` is detailed in Section 3.4 of Higham (2008).
.. _f01ka-py2-py-references:
**References**
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def complex_gen_matrix_cond_num(a, f, data=None):
r"""
``complex_gen_matrix_cond_num`` computes an estimate of the absolute condition number of a matrix function :math:`f` of a complex :math:`n\times n` matrix :math:`A` in the :math:`1`-norm.
Numerical differentiation is used to evaluate the derivatives of :math:`f` when they are required.
.. _f01kb-py2-py-doc:
For full information please refer to the NAG Library document for f01kb
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01kbf.html
.. _f01kb-py2-py-parameters:
**Parameters**
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**f** : callable fz = f(z, data=None)
The function :math:`\mathrm{f}` evaluates :math:`f\left(z_i\right)` at a number of points :math:`z_i`.
**Parameters**
**z** : complex, ndarray, shape :math:`\left(\textit{nz}\right)`
The :math:`n_z` points :math:`z_1,z_2,\ldots,z_{n_z}` at which the function :math:`f` is to be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**fz** : complex, array-like, shape :math:`\left(\textit{nz}\right)`
The :math:`n_z` function values. :math:`\mathrm{fz}[\textit{i}-1]` should return the value :math:`f\left(z_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n_z`.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix, :math:`f\left(A\right)`.
**conda** : float
An estimate of the absolute condition number of :math:`f` at :math:`A`.
**norma** : float
The :math:`1`-norm of :math:`A`.
**normfa** : float
The :math:`1`-norm of :math:`f\left(A\right)`.
.. _f01kb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`1`)
An internal error occurred when estimating the norm of the Fréchet derivative of :math:`f` at :math:`A`. Please contact `NAG <https://www.nag.com>`__.
(`errno` :math:`2`)
An internal error occurred while evaluating the matrix function :math:`f\left(A\right)`. You can investigate further by calling :meth:`complex_gen_matrix_fun_num` with the matrix :math:`A` and the function :math:`f`.
**Warns**
**NagCallbackTerminateWarning**
(`errno` :math:`3`)
Termination requested in :math:`\mathrm{f}`.
.. _f01kb-py2-py-notes:
**Notes**
The absolute condition number of :math:`f` at :math:`A`, :math:`\mathrm{cond}_{\mathrm{abs}}\left(f, A\right)` is given by the norm of the Fréchet derivative of :math:`f`, :math:`L\left(A\right)`, which is defined by
.. math::
\left\lVert L\left(X\right)\right\rVert :=\mathrm{max}_{{E\neq 0}}\frac{\left\lVert L\left(X, E\right)\right\rVert }{\left\lVert E\right\rVert }\text{,}
where :math:`L\left(X, E\right)` is the Fréchet derivative in the direction :math:`E`. :math:`L\left(X, E\right)` is linear in :math:`E` and can, therefore, be written as
.. math::
\mathrm{vec}\left(L\left(X, E\right)\right) = K\left(X\right)\mathrm{vec}\left(E\right)\text{,}
where the :math:`\mathrm{vec}` operator stacks the columns of a matrix into one vector, so that :math:`K\left(X\right)` is :math:`n^2\times n^2`. ``complex_gen_matrix_cond_num`` computes an estimate :math:`\gamma` such that :math:`\gamma \leq \left\lVert K\left(X\right)\right\rVert_1`, where :math:`\left\lVert K\left(X\right)\right\rVert_1 \in \left[{n^{-1}\left\lVert L\left(X\right)\right\rVert_1}, {n\left\lVert L\left(X\right)\right\rVert_1}\right]`.
The relative condition number can then be computed via
.. math::
\mathrm{cond}_{\mathrm{rel}}\left(f, A\right) = \frac{{\mathrm{cond}_{\mathrm{abs}}\left(f, A\right)\left\lVert A\right\rVert_1}}{\left\lVert f\left(A\right)\right\rVert_1}\text{.}
The algorithm used to find :math:`\gamma` is detailed in Section 3.4 of Higham (2008).
.. _f01kb-py2-py-references:
**References**
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def complex_gen_matrix_cond_usd(a, f, data=None):
r"""
``complex_gen_matrix_cond_usd`` computes an estimate of the absolute condition number of a matrix function :math:`f` of a complex :math:`n\times n` matrix :math:`A` in the :math:`1`-norm, using analytical derivatives of :math:`f` you have supplied.
.. _f01kc-py2-py-doc:
For full information please refer to the NAG Library document for f01kc
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01kcf.html
.. _f01kc-py2-py-parameters:
**Parameters**
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**f** : callable fz = f(m, z, data=None)
Given an integer :math:`m`, the function :math:`\mathrm{f}` evaluates :math:`f^{\left(m\right)}\left(z_i\right)` at a number of points :math:`z_i`.
**Parameters**
**m** : int
The order, :math:`m`, of the derivative required.
If :math:`\mathrm{m} = 0`, :math:`f\left(z_i\right)` should be returned.
For :math:`\mathrm{m} > 0`, :math:`f^{\left(m\right)}\left(z_i\right)` should be returned.
**z** : complex, ndarray, shape :math:`\left(\textit{nz}\right)`
The :math:`n_z` points :math:`z_1,z_2,\ldots,z_{n_z}` at which the function :math:`f` is to be evaluated.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**fz** : complex, array-like, shape :math:`\left(\textit{nz}\right)`
The :math:`n_z` function or derivative values. :math:`\mathrm{fz}[\textit{i}-1]` should return the value :math:`f^{\left(m\right)}\left(z_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n_z`.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix, :math:`f\left(A\right)`.
**conda** : float
An estimate of the absolute condition number of :math:`f` at :math:`A`.
**norma** : float
The :math:`1`-norm of :math:`A`.
**normfa** : float
The :math:`1`-norm of :math:`f\left(A\right)`.
.. _f01kc-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`1`)
An internal error occurred when estimating the norm of the Fréchet derivative of :math:`f` at :math:`A`. Please contact `NAG <https://www.nag.com>`__.
(`errno` :math:`2`)
An internal error occurred when evaluating the matrix function :math:`f\left(A\right)`. You can investigate further by calling :meth:`complex_gen_matrix_fun_usd` with the matrix :math:`A` and the function :math:`f`.
**Warns**
**NagCallbackTerminateWarning**
(`errno` :math:`3`)
Termination requested in :math:`\mathrm{f}`.
.. _f01kc-py2-py-notes:
**Notes**
The absolute condition number of :math:`f` at :math:`A`, :math:`\mathrm{cond}_{\mathrm{abs}}\left(f, A\right)` is given by the norm of the Fréchet derivative of :math:`f`, :math:`L\left(A\right)`, which is defined by
.. math::
\left\lVert L\left(X\right)\right\rVert :=\mathrm{max}_{{E\neq 0}}\frac{\left\lVert L\left(X, E\right)\right\rVert }{\left\lVert E\right\rVert }\text{,}
where :math:`L\left(X, E\right)` is the Fréchet derivative in the direction :math:`E`. :math:`L\left(X, E\right)` is linear in :math:`E` and can, therefore, be written as
.. math::
\mathrm{vec}\left(L\left(X, E\right)\right) = K\left(X\right)\mathrm{vec}\left(E\right)\text{,}
where the :math:`\mathrm{vec}` operator stacks the columns of a matrix into one vector, so that :math:`K\left(X\right)` is :math:`n^2\times n^2`. ``complex_gen_matrix_cond_usd`` computes an estimate :math:`\gamma` such that :math:`\gamma \leq \left\lVert K\left(X\right)\right\rVert_1`, where :math:`\left\lVert K\left(X\right)\right\rVert_1 \in \left[{n^{-1}\left\lVert L\left(X\right)\right\rVert_1}, {n\left\lVert L\left(X\right)\right\rVert_1}\right]`.
The relative condition number can then be computed via
.. math::
\mathrm{cond}_{\mathrm{rel}}\left(f, A\right) = \frac{{\mathrm{cond}_{\mathrm{abs}}\left(f, A\right)\left\lVert A\right\rVert_1}}{\left\lVert f\left(A\right)\right\rVert_1}\text{.}
The algorithm used to find :math:`\gamma` is detailed in Section 3.4 of Higham (2008).
.. _f01kc-py2-py-references:
**References**
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def complex_gen_matrix_cond_sqrt(a):
r"""
``complex_gen_matrix_cond_sqrt`` computes an estimate of the relative condition number, :math:`\kappa_{A^{{1/2}}}`, and a bound on the relative residual, in the Frobenius norm, for the square root of a complex :math:`n\times n` matrix :math:`A`.
The principal square root, :math:`A^{{1/2}}`, of :math:`A` is also returned.
.. _f01kd-py2-py-doc:
For full information please refer to the NAG Library document for f01kd
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01kdf.html
.. _f01kd-py2-py-parameters:
**Parameters**
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` principal matrix square root :math:`A^{{1/2}}`. Alternatively, if :math:`\mathrm{errno}` = 1, contains an :math:`n\times n` non-principal square root of :math:`A`.
**alpha** : float
An estimate of the stability of the relative residual for the computed principal (if no exception or warning is raised) or non-principal (if :math:`\mathrm{errno}` = 1) matrix square root, :math:`\alpha`.
**condsa** : float
An estimate of the relative condition number, in the Frobenius norm, of the principal (if no exception or warning is raised) or non-principal (if :math:`\mathrm{errno}` = 1) matrix square root at :math:`A`, :math:`\kappa_{A^{{1/2}}}`.
.. _f01kd-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`2`)
:math:`A` has a defective vanishing eigenvalue. The square root and condition number cannot be found in this case.
(`errno` :math:`3`)
An error occurred when computing the matrix square root. Consequently, :math:`\mathrm{alpha}` and :math:`\mathrm{condsa}` could not be computed. It is likely that the function was called incorrectly.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
:math:`A` has a negative or semisimple vanishing eigenvalue. A non-principal square root was returned.
(`errno` :math:`4`)
An error occurred when computing the condition number. The matrix square root was still returned but you should use :meth:`complex_gen_matrix_sqrt` to check if it is the principal matrix square root.
.. _f01kd-py2-py-notes:
**Notes**
For a matrix with no eigenvalues on the closed negative real line, the principal matrix square root, :math:`A^{{1/2}}`, of :math:`A` is the unique square root with eigenvalues in the right half-plane.
The Fréchet derivative of a matrix function :math:`A^{{1/2}}` in the direction of the matrix :math:`E` is the linear function mapping :math:`E` to :math:`L\left(A, E\right)` such that
.. math::
\left(A+E\right)^{{1/2}}-A^{{1/2}}-L\left(A, E\right) = o\left(\left\lVert A\right\rVert \right)\text{.}
The absolute condition number is given by the norm of the Fréchet derivative which is defined by
.. math::
\left\lVert L\left(A\right)\right\rVert :=\mathrm{max}_{{E\neq 0}}\frac{\left\lVert L\left(A, E\right)\right\rVert }{\left\lVert E\right\rVert }\text{.}
The Fréchet derivative is linear in :math:`E` and can, therefore, be written as
.. math::
\mathrm{vec}\left(L\left(A, E\right)\right) = K\left(A\right)\mathrm{vec}\left(E\right)\text{,}
where the :math:`\mathrm{vec}` operator stacks the columns of a matrix into one vector, so that :math:`K\left(A\right)` is :math:`n^2\times n^2`.
``complex_gen_matrix_cond_sqrt`` uses Algorithm 3.20 from Higham (2008) to compute an estimate :math:`\gamma` such that :math:`\gamma \leq \left\lVert K\left(X\right)\right\rVert_F`.
The quantity of :math:`\gamma` provides a good approximation to :math:`\left\lVert L\left(A\right)\right\rVert_F`.
The relative condition number, :math:`\kappa_{A^{{1/2}}}`, is then computed via
.. math::
\kappa_{A^{{1/2}}} = \frac{{\left\lVert L\left(A\right)\right\rVert_F\left\lVert A\right\rVert_F}}{{\left\lVert A^{{1/2}}\right\rVert_F}}\text{.}
:math:`\kappa_{A^{{1/2}}}` is returned in the argument :math:`\mathrm{condsa}`.
:math:`A^{{1/2}}` is computed using the algorithm described in Higham (1987).
This is a version of the algorithm of Björck and Hammarling (1983).
In addition, a blocking scheme described in Deadman `et al.` (2013) is used.
The computed quantity :math:`\alpha` is a measure of the stability of the relative residual (see `Accuracy <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01kdf.html#accuracy>`__).
It is computed via
.. math::
\alpha = \frac{\left\lVert A^{{1/2}}\right\rVert_F^2}{\left\lVert A\right\rVert_F}\text{.}
.. _f01kd-py2-py-references:
**References**
Björck, Å and Hammarling, S, 1983, `A Schur method for the square root of a matrix`, Linear Algebra Appl. (52/53), 127--140
Deadman, E, Higham, N J and Ralha, R, 2013, `Blocked Schur Algorithms for Computing the Matrix Square Root`, `Applied Parallel and Scientific Computing: 11th International Conference, (PARA 2012, Helsinki, Finland)`, P. Manninen and P. Öster, Eds, Lecture Notes in Computer Science (7782), 171--181, Springer--Verlag
Higham, N J, 1987, `Computing real square roots of a real matrix`, Linear Algebra Appl. (88/89), 405--430
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def complex_gen_matrix_cond_pow(a, p):
r"""
``complex_gen_matrix_cond_pow`` computes an estimate of the relative condition number :math:`\kappa_{A^p}` of the :math:`p`\ th power (where :math:`p` is real) of a complex :math:`n\times n` matrix :math:`A`, in the :math:`1`-norm.
The principal matrix power :math:`A^p` is also returned.
.. _f01ke-py2-py-doc:
For full information please refer to the NAG Library document for f01ke
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01kef.html
.. _f01ke-py2-py-parameters:
**Parameters**
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**p** : float
The required power of :math:`A`.
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` principal matrix :math:`p`\ th power, :math:`A^p`, unless :math:`\mathrm{errno}` = 1, in which case a non-principal :math:`p`\ th power is returned.
**condpa** : float
If the function exits successfully or :math:`\mathrm{errno}` = 3, an estimate of the relative condition number of the matrix :math:`p`\ th power, :math:`\kappa_{A^p}`. Alternatively, if :math:`\mathrm{errno}` = 4, the absolute condition number of the matrix :math:`p`\ th power.
.. _f01ke-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`2`)
:math:`A` is singular so the :math:`p`\ th power cannot be computed.
(`errno` :math:`5`)
An unexpected internal error occurred. This failure should not occur and suggests that the function has been called incorrectly.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
:math:`A` has eigenvalues on the negative real line. The principal :math:`p`\ th power is not defined in this case, so a non-principal power was returned.
(`errno` :math:`3`)
:math:`A^p` has been computed using an IEEE double precision Padé approximant, although the arithmetic precision is higher than IEEE double precision.
(`errno` :math:`4`)
The relative condition number is infinite. The absolute condition number was returned instead.
.. _f01ke-py2-py-notes:
**Notes**
For a matrix :math:`A` with no eigenvalues on the closed negative real line, :math:`A^p` (:math:`p \in \mathbb{R}`) can be defined as
.. math::
A^p = \mathrm{exp}\left(p\log\left(A\right)\right)
where :math:`\log\left(A\right)` is the principal logarithm of :math:`A` (the unique logarithm whose spectrum lies in the strip :math:`\left\{z:{-\pi } < \mathrm{Im}\left(z\right) < \pi \right\}`).
The Fréchet derivative of the matrix :math:`p`\ th power of :math:`A` is the unique linear mapping :math:`E⟼L\left(A, E\right)` such that for any matrix :math:`E`
.. math::
\left(A+E\right)^p-A^p-L\left(A, E\right) = o\left(\left\lVert E\right\rVert \right)\text{.}
The derivative describes the first-order effect of perturbations in :math:`A` on the matrix power :math:`A^p`.
The relative condition number of the matrix :math:`p`\ th power can be defined by
.. math::
\kappa_{A^p} = \frac{{\left\lVert L\left(A\right)\right\rVert \left\lVert A\right\rVert }}{\left\lVert A^p\right\rVert }\text{,}
where :math:`\left\lVert L\left(A\right)\right\rVert` is the norm of the Fréchet derivative of the matrix power at :math:`A`.
``complex_gen_matrix_cond_pow`` uses the algorithms of Higham and Lin (2011) and Higham and Lin (2013) to compute :math:`\kappa_{A^p}` and :math:`A^p`.
The real number :math:`p` is expressed as :math:`p = q+r` where :math:`q \in \left(-1, 1\right)` and :math:`r \in ℤ`.
Then :math:`A^p = A^qA^r`.
The integer power :math:`A^r` is found using a combination of binary powering and, if necessary, matrix inversion.
The fractional power :math:`A^q` is computed using a Schur decomposition, a Padé approximant and the scaling and squaring method.
To obtain the estimate of :math:`\kappa_{A^p}`, ``complex_gen_matrix_cond_pow`` first estimates :math:`\left\lVert L\left(A\right)\right\rVert` by computing an estimate :math:`\gamma` of a quantity :math:`K \in \left[{n^{-1}\left\lVert L\left(A\right)\right\rVert_1}, {n\left\lVert L\left(A\right)\right\rVert_1}\right]`, such that :math:`\gamma \leq K`.
This requires multiple Fréchet derivatives to be computed.
Fréchet derivatives of :math:`A^q` are obtained by differentiating the Padé approximant.
Fréchet derivatives of :math:`A^p` are then computed using a combination of the chain rule and the product rule for Fréchet derivatives.
If :math:`A` is nonsingular but has negative real eigenvalues ``complex_gen_matrix_cond_pow`` will return a non-principal matrix :math:`p`\ th power and its condition number.
.. _f01ke-py2-py-references:
**References**
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
Higham, N J and Lin, L, 2011, `A Schur--Padé algorithm for fractional powers of a matrix`, SIAM J. Matrix Anal. Appl. (32(3)), 1056--1078
Higham, N J and Lin, L, 2013, `An improved Schur--Padé algorithm for fractional powers of a matrix and their Fréchet derivatives`, SIAM J. Matrix Anal. Appl. (34(3)), 1341--1360
"""
raise NotImplementedError
[docs]def complex_gen_matrix_frcht_pow(a, e, p):
r"""
``complex_gen_matrix_frcht_pow`` computes the Fréchet derivative :math:`L\left(A, E\right)` of the :math:`p`\ th power (where :math:`p` is real) of the complex :math:`n\times n` matrix :math:`A` applied to the complex :math:`n\times n` matrix :math:`E`.
The principal matrix power :math:`A^p` is also returned.
.. _f01kf-py2-py-doc:
For full information please refer to the NAG Library document for f01kf
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01kff.html
.. _f01kf-py2-py-parameters:
**Parameters**
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**e** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`E`.
**p** : float
The required power of :math:`A`.
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` principal matrix :math:`p`\ th power, :math:`A^p`. Alternatively if :math:`\mathrm{errno}` = 1, a non-principal :math:`p`\ th power is returned.
**e** : complex, ndarray, shape :math:`\left(n, n\right)`
The Fréchet derivative :math:`L\left(A, E\right)`.
.. _f01kf-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`2`)
:math:`A` is singular so the :math:`p`\ th power cannot be computed.
(`errno` :math:`4`)
An unexpected internal error occurred. This failure should not occur and suggests that the function has been called incorrectly.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`1`)
:math:`A` has eigenvalues on the negative real line. The principal :math:`p`\ th power is not defined in this case, so a non-principal power was returned.
(`errno` :math:`3`)
:math:`A^p` has been computed using an IEEE double precision Padé approximant, although the arithmetic precision is higher than IEEE double precision.
.. _f01kf-py2-py-notes:
**Notes**
For a matrix :math:`A` with no eigenvalues on the closed negative real line, :math:`A^p` (:math:`p \in \mathbb{R}`) can be defined as
.. math::
A^p = \mathrm{exp}\left(p\log\left(A\right)\right)
where :math:`\log\left(A\right)` is the principal logarithm of :math:`A` (the unique logarithm whose spectrum lies in the strip :math:`\left\{z:{-\pi } < \mathrm{Im}\left(z\right) < \pi \right\}`).
If :math:`A` is nonsingular but has negative real eigenvalues, the principal logarithm is not defined, but a non-principal :math:`p`\ th power can be defined by using a non-principal logarithm.
The Fréchet derivative of the matrix :math:`p`\ th power of :math:`A` is the unique linear mapping :math:`E⟼L\left(A, E\right)` such that for any matrix :math:`E`
.. math::
\left(A+E\right)^p-A^p-L\left(A, E\right) = o\left(\left\lVert E\right\rVert \right)\text{.}
The derivative describes the first-order effect of perturbations in :math:`A` on the matrix power :math:`A^p`.
``complex_gen_matrix_frcht_pow`` uses the algorithms of Higham and Lin (2011) and Higham and Lin (2013) to compute :math:`A^p` and :math:`L\left(A, E\right)`.
The real number :math:`p` is expressed as :math:`p = q+r` where :math:`q \in \left(-1, 1\right)` and :math:`r \in ℤ`.
Then :math:`A^p = A^qA^r`.
The integer power :math:`A^r` is found using a combination of binary powering and, if necessary, matrix inversion.
The fractional power :math:`A^q` is computed using a Schur decomposition, a Padé approximant and the scaling and squaring method.
The Padé approximant is differentiated in order to obtain the Fréchet derivative of :math:`A^q` and :math:`L\left(A, E\right)` is then computed using a combination of the chain rule and the product rule for Fréchet derivatives.
.. _f01kf-py2-py-references:
**References**
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
Higham, N J and Lin, L, 2011, `A Schur--Padé algorithm for fractional powers of a matrix`, SIAM J. Matrix Anal. Appl. (32(3)), 1056--1078
Higham, N J and Lin, L, 2013, `An improved Schur--Padé algorithm for fractional powers of a matrix and their Fréchet derivatives`, SIAM J. Matrix Anal. Appl. (34(3)), 1341--1360
"""
raise NotImplementedError
[docs]def complex_gen_matrix_cond_exp(a):
r"""
``complex_gen_matrix_cond_exp`` computes an estimate of the relative condition number :math:`\kappa_{\mathrm{exp}}\left(A\right)` of the exponential of a complex :math:`n\times n` matrix :math:`A`, in the :math:`1`-norm.
The matrix exponential :math:`e^A` is also returned.
.. _f01kg-py2-py-doc:
For full information please refer to the NAG Library document for f01kg
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01kgf.html
.. _f01kg-py2-py-parameters:
**Parameters**
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix exponential :math:`e^A`.
**condea** : float
An estimate of the relative condition number of the matrix exponential :math:`\kappa_{\mathrm{exp}}\left(A\right)`.
.. _f01kg-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`1`)
The linear equations to be solved for the Padé approximant are singular; it is likely that this function has been called incorrectly.
(`errno` :math:`3`)
An unexpected internal error has occurred. Please contact `NAG <https://www.nag.com>`__.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`2`)
The arithmetic precision is higher than that used for the Padé approximant computed matrix exponential.
.. _f01kg-py2-py-notes:
**Notes**
The Fréchet derivative of the matrix exponential of :math:`A` is the unique linear mapping :math:`E⟼L\left(A, E\right)` such that for any matrix :math:`E`
.. math::
e^{{A+E}}-e^A-L\left(A, E\right) = o\left(\left\lVert E\right\rVert \right)\text{.}
The derivative describes the first-order effect of perturbations in :math:`A` on the exponential :math:`e^A`.
The relative condition number of the matrix exponential can be defined by
.. math::
\kappa_{\mathrm{exp}}\left(A\right) = \frac{{\left\lVert L\left(A\right)\right\rVert \left\lVert A\right\rVert }}{\left\lVert \mathrm{exp}\left(A\right)\right\rVert }\text{,}
where :math:`\left\lVert L\left(A\right)\right\rVert` is the norm of the Fréchet derivative of the matrix exponential at :math:`A`.
To obtain the estimate of :math:`\kappa_{\mathrm{exp}}\left(A\right)`, ``complex_gen_matrix_cond_exp`` first estimates :math:`\left\lVert L\left(A\right)\right\rVert` by computing an estimate :math:`\gamma` of a quantity :math:`K \in \left[{n^{-1}\left\lVert L\left(A\right)\right\rVert_1}, {n\left\lVert L\left(A\right)\right\rVert_1}\right]`, such that :math:`\gamma \leq K`.
The algorithms used to compute :math:`\kappa_{\mathrm{exp}}\left(A\right)` are detailed in the Al--Mohy and Higham (2009a) and Al--Mohy and Higham (2009b).
The matrix exponential :math:`e^A` is computed using a Padé approximant and the scaling and squaring method.
The Padé approximant is differentiated to obtain the Fréchet derivatives :math:`L\left(A, E\right)` which are used to estimate the condition number.
.. _f01kg-py2-py-references:
**References**
Al--Mohy, A H and Higham, N J, 2009, `A new scaling and squaring algorithm for the matrix exponential`, SIAM J. Matrix Anal. (31(3)), 970--989
Al--Mohy, A H and Higham, N J, 2009, `Computing the Fréchet derivative of the matrix exponential, with an application to condition number estimation`, SIAM J. Matrix Anal. Appl. (30(4)), 1639--1657
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
Moler, C B and Van Loan, C F, 2003, `Nineteen dubious ways to compute the exponential of a matrix, twenty-five years later`, SIAM Rev. (45), 3--49
"""
raise NotImplementedError
[docs]def complex_gen_matrix_frcht_exp(a, e):
r"""
``complex_gen_matrix_frcht_exp`` computes the Fréchet derivative :math:`L\left(A, E\right)` of the matrix exponential of a complex :math:`n\times n` matrix :math:`A` applied to the complex :math:`n\times n` matrix :math:`E`.
The matrix exponential :math:`e^A` is also returned.
.. _f01kh-py2-py-doc:
For full information please refer to the NAG Library document for f01kh
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01khf.html
.. _f01kh-py2-py-parameters:
**Parameters**
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**e** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`E`
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix exponential :math:`e^A`.
**e** : complex, ndarray, shape :math:`\left(n, n\right)`
The Fréchet derivative :math:`L\left(A, E\right)`
.. _f01kh-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`1`)
The linear equations to be solved for the Padé approximant are singular; it is likely that this function has been called incorrectly.
(`errno` :math:`3`)
An unexpected internal error has occurred. Please contact `NAG <https://www.nag.com>`__.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`2`)
The arithmetic precision is higher than that used for the Padé approximant computed matrix exponential.
.. _f01kh-py2-py-notes:
**Notes**
The Fréchet derivative of the matrix exponential of :math:`A` is the unique linear mapping :math:`E⟼L\left(A, E\right)` such that for any matrix :math:`E`
.. math::
e^{{A+E}}-e^A-L\left(A, E\right) = o\left(\left\lVert E\right\rVert \right)\text{.}
The derivative describes the first-order effect of perturbations in :math:`A` on the exponential :math:`e^A`.
``complex_gen_matrix_frcht_exp`` uses the algorithms of Al--Mohy and Higham (2009a) and Al--Mohy and Higham (2009b) to compute :math:`e^A` and :math:`L\left(A, E\right)`.
The matrix exponential :math:`e^A` is computed using a Padé approximant and the scaling and squaring method.
The Padé approximant is then differentiated in order to obtain the Fréchet derivative :math:`L\left(A, E\right)`.
.. _f01kh-py2-py-references:
**References**
Al--Mohy, A H and Higham, N J, 2009, `A new scaling and squaring algorithm for the matrix exponential`, SIAM J. Matrix Anal. (31(3)), 970--989
Al--Mohy, A H and Higham, N J, 2009, `Computing the Fréchet derivative of the matrix exponential, with an application to condition number estimation`, SIAM J. Matrix Anal. Appl. (30(4)), 1639--1657
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
Moler, C B and Van Loan, C F, 2003, `Nineteen dubious ways to compute the exponential of a matrix, twenty-five years later`, SIAM Rev. (45), 3--49
"""
raise NotImplementedError
[docs]def complex_gen_matrix_cond_log(a):
r"""
``complex_gen_matrix_cond_log`` computes an estimate of the relative condition number :math:`\kappa_{\mathrm{log}}\left(A\right)` of the logarithm of a complex :math:`n\times n` matrix :math:`A`, in the :math:`1`-norm.
The principal matrix logarithm :math:`\log\left(A\right)` is also returned.
.. _f01kj-py2-py-doc:
For full information please refer to the NAG Library document for f01kj
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01kjf.html
.. _f01kj-py2-py-parameters:
**Parameters**
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` principal matrix logarithm, :math:`\log\left(A\right)`. Alternatively, if :math:`\mathrm{errno}` = 2, a non-principal logarithm is returned.
**condla** : float
With the function exits successfully or :math:`\mathrm{errno}` = 2 or 3, an estimate of the relative condition number of the matrix logarithm, :math:`\kappa_{\mathrm{log}}\left(A\right)`. Alternatively, if :math:`\mathrm{errno}` = 4, contains the absolute condition number of the matrix logarithm.
.. _f01kj-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`1`)
:math:`A` is singular so the logarithm cannot be computed.
(`errno` :math:`5`)
An unexpected internal error occurred. This failure should not occur and suggests that the function has been called incorrectly.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`2`)
:math:`A` has eigenvalues on the negative real line. The principal logarithm is not defined in this case, so a non-principal logarithm was returned.
(`errno` :math:`3`)
:math:`\log\left(A\right)` has been computed using an IEEE double precision Padé approximant, although the arithmetic precision is higher than IEEE double precision.
(`errno` :math:`4`)
The relative condition number is infinite. The absolute condition number was returned instead.
.. _f01kj-py2-py-notes:
**Notes**
For a matrix with no eigenvalues on the closed negative real line, the principal matrix logarithm :math:`\log\left(A\right)` is the unique logarithm whose spectrum lies in the strip :math:`\left\{{z:{-\pi } < \mathrm{Im}\left({\left(z\right) < \pi }\right)}\right\}`.
The Fréchet derivative of the matrix logarithm of :math:`A` is the unique linear mapping :math:`E⟼L\left(A, E\right)` such that for any matrix :math:`E`
.. math::
\log\left(A+E\right)-\log\left(A\right)-L\left(A, E\right) = o\left(\left\lVert E\right\rVert \right)\text{.}
The derivative describes the first order effect of perturbations in :math:`A` on the logarithm :math:`\log\left(A\right)`.
The relative condition number of the matrix logarithm can be defined by
.. math::
\kappa_{\mathrm{log}}\left(A\right) = \frac{{\left\lVert L\left(A\right)\right\rVert \left\lVert A\right\rVert }}{\left\lVert \log\left(A\right)\right\rVert }\text{,}
where :math:`\left\lVert L\left(A\right)\right\rVert` is the norm of the Fréchet derivative of the matrix logarithm at :math:`A`.
To obtain the estimate of :math:`\kappa_{\mathrm{log}}\left(A\right)`, ``complex_gen_matrix_cond_log`` first estimates :math:`\left\lVert L\left(A\right)\right\rVert` by computing an estimate :math:`\gamma` of a quantity :math:`K \in \left[{n^{-1}\left\lVert L\left(A\right)\right\rVert_1}, {n\left\lVert L\left(A\right)\right\rVert_1}\right]`, such that :math:`\gamma \leq K`.
The algorithms used to compute :math:`\kappa_{\mathrm{log}}\left(A\right)` and :math:`\log\left(A\right)` are based on a Schur decomposition, the inverse scaling and squaring method and Padé approximants.
Further details can be found in Al--Mohy and Higham (2011) and Al--Mohy `et al.` (2012).
If :math:`A` is nonsingular but has negative real eigenvalues, the principal logarithm is not defined, but ``complex_gen_matrix_cond_log`` will return a non-principal logarithm and its condition number.
.. _f01kj-py2-py-references:
**References**
Al--Mohy, A H and Higham, N J, 2011, `Improved inverse scaling and squaring algorithms for the matrix logarithm`, SIAM J. Sci. Comput. (34(4)), C152--C169
Al--Mohy, A H, Higham, N J and Relton, S D, 2012, `Computing the Fréchet derivative of the matrix logarithm and estimating the condition number`, SIAM J. Sci. Comput. (35(4)), C394--C410
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def complex_gen_matrix_frcht_log(a, e):
r"""
``complex_gen_matrix_frcht_log`` computes the Fréchet derivative :math:`L\left(A, E\right)` of the matrix logarithm of the complex :math:`n\times n` matrix :math:`A` applied to the complex :math:`n\times n` matrix :math:`E`.
The principal matrix logarithm :math:`\log\left(A\right)` is also returned.
.. _f01kk-py2-py-doc:
For full information please refer to the NAG Library document for f01kk
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01kkf.html
.. _f01kk-py2-py-parameters:
**Parameters**
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
**e** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`E`
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
The :math:`n\times n` principal matrix logarithm, :math:`\log\left(A\right)`. Alterntively, if :math:`\mathrm{errno}` = 2, a non-principal logarithm is returned.
**e** : complex, ndarray, shape :math:`\left(n, n\right)`
With the function exits successfully or :math:`\mathrm{errno}` = 2 or 3, the Fréchet derivative :math:`L\left(A, E\right)`
.. _f01kk-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`1`)
:math:`A` is singular so the logarithm cannot be computed.
(`errno` :math:`4`)
An unexpected internal error occurred. This failure should not occur and suggests that the function has been called incorrectly.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`2`)
:math:`A` has eigenvalues on the negative real line. The principal logarithm is not defined in this case, so a non-principal logarithm was returned.
(`errno` :math:`3`)
:math:`\log\left(A\right)` has been computed using an IEEE double precision Padé approximant, although the arithmetic precision is higher than IEEE double precision.
.. _f01kk-py2-py-notes:
**Notes**
For a matrix with no eigenvalues on the closed negative real line, the principal matrix logarithm :math:`\log\left(A\right)` is the unique logarithm whose spectrum lies in the strip :math:`\left\{{z:{-\pi } < \mathrm{Im}\left({\left(z\right) < \pi }\right)}\right\}`.
The Fréchet derivative of the matrix logarithm of :math:`A` is the unique linear mapping :math:`E⟼L\left(A, E\right)` such that for any matrix :math:`E`
.. math::
\log\left(A+E\right)-\log\left(A\right)-L\left(A, E\right) = o\left(\left\lVert E\right\rVert \right)\text{.}
The derivative describes the first order effect of perturbations in :math:`A` on the logarithm :math:`\log\left(A\right)`.
``complex_gen_matrix_frcht_log`` uses the algorithm of Al--Mohy `et al.` (2012) to compute :math:`\log\left(A\right)` and :math:`L\left(A, E\right)`.
The principal matrix logarithm :math:`\log\left(A\right)` is computed using a Schur decomposition, a Padé approximant and the inverse scaling and squaring method.
The Padé approximant is then differentiated in order to obtain the Fréchet derivative :math:`L\left(A, E\right)`.
If :math:`A` is nonsingular but has negative real eigenvalues, the principal logarithm is not defined, but ``complex_gen_matrix_frcht_log`` will return a non-principal logarithm and Fréchet derivative.
.. _f01kk-py2-py-references:
**References**
Al--Mohy, A H and Higham, N J, 2011, `Improved inverse scaling and squaring algorithms for the matrix logarithm`, SIAM J. Sci. Comput. (34(4)), C152--C169
Al--Mohy, A H, Higham, N J and Relton, S D, 2012, `Computing the Fréchet derivative of the matrix logarithm and estimating the condition number`, SIAM J. Sci. Comput. (35(4)), C394--C410
Higham, N J, 2008, `Functions of Matrices: Theory and Computation`, SIAM, Philadelphia, PA, USA
"""
raise NotImplementedError
[docs]def real_gen_tridiag_lu(a, lamda, b, c, tol):
r"""
``real_gen_tridiag_lu`` computes an :math:`LU` factorization of a real tridiagonal matrix, using Gaussian elimination with partial pivoting.
.. _f01le-py2-py-doc:
For full information please refer to the NAG Library document for f01le
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01lef.html
.. _f01le-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n\right)`
The diagonal elements of :math:`T`.
**lamda** : float
The scalar :math:`\lambda`. ``real_gen_tridiag_lu`` factorizes :math:`T-\lambda I`.
**b** : float, array-like, shape :math:`\left(n\right)`
The superdiagonal elements of :math:`T`, stored in :math:`\mathrm{b}[1]` to :math:`\mathrm{b}[n-1]`; :math:`\mathrm{b}[0]` is not used.
**c** : float, array-like, shape :math:`\left(n\right)`
The subdiagonal elements of :math:`T`, stored in :math:`\mathrm{c}[1]` to :math:`\mathrm{c}[n-1]`; :math:`\mathrm{c}[0]` is not used.
**tol** : float
A relative tolerance used to indicate whether or not the matrix (:math:`T-\lambda I`) is nearly singular. :math:`\mathrm{tol}` should normally be chosen as approximately the largest relative error in the elements of :math:`T`. For example, if the elements of :math:`T` are correct to about :math:`4` significant figures, then :math:`\mathrm{tol}` should be set to about :math:`5\times 10^{-4}`. See `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01lef.html#fcomments>`__ for further details on how :math:`\mathrm{tol}` is used. If :math:`\mathrm{tol}` is supplied as less than :math:`\epsilon`, where :math:`\epsilon` is the machine precision, then the value :math:`\epsilon` is used in place of :math:`\mathrm{tol}`.
**Returns**
**a** : float, ndarray, shape :math:`\left(n\right)`
The diagonal elements of the upper triangular matrix :math:`U`.
**b** : float, ndarray, shape :math:`\left(n\right)`
The elements of the first superdiagonal of :math:`U`, stored in :math:`\mathrm{b}[1]` to :math:`\mathrm{b}[n-1]`.
**c** : float, ndarray, shape :math:`\left(n\right)`
The subdiagonal elements of :math:`L`, stored in :math:`\mathrm{c}[1]` to :math:`\mathrm{c}[n-1]`.
**d** : float, ndarray, shape :math:`\left(n\right)`
The elements of the second superdiagonal of :math:`U`, stored in :math:`\mathrm{d}[2]` to :math:`\mathrm{d}[n-1]`; :math:`\mathrm{d}[0]` and :math:`\mathrm{d}[1]` are not used.
**ipiv** : int, ndarray, shape :math:`\left(n\right)`
Details of the permutation matrix :math:`P`. If an interchange occurred at the :math:`k`\ th step of the elimination, then :math:`\mathrm{ipiv}[k-1] = 1`, otherwise :math:`\mathrm{ipiv}[k-1] = 0`. If a diagonal element of :math:`U` is small, indicating that :math:`\left(T-\lambda I\right)` is nearly singular, then the element :math:`\mathrm{ipiv}[n-1]` is returned as positive. Otherwise :math:`\mathrm{ipiv}[n-1]` is returned as :math:`0`. See `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01lef.html#fcomments>`__ for further details. If the application is such that it is important that :math:`\left(T-\lambda I\right)` is not nearly singular, then it is strongly recommended that :math:`\mathrm{ipiv}[n-1]` is inspected on return.
.. _f01le-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 1`.
.. _f01le-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
The matrix :math:`T-\lambda I`, where :math:`T` is a real :math:`n\times n` tridiagonal matrix, is factorized as
.. math::
T-\lambda I = PLU\text{,}
where :math:`P` is a permutation matrix, :math:`L` is a unit lower triangular matrix with at most one nonzero subdiagonal element per column, and :math:`U` is an upper triangular matrix with at most two nonzero superdiagonal elements per column.
The factorization is obtained by Gaussian elimination with partial pivoting and implicit row scaling.
An indication of whether or not the matrix :math:`T-\lambda I` is nearly singular is returned in the :math:`n`\ th element of the array :math:`\mathrm{ipiv}`.
If it is important that :math:`T-\lambda I` is nonsingular, as is usually the case when solving a system of tridiagonal equations, then it is strongly recommended that :math:`\mathrm{ipiv}[n-1]` is inspected on return from ``real_gen_tridiag_lu``. (See the argument :math:`\mathrm{ipiv}` and `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01lef.html#fcomments>`__ for further details.)
The argument :math:`\lambda` is included in the function so that ``real_gen_tridiag_lu`` may be used, in conjunction with :meth:`linsys.real_tridiag_fac_solve <naginterfaces.library.linsys.real_tridiag_fac_solve>`, to obtain eigenvectors of :math:`T` by inverse iteration.
.. _f01le-py2-py-references:
**References**
Wilkinson, J H, 1965, `The Algebraic Eigenvalue Problem`, Oxford University Press, Oxford
Wilkinson, J H and Reinsch, C, 1971, `Handbook for Automatic Computation II, Linear Algebra`, Springer--Verlag
"""
raise NotImplementedError
[docs]def real_gen_blkdiag_lu(n, blkstr, a, tol):
r"""
``real_gen_blkdiag_lu`` factorizes a real almost block diagonal matrix.
.. _f01lh-py2-py-doc:
For full information please refer to the NAG Library document for f01lh
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01lhf.html
.. _f01lh-py2-py-parameters:
**Parameters**
**n** : int
:math:`n`, the order of the matrix :math:`A`.
**blkstr** : int, array-like, shape :math:`\left(3, \textit{nbloks}\right)`
Information which describes the block structure of :math:`A` as follows:
:math:`\mathrm{blkstr}[0,k-1]` must contain the number of rows in the :math:`k`\ th block, :math:`k = 1,2,\ldots,\textit{nbloks}`;
:math:`\mathrm{blkstr}[1,k-1]` must contain the number of columns in the :math:`k`\ th block, :math:`k = 1,2,\ldots,\textit{nbloks}`;
:math:`\mathrm{blkstr}[2,k-1]` must contain the number of columns of overlap between the :math:`k`\ th and :math:`\left(k+1\right)`\ th blocks, :math:`k = 1,2,\ldots,\textit{nbloks}-1`. :math:`\mathrm{blkstr}[2,\textit{nbloks}-1]` need not be set.
The following conditions delimit the structure of :math:`A`:
:math:`\mathrm{blkstr}[0,k-1],\mathrm{blkstr}[1,k-1] > 0\text{, }\quad k = 1,2,\ldots,\textit{nbloks}`,
:math:`\mathrm{blkstr}[2,k-1]\geq 0\text{, }\quad k = 1,2,\ldots,\textit{nbloks}-1`,
(there must be at least one column and one row in each block and a non-negative number of columns of overlap);
:math:`\mathrm{blkstr}[2,k-2]+\mathrm{blkstr}[2,k-1]\leq \mathrm{blkstr}[1,k-1]\text{, }\quad k = 2,3,\ldots,\textit{nbloks}-1`,
(the total number of columns in overlaps in each block must not exceed the number of columns in that block);
:math:`\mathrm{blkstr}[1,0]\geq \mathrm{blkstr}[0,0]`,
:math:`\mathrm{blkstr}[1,0]+\sum_{{k = 2}}^j\left[\mathrm{blkstr}[1,k -1]-\mathrm{blkstr}[2,k -1 -1]\right]\geq \sum_{{k = 1}}^j\mathrm{blkstr}[0,k -1]`, :math:`j = 2,3,\ldots,\textit{nbloks}-1`,
:math:`\sum_{{k = 1}}^j\left[\mathrm{blkstr}[1,k-1]-\mathrm{blkstr}[2,k-1]\right]\leq \sum_{{k = 1}}^j\mathrm{blkstr}[0,k-1]\text{, }\quad j = 1,2,\ldots,\textit{nbloks}-1`,
(the index of the first column of the overlap between the :math:`j`\ th and :math:`\left(j+1\right)`\ th blocks must be :math:`\leq` the index of the last row of the :math:`j`\ th block, and the index of the last column of overlap must be :math:`\geq` the index of the last row of the :math:`j`\ th block);
:math:`\sum_{{k = 1}}^{\textit{nbloks}}\mathrm{blkstr}[0,k -1] = n`,
:math:`\mathrm{blkstr}[1,0]+\sum_{{k = 2}}^{\textit{nbloks}}\left[\mathrm{blkstr}[1,k -1]-\mathrm{blkstr}[2,k -1 -1]\right] = nk`,
(both the number of rows and the number of columns of :math:`A` must equal :math:`n`).
**a** : float, array-like, shape :math:`\left(\textit{lena}\right)`
The elements of the almost block diagonal matrix stored block by block, with each block stored column by column. The sizes of the blocks and the overlaps are defined by the argument :math:`\mathrm{blkstr}`.
If :math:`a_{{rs}}` is the first element in the :math:`k`\ th block, then an arbitrary element :math:`a_{{ij}}` in the :math:`k`\ th block must be stored in the array element:
.. math::
\mathrm{a}[ p_k + \left(j-r\right) m_k + \left(i-s\right)+1 -1]
where
.. math::
p_k = \sum_{{l = 1}}^{{k-1}}\mathrm{blkstr}[0,l-1]\times \mathrm{blkstr}[1,l-1]
is the base address of the :math:`k`\ th block, and
.. math::
m_k = \mathrm{blkstr}[0,k-1]
is the number of rows of the :math:`k`\ th block.
See `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01lhf.html#fcomments>`__ for comments on scaling.
**tol** : float
A relative tolerance to be used to indicate whether or not the matrix is singular. For a discussion on how :math:`\mathrm{tol}` is used see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01lhf.html#fcomments>`__. If :math:`\mathrm{tol}` is non-positive, :math:`\mathrm{tol}` is reset to :math:`10\epsilon`, where :math:`\epsilon` is the machine precision.
**Returns**
**a** : float, ndarray, shape :math:`\left(\textit{lena}\right)`
The factorized form of the matrix.
**pivot** : int, ndarray, shape :math:`\left(\mathrm{n}\right)`
Details of the interchanges.
**tol** : float
Unchanged unless :math:`\mathrm{tol}\leq 0.0` on entry, in which case it is set to :math:`10\epsilon`.
**kpivot** : int
If :math:`\mathrm{errno}` = 2, :math:`\mathrm{kpivot}` contains the value :math:`k`, where :math:`k` is the first position on the diagonal of the matrix :math:`A` where too small a pivot was detected. Otherwise :math:`\mathrm{kpivot}` is set to :math:`0`.
.. _f01lh-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\textit{lena}` is too small. :math:`\textit{lena} = \langle\mathit{\boldsymbol{value}}\rangle`. Minimum possible dimension: :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`1`)
On entry, the following equality does not hold: :math:`\mathrm{blkstr}[1,0]+\mathrm{sum}\left({\mathrm{blkstr}[1,k-1]-\mathrm{blkstr}[2,k-2]:k = 2}, \textit{nbloks}\right) = \mathrm{n}`.
(`errno` :math:`1`)
On entry, the following equality does not hold: :math:`\mathrm{sum}\left({\mathrm{blkstr}[0,k-1]:k = 1}, \textit{nbloks}\right) = \mathrm{n}`.
(`errno` :math:`1`)
On entry, :math:`K = \langle\mathit{\boldsymbol{value}}\rangle` :math:`\mathrm{blkstr}[2,K-1] = \langle\mathit{\boldsymbol{value}}\rangle` :math:`\mathrm{blkstr}[2,K-2] = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{blkstr}[1,K-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{blkstr}[2,K-1]+\mathrm{blkstr}[2,K-2]\geq \mathrm{blkstr}[1,K-1]`.
(`errno` :math:`1`)
On entry, the following inequality was not satisfied for: :math:`J = \langle\mathit{\boldsymbol{value}}\rangle`. :math:`\mathrm{sum}\left({\mathrm{blkstr}[1,k-1]-\mathrm{blkstr}[2,k-1]:k = 1}, J\right)\leq \text{}` :math:`\mathrm{sum}\left({\mathrm{blkstr}[0,k-1]:k = 1}, J\right)\leq \text{}` :math:`\mathrm{blkstr}[1,0]+\mathrm{sum}\left({\mathrm{blkstr}[1,k-1]-\mathrm{blkstr}[2,k-2]:k = 2}, J\right)`.
(`errno` :math:`1`)
On entry, :math:`K = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{blkstr}[1,K-1] = \langle\mathit{\boldsymbol{value}}\rangle` :math:`\mathrm{blkstr}[2,K-1] = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{blkstr}[0,K-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{blkstr}[1,K-1]-\mathrm{blkstr}[2,K-1]\leq \mathrm{blkstr}[0,K-1]`.
(`errno` :math:`1`)
On entry, :math:`K = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{blkstr}[1,K-1] = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{blkstr}[0,K-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{blkstr}[1,K-1]\geq \mathrm{blkstr}[0,K-1]`.
(`errno` :math:`1`)
On entry, :math:`K = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{blkstr}[2,K-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{blkstr}[2,K-1]\geq 0`.
(`errno` :math:`1`)
On entry, :math:`K = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{blkstr}[1,K-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{blkstr}[1,K-1]\geq 1`.
(`errno` :math:`1`)
On entry, :math:`K = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{blkstr}[0,K-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{blkstr}[0,K-1]\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{nbloks} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{n}\geq \textit{nbloks}`.
(`errno` :math:`1`)
On entry, :math:`\textit{nbloks} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{nbloks}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{n}\geq 1`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`2`)
Factorization completed, but pivot in diagonal :math:`I` was small: :math:`I = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _f01lh-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``real_gen_blkdiag_lu`` factorizes a real almost block diagonal matrix, :math:`A`, by row elimination with alternate row and column pivoting such that no 'fill-in' is produced.
The code, which is derived from ARCECO described in Diaz `et al.` (1983), uses Level 1 and Level 2 BLAS.
No three successive diagonal blocks may have columns in common and, therefore, the almost block diagonal matrix must have the form shown in the following diagram:
[figure omitted]
This function may be followed by :meth:`linsys.real_blkdiag_fac_solve <naginterfaces.library.linsys.real_blkdiag_fac_solve>`, which is designed to solve sets of linear equations :math:`AX = B` or :math:`A^\mathrm{T}X = B`.
.. _f01lh-py2-py-references:
**References**
Diaz, J C, Fairweather, G and Keast, P, 1983, `Fortran packages for solving certain almost block diagonal linear systems by modified alternate row and column elimination`, ACM Trans. Math. Software (9), 358--375
"""
raise NotImplementedError
[docs]def real_vband_posdef_fac(a, nrow):
r"""
``real_vband_posdef_fac`` computes the Cholesky factorization of a real symmetric positive definite variable-bandwidth matrix.
.. _f01mc-py2-py-doc:
For full information please refer to the NAG Library document for f01mc
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01mcf.html
.. _f01mc-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(\textit{lal}\right)`
The elements within the envelope of the lower triangle of the positive definite symmetric matrix :math:`A`, taken in row by row order. The matrix elements within the band can be assigned to the correct elements of the array using the following logic:
set :math:`k = 0`
loop for :math:`i = 1` to :math:`\textit{n}`
loop for :math:`j = i-\mathrm{nrow}[i-1]+1` to :math:`i`
set :math:`k = k+1`
set :math:`\mathrm{a}[k-1] = A_{{ij}}`
where :math:`A_{{ij}}` is the element in the :math:`i`\ th row and :math:`j`\ th column of the matrix :math:`A`.
See also `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01mcf.html#fcomments>`__.
**nrow** : int, array-like, shape :math:`\left(n\right)`
:math:`\mathrm{nrow}[i-1]` must contain the width of row :math:`i` of the matrix :math:`A`, i.e., the number of elements between the first (leftmost) nonzero element and the element on the diagonal, inclusive.
**Returns**
**al** : float, ndarray, shape :math:`\left(\textit{lal}\right)`
The elements within the envelope of the lower triangular matrix :math:`L`, taken in row by row order. The envelope of :math:`L` is identical to that of the lower triangle of :math:`A`. The unit diagonal elements of :math:`L` are stored explicitly. See also `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01mcf.html#fcomments>`__.
**d** : float, ndarray, shape :math:`\left(n\right)`
The diagonal elements of the diagonal matrix :math:`D`. Note that the determinant of :math:`A` is equal to the product of these diagonal elements. If the value of the determinant is required it should not be determined by forming the product explicitly, because of the possibility of overflow or underflow. The logarithm of the determinant may safely be formed from the sum of the logarithms of the diagonal elements.
.. _f01mc-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\textit{lal} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{nrow}[0] + \cdots +\mathrm{nrow}[n-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{lal}\geq \mathrm{nrow}[0] + \cdots +\mathrm{nrow}[n-1]`.
(`errno` :math:`1`)
On entry, :math:`I = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{nrow}[I-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nrow}[I-1]\geq 1` and :math:`\mathrm{nrow}[I-1]\leq I`.
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 1`.
(`errno` :math:`2`)
:math:`A` is not positive definite. Factorization abandoned.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`3`)
:math:`A` is not positive definite. Factorization completed.
.. _f01mc-py2-py-notes:
**Notes**
`In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.`
``real_vband_posdef_fac`` determines the unit lower triangular matrix :math:`L` and the diagonal matrix :math:`D` in the Cholesky factorization :math:`A = LDL^\mathrm{T}` of a symmetric positive definite variable-bandwidth matrix :math:`A` of order :math:`n`. (Such a matrix is sometimes called a 'sky-line' matrix.)
The matrix :math:`A` is represented by the elements lying within the **envelope** of its lower triangular part, that is, between the first nonzero of each row and the diagonal.
The **width** :math:`\mathrm{nrow}[i-1]` of the :math:`i`\ th row is the number of elements between the first nonzero element and the element on the diagonal, inclusive.
Although, of course, any matrix possesses an envelope as defined, this function is primarily intended for the factorization of symmetric positive definite matrices with an **average** bandwidth which is small compared with :math:`n` (also see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01mcf.html#fcomments>`__).
The method is based on the property that during Cholesky factorization there is no fill-in outside the envelope.
The determination of :math:`L` and :math:`D` is normally the first of two steps in the solution of the system of equations :math:`Ax = b`.
The remaining step, viz. the solution of :math:`LDL^\mathrm{T}x = b`, may be carried out using :meth:`linsys.real_posdef_vband_solve <naginterfaces.library.linsys.real_posdef_vband_solve>`.
.. _f01mc-py2-py-references:
**References**
Jennings, A, 1966, `A compact storage scheme for the solution of symmetric linear simultaneous equations`, Comput. J. (9), 281--285
Wilkinson, J H and Reinsch, C, 1971, `Handbook for Automatic Computation II, Linear Algebra`, Springer--Verlag
"""
raise NotImplementedError
[docs]def real_modified_cholesky(uplo, a, delta):
r"""
``real_modified_cholesky`` computes the Cheng--Higham modified Cholesky factorization of a real symmetric matrix.
.. _f01md-py2-py-doc:
For full information please refer to the NAG Library document for f01md
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01mdf.html
.. _f01md-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized.
:math:`\mathrm{uplo} = \texttt{'U'}`
The upper triangular part of :math:`A` is stored and we compute :math:`P^\mathrm{T}\left(A+E\right)P = UDU^\mathrm{T}`.
:math:`\mathrm{uplo} = \texttt{'L'}`
The lower triangular part of :math:`A` is stored and we compute :math:`P^\mathrm{T}\left(A+E\right)P = LDL^\mathrm{T}`.
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` symmetric matrix :math:`A`.
**delta** : float
The value of :math:`\delta`.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
:math:`\mathrm{a}` is overwritten.
See `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01mdf.html#fcomments>`__ for further details.
**offdiag** : float, ndarray, shape :math:`\left(n\right)`
The offdiagonals of the symmetric matrix :math:`D` are returned in :math:`\mathrm{offdiag}[0],\mathrm{offdiag}[1],\ldots,\mathrm{offdiag}[n-2]`, for :math:`\mathrm{uplo} = \texttt{'L'}` and in :math:`\mathrm{offdiag}[1],\mathrm{offdiag}[2],\ldots,\mathrm{offdiag}[n-1]`, for :math:`\mathrm{uplo} = \texttt{'U'}`. See `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01mdf.html#fcomments>`__ for further details.
**ipiv** : int, ndarray, shape :math:`\left(n\right)`
Gives the permutation information of the factorization. The entries of :math:`\mathrm{ipiv}` are either positive, indicating a :math:`1\times 1` pivot block, or pairs of negative entries, indicating a :math:`2\times 2` pivot block.
:math:`\mathrm{ipiv}[i-1] = k > 0`
The :math:`i`\ th and :math:`k`\ th rows and columns of :math:`A` were interchanged and :math:`d_{{ii}}` is a :math:`1\times 1` block.
:math:`\mathrm{ipiv}[i-1] = {-k} < 0` and :math:`\mathrm{ipiv}[{i+1}-1] = {-\ell } < 0`
The :math:`i`\ th and :math:`k`\ th rows and columns, and the :math:`i+1`\ st and :math:`\ell`\ th rows and columns, were interchanged and :math:`D` has the :math:`2\times 2` block:
.. math::
\begin{pmatrix}d_{{ii}}&d_{{i+1,i}}\\d_{{i+1,i}}&d_{{i+1,i+1}}\end{pmatrix}
If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`d_{{i+1,i}}` is stored in :math:`\mathrm{offdiag}[i]`. The interchanges were made in the order :math:`i = n,n-1,\ldots,2`.
If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`d_{{i+1,i}}` is stored in :math:`\mathrm{offdiag}[i-1]`. The interchanges were made in the order :math:`i = 1,2,\ldots,n-1`.
.. _f01md-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{uplo} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`2`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n > 0`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{delta} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{delta}\geq 0.0`.
(`errno` :math:`5`)
An intermediate eigenproblem could not be solved. This should not occur. Please contact `NAG <https://www.nag.com>`__ with details of your call.
.. _f01md-py2-py-notes:
**Notes**
Given a symmetric, possibly indefinite matrix :math:`A`, ``real_modified_cholesky`` finds the Cheng--Higham modified Cholesky factorization
.. math::
P^\mathrm{T}\left(A+E\right)P = {LDL^\mathrm{T}}\text{,}
when :math:`\mathrm{uplo} = \texttt{'L'}`.
Here :math:`L` is a unit lower triangular matrix, :math:`P` is a permutation matrix, :math:`D` is a symmetric block diagonal matrix (with blocks of order :math:`1` or :math:`2`) with minimum eigenvalue :math:`\delta`, and :math:`E` is a perturbation matrix of small norm chosen so that such a factorization can be found.
Note that :math:`E` is not computed explicitly.
If :math:`\mathrm{uplo} = \texttt{'U'}`, we compute the factorization :math:`P^\mathrm{T}\left(A+E\right)P = {UDU^\mathrm{T}}`, where :math:`U` is a unit upper triangular matrix.
If the matrix :math:`A` is symmetric positive definite, the algorithm ensures that :math:`E = 0`.
The function :meth:`real_mod_chol_perturbed_a` can be used to compute the matrix :math:`A+E`.
.. _f01md-py2-py-references:
**References**
Ashcraft, C, Grimes, R G, and Lewis, J G, 1998, `Accurate symmetric indefinite linear equation solvers`, SIAM J. Matrix Anal. Appl. (20), 513--561
Cheng, S H and Higham, N J, 1998, `A modified Cholesky algorithm based on a symmetric indefinite factorization`, SIAM J. Matrix Anal. Appl. (19(4)), 1097--1110
"""
raise NotImplementedError
[docs]def real_mod_chol_perturbed_a(uplo, a, offdiag, ipiv):
r"""
``real_mod_chol_perturbed_a`` computes the positive definite perturbed matrix :math:`A+E` from the factors of a modified Cholesky factorization of a real symmetric matrix, :math:`A`.
.. _f01me-py2-py-doc:
For full information please refer to the NAG Library document for f01me
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01mef.html
.. _f01me-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Indicates whether the upper or lower triangular part of :math:`A` was stored and how it was factorized.
:math:`\mathrm{uplo} = \texttt{'U'}`
The upper triangular part of :math:`A` was stored and we compute :math:`A+E` such that :math:`P^\mathrm{T}\left(A+E\right)P = UDU^\mathrm{T}`.
:math:`\mathrm{uplo} = \texttt{'L'}`
The lower triangular part of :math:`A` was stored and we compute :math:`A+E` such that :math:`P^\mathrm{T}\left(A+E\right)P = LDL^\mathrm{T}`.
**a** : float, array-like, shape :math:`\left(n, n\right)`
The modified Cholesky factor of :math:`A`, as returned by :meth:`real_modified_cholesky`.
**offdiag** : float, array-like, shape :math:`\left(n\right)`
The array :math:`\textit{offdiag}` as returned by :meth:`real_modified_cholesky`.
**ipiv** : int, array-like, shape :math:`\left(n\right)`
The array :math:`\textit{ipiv}` as returned by :meth:`real_modified_cholesky`.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangular part of :math:`A+E` is returned and the elements of the array below the diagonal are not referenced.
If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangular part of :math:`A+E` is returned and the elements of the array above the diagonal are not referenced.
.. _f01me-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{uplo} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`2`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n > 0`.
.. _f01me-py2-py-notes:
**Notes**
``real_mod_chol_perturbed_a`` computes the positive definite perturbed matrix :math:`A+E` from the factors provided by a previous call to :meth:`real_modified_cholesky`.
For a symmetric, possibly indefinite matrix :math:`A`, :meth:`real_modified_cholesky` finds the Cheng--Higham modified Cholesky factorization
.. math::
P^\mathrm{T}\left(A+E\right)P = {LDL^\mathrm{T}}\text{,}
when :math:`\mathrm{uplo} = \texttt{'L'}`.
Here :math:`L` is a unit lower triangular matrix, :math:`P` is a permutation matrix, :math:`D` is a symmetric block diagonal matrix (with blocks of order :math:`1` or :math:`2`).
The matrix :math:`E` is not explicitly formed.
If :math:`\mathrm{uplo} = \texttt{'U'}`, we compute :math:`A+E` from the factorization :math:`P^\mathrm{T}\left(A+E\right)P = {UDU^\mathrm{T}}`, where :math:`U` is a unit upper triangular matrix.
.. _f01me-py2-py-references:
**References**
Cheng, S H and Higham, N J, 1998, `A modified Cholesky algorithm based on a symmetric indefinite factorization`, SIAM J. Matrix Anal. Appl. (19(4)), 1097--1110
"""
raise NotImplementedError
[docs]def real_trapez_rq(m, a):
r"""
``real_trapez_rq`` reduces the :math:`m\times n` (:math:`m\leq n`) real upper trapezoidal matrix :math:`A` to upper triangular form by means of orthogonal transformations.
.. _f01qg-py2-py-doc:
For full information please refer to the NAG Library document for f01qg
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01qgf.html
.. _f01qg-py2-py-parameters:
**Parameters**
**m** : int
:math:`m`, the number of rows of the matrix :math:`A`.
When :math:`\mathrm{m} = 0` then an immediate return is effected.
**a** : float, array-like, shape :math:`\left(\mathrm{m}, n\right)`
The leading :math:`m\times n` upper trapezoidal part of the array :math:`\mathrm{a}` must contain the matrix to be factorized.
**Returns**
**a** : float, ndarray, shape :math:`\left(\mathrm{m}, n\right)`
The :math:`m\times m` upper triangular part of :math:`\mathrm{a}` will contain the upper triangular matrix :math:`R`, and the :math:`m\times \left(n-m\right)` upper trapezoidal part of :math:`\mathrm{a}` will contain details of the factorization as described in :ref:`Notes <f01qg-py2-py-notes>`.
**zeta** : float, ndarray, shape :math:`\left(\mathrm{m}\right)`
:math:`\mathrm{zeta}[k-1]` contains the scalar :math:`\zeta_k` for the :math:`\left(m-k+1\right)`\ th transformation. If :math:`T_k = I` then :math:`\mathrm{zeta}[k-1] = 0.0`, otherwise :math:`\mathrm{zeta}[k-1]` contains :math:`\zeta_k` as described in :ref:`Notes <f01qg-py2-py-notes>` and :math:`\zeta_k` is always in the range :math:`\left(1.0,\sqrt{2.0}\right)`.
.. _f01qg-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq \mathrm{m}`.
(`errno` :math:`-1`)
On entry, :math:`\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m}\geq 0`.
.. _f01qg-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
The :math:`m\times n` (:math:`m\leq n`) real upper trapezoidal matrix :math:`A` given by
.. math::
A = \begin{pmatrix}U&X\end{pmatrix}\text{,}
where :math:`U` is an :math:`m\times m` upper triangular matrix, is factorized as
.. math::
A = \begin{pmatrix}R&0\end{pmatrix}P^{\mathrm{T}}\text{,}
where :math:`P` is an :math:`n\times n` orthogonal matrix and :math:`R` is an :math:`m\times m` upper triangular matrix.
:math:`P` is given as a sequence of Householder transformation matrices
.. math::
P = P_m \cdots P_2P_1\text{,}
the :math:`\left(m-k+1\right)`\ th transformation matrix, :math:`P_k`, being used to introduce zeros into the :math:`k`\ th row of :math:`A`. :math:`P_k` has the form
.. math::
P_k = \begin{pmatrix}I&0\\0&T_k\end{pmatrix}\text{,}
where
.. math::
\begin{array}{c}T_k = I-u_ku_k^{\mathrm{T}}\text{,}\\\\u_k = \begin{pmatrix}\zeta_k\\0\\z_k\end{pmatrix}\text{,}\end{array}
:math:`\zeta_k` is a scalar and :math:`z_k` is an (:math:`n-m`) element vector. :math:`\zeta_k` and :math:`z_k` are chosen to annihilate the elements of the :math:`k`\ th row of :math:`X`.
The vector :math:`u_k` is returned in the :math:`k`\ th element of the array :math:`\mathrm{zeta}` and in the :math:`k`\ th row of :math:`\mathrm{a}`, such that :math:`\zeta_k` is in :math:`\mathrm{zeta}[k-1]` and the elements of :math:`z_k` are in :math:`\mathrm{a}[k-1,m],\ldots,\mathrm{a}[k-1,n-1]`.
The elements of :math:`R` are returned in the upper triangular part of :math:`\mathrm{a}`.
For further information on this factorization and its use see Section 6.5 of Golub and Van Loan (1996).
.. _f01qg-py2-py-references:
**References**
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
Wilkinson, J H, 1965, `The Algebraic Eigenvalue Problem`, Oxford University Press, Oxford
"""
raise NotImplementedError
[docs]def real_gen_rq(m, a):
r"""
``real_gen_rq`` finds the :math:`RQ` factorization of the real :math:`m\times n` (:math:`m\leq n`) matrix :math:`A`, so that :math:`A` is reduced to upper triangular form by means of orthogonal transformations from the right.
.. _f01qj-py2-py-doc:
For full information please refer to the NAG Library document for f01qj
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01qjf.html
.. _f01qj-py2-py-parameters:
**Parameters**
**m** : int
:math:`m`, the number of rows of the matrix :math:`A`.
When :math:`\mathrm{m} = 0` then an immediate return is effected.
**a** : float, array-like, shape :math:`\left(\mathrm{m}, n\right)`
The leading :math:`m\times n` part of the array :math:`\mathrm{a}` must contain the matrix to be factorized.
**Returns**
**a** : float, ndarray, shape :math:`\left(\mathrm{m}, n\right)`
The :math:`m\times m` upper triangular part of :math:`\mathrm{a}` will contain the upper triangular matrix :math:`R`, and the :math:`m\times m` strictly lower triangular part of :math:`\mathrm{a}` and the :math:`m\times \left(n-m\right)` rectangular part of :math:`\mathrm{a}` to the right of the upper triangular part will contain details of the factorization as described in :ref:`Notes <f01qj-py2-py-notes>`.
**zeta** : float, ndarray, shape :math:`\left(\mathrm{m}\right)`
:math:`\mathrm{zeta}[k-1]` contains the scalar :math:`\zeta_k` for the :math:`\left(m-k+1\right)`\ th transformation. If :math:`P_k = I` then :math:`\mathrm{zeta}[k-1] = 0.0`, otherwise :math:`\mathrm{zeta}[k-1]` contains :math:`\zeta_k` as described in :ref:`Notes <f01qj-py2-py-notes>` and :math:`\zeta_k` is always in the range :math:`\left(1.0, {\sqrt{2.0}}\right)`.
.. _f01qj-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq \mathrm{m}`.
(`errno` :math:`-1`)
On entry, :math:`\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m}\geq 0`.
.. _f01qj-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
The :math:`m\times n` matrix :math:`A` is factorized as
.. math::
\begin{array}{ll}A = \begin{pmatrix}R&0\end{pmatrix} P^{\mathrm{T}}&\text{when }m < n\text{,}\\&\\A = RP^{\mathrm{T}}&\text{when }m = n\text{,}\end{array}
where :math:`P` is an :math:`n\times n` orthogonal matrix and :math:`R` is an :math:`m\times m` upper triangular matrix.
:math:`P` is given as a sequence of Householder transformation matrices
.. math::
P = P_m\ldots P_2P_1\text{,}
the (:math:`m-k+1`)th transformation matrix, :math:`P_k`, being used to introduce zeros into the :math:`k`\ th row of :math:`A`. :math:`P_k` has the form
.. math::
P_k = I-u_ku_k^{\mathrm{T}}\text{,}
where
.. math::
u_k = \begin{pmatrix}w_k\\\zeta_k\\0\\z_k\end{pmatrix}\text{,}
:math:`\zeta_k` is a scalar, :math:`w_k` is an :math:`\left(k-1\right)` element vector and :math:`z_k` is an :math:`\left(n-m\right)` element vector. :math:`u_k` is chosen to annihilate the elements in the :math:`k`\ th row of :math:`A`.
The vector :math:`u_k` is returned in the :math:`k`\ th element of :math:`\mathrm{zeta}` and in the :math:`k`\ th row of :math:`\mathrm{a}`, such that :math:`\zeta_k` is in :math:`\mathrm{zeta}[k-1]`, the elements of :math:`w_k` are in :math:`\mathrm{a}[k-1,0],\ldots,\mathrm{a}[k-1,k-2]` and the elements of :math:`z_k` are in :math:`\mathrm{a}[k-1,m],\ldots,\mathrm{a}[k-1,n-1]`.
The elements of :math:`R` are returned in the upper triangular part of :math:`\mathrm{a}`.
.. _f01qj-py2-py-references:
**References**
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
Wilkinson, J H, 1965, `The Algebraic Eigenvalue Problem`, Oxford University Press, Oxford
"""
raise NotImplementedError
[docs]def complex_trapez_rq(m, a):
r"""
``complex_trapez_rq`` reduces the complex :math:`m\times n` (:math:`m\leq n`) upper trapezoidal matrix :math:`A` to upper triangular form by means of unitary transformations.
.. _f01rg-py2-py-doc:
For full information please refer to the NAG Library document for f01rg
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01rgf.html
.. _f01rg-py2-py-parameters:
**Parameters**
**m** : int
:math:`m`, the number of rows of the matrix :math:`A`.
When :math:`\mathrm{m} = 0` then an immediate return is effected.
**a** : complex, array-like, shape :math:`\left(\mathrm{m}, n\right)`
The leading :math:`m\times n` upper trapezoidal part of the array :math:`\mathrm{a}` must contain the matrix to be factorized.
**Returns**
**a** : complex, ndarray, shape :math:`\left(\mathrm{m}, n\right)`
The :math:`m\times m` upper triangular part of :math:`\mathrm{a}` will contain the upper triangular matrix :math:`R`, and the :math:`m\times \left(n-m\right)` upper trapezoidal part of :math:`\mathrm{a}` will contain details of the factorization as described in :ref:`Notes <f01rg-py2-py-notes>`.
**theta** : complex, ndarray, shape :math:`\left(\mathrm{m}\right)`
:math:`\mathrm{theta}[k-1]` contains the scalar :math:`\theta_k` for the :math:`\left(m-k+1\right)`\ th transformation. If :math:`T_k = I` then :math:`\mathrm{theta}[k-1] = 0.0`; if
.. math::
T_k = \begin{pmatrix}\alpha &0\\0&I\end{pmatrix}\text{, }\quad \mathrm{Re}\left(\alpha \right) < 0.0
then :math:`\mathrm{theta}[k-1] = \alpha`, otherwise :math:`\mathrm{theta}[k-1]` contains :math:`\theta_k` as described in :ref:`Notes <f01rg-py2-py-notes>` and :math:`\mathrm{Re}\left(\theta_k\right)` is always in the range :math:`\left(1.0, {\sqrt{2.0}}\right)`.
.. _f01rg-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq \mathrm{m}`.
(`errno` :math:`-1`)
On entry, :math:`\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m}\geq 0`.
.. _f01rg-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
The :math:`m\times n\left(m\leq n\right)` upper trapezoidal matrix :math:`A` given by
.. math::
A = \begin{pmatrix}U&X\end{pmatrix}\text{,}
where :math:`U` is an :math:`m\times m` upper triangular matrix, is factorized as
.. math::
A = \begin{pmatrix}R&0\end{pmatrix}P^\mathrm{H}\text{,}
where :math:`P` is an :math:`n\times n` unitary matrix and :math:`R` is an :math:`m\times m` upper triangular matrix.
:math:`P` is given as a sequence of Householder transformation matrices
.. math::
P = P_m \cdots P_2P_1\text{,}
the :math:`\left(m-k+1\right)`\ th transformation matrix, :math:`P_k`, being used to introduce zeros into the :math:`k`\ th row of :math:`A`. :math:`P_k` has the form
.. math::
P_k = \begin{pmatrix}I&0\\0&T_k\end{pmatrix}\text{,}
where
.. math::
\begin{array}{c}T_k = I-\gamma_ku_ku_k^H\text{,}\\\\u_k = \begin{pmatrix}\zeta_k\\0\\z_k\\cr\end{pmatrix}\text{,} \end{array}
:math:`\gamma_k` is a scalar for which :math:`\mathrm{Re}\left(\gamma_k\right) = 1.0`, :math:`\zeta_k` is a real scalar and :math:`z_k` is an :math:`\left(n-m\right)` element vector. :math:`\gamma_k`, :math:`\zeta_k` and :math:`z_k` are chosen to annihilate the elements of the :math:`k`\ th row of :math:`X` and to make the diagonal elements of :math:`R` real.
The scalar :math:`\gamma_k` and the vector :math:`u_k` are returned in the :math:`k`\ th element of the array :math:`\mathrm{theta}` and in the :math:`k`\ th row of :math:`\mathrm{a}`, such that :math:`\theta_k`, given by
.. math::
\theta_k = \left(\zeta_k, {\mathrm{Im}\left(\gamma_k\right)}\right)\text{,}
is in :math:`\mathrm{theta}[k-1]` and the elements of :math:`z_k` are in :math:`\mathrm{a}[k-1,m],\ldots,\mathrm{a}[k-1,n-1]`.
The elements of :math:`R` are returned in the upper triangular part of :math:`\mathrm{a}`.
For further information on this factorization and its use see Section 6.5 of Golub and Van Loan (1996).
.. _f01rg-py2-py-references:
**References**
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
Wilkinson, J H, 1965, `The Algebraic Eigenvalue Problem`, Oxford University Press, Oxford
"""
raise NotImplementedError
[docs]def complex_gen_rq(m, a):
r"""
``complex_gen_rq`` finds the :math:`RQ` factorization of the complex :math:`m\times n` (:math:`m\leq n`), matrix :math:`A`, so that :math:`A` is reduced to upper triangular form by means of unitary transformations from the right.
.. _f01rj-py2-py-doc:
For full information please refer to the NAG Library document for f01rj
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01rjf.html
.. _f01rj-py2-py-parameters:
**Parameters**
**m** : int
:math:`m`, the number of rows of the matrix :math:`A`.
When :math:`\mathrm{m} = 0` then an immediate return is effected.
**a** : complex, array-like, shape :math:`\left(\mathrm{m}, n\right)`
The leading :math:`m\times n` part of the array :math:`\mathrm{a}` must contain the matrix to be factorized.
**Returns**
**a** : complex, ndarray, shape :math:`\left(\mathrm{m}, n\right)`
The :math:`m\times m` upper triangular part of :math:`\mathrm{a}` will contain the upper triangular matrix :math:`R`, and the :math:`m\times m` strictly lower triangular part of :math:`\mathrm{a}` and the :math:`m\times \left(n-m\right)` rectangular part of :math:`\mathrm{a}` to the right of the upper triangular part will contain details of the factorization as described in :ref:`Notes <f01rj-py2-py-notes>`.
**theta** : complex, ndarray, shape :math:`\left(\mathrm{m}\right)`
:math:`\mathrm{theta}[k-1]` contains the scalar :math:`\theta_k` for the :math:`\left(m-k+1\right)`\ th transformation. If :math:`P_k = I` then :math:`\mathrm{theta}[k-1] = 0.0`; if
.. math::
T_k = \begin{pmatrix}I&0&0\\0&\alpha &0\\0&0&I\end{pmatrix}\text{, }\quad \mathrm{Re}\left(\alpha \right) < 0.0
then :math:`\mathrm{theta}[k-1] = \alpha`, otherwise :math:`\mathrm{theta}[k-1]` contains :math:`\theta_k` as described in :ref:`Notes <f01rj-py2-py-notes>` and :math:`\theta_k` is always in the range :math:`\left(1.0, {\sqrt{2.0}}\right)`.
.. _f01rj-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq \mathrm{m}`.
(`errno` :math:`-1`)
On entry, :math:`\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m}\geq 0`.
.. _f01rj-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
The :math:`m\times n` matrix :math:`A` is factorized as
.. math::
\begin{array}{ll}A = \begin{pmatrix}R&0\end{pmatrix} P^\mathrm{H}&\text{when }m < n\text{,}\\&\\A = RP^\mathrm{H}&\text{when }m = n\text{,}\end{array}
where :math:`P` is an :math:`n\times n` unitary matrix and :math:`R` is an :math:`m\times m` upper triangular matrix.
:math:`P` is given as a sequence of Householder transformation matrices
.. math::
P = P_m \cdots P_2P_1\text{,}
the :math:`\left(m-k+1\right)`\ th transformation matrix, :math:`P_k`, being used to introduce zeros into the :math:`k`\ th row of :math:`A`. :math:`P_k` has the form
.. math::
P_k = I-\gamma_ku_ku_k^H\text{,}
where
.. math::
u_k = \begin{pmatrix}w_k\\\zeta_k\\0\\z_k\end{pmatrix}\text{.}
:math:`\gamma_k` is a scalar for which :math:`\mathrm{Re}\left(\gamma_k\right) = 1.0`, :math:`\zeta_k` is a real scalar, :math:`w_k` is a :math:`\left(k-1\right)` element vector and :math:`z_k` is an :math:`\left(n-m\right)` element vector. :math:`\gamma_k` and :math:`u_k` are chosen to annihilate the elements in the :math:`k`\ th row of :math:`A`.
The scalar :math:`\gamma_k` and the vector :math:`u_k` are returned in the :math:`k`\ th element of :math:`\mathrm{theta}` and in the :math:`k`\ th row of :math:`\mathrm{a}`, such that :math:`\theta_k`, given by
.. math::
\theta_k = \left(\zeta_k, {\mathrm{Im}\left(\gamma_k\right)}\right)\text{.}
is in :math:`\mathrm{theta}[k-1]`, the elements of :math:`w_k` are in :math:`\mathrm{a}[k-1,0],\ldots,\mathrm{a}[k-1,k-2]` and the elements of :math:`z_k` are in :math:`\mathrm{a}[k-1,m],\ldots,\mathrm{a}[k-1,n-1]`.
The elements of :math:`R` are returned in the upper triangular part of :math:`\mathrm{a}`.
.. _f01rj-py2-py-references:
**References**
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
Wilkinson, J H, 1965, `The Algebraic Eigenvalue Problem`, Oxford University Press, Oxford
"""
raise NotImplementedError
[docs]def real_nmf(a, k=None, w=None, h=None, seed=None, errtol=0.0, maxit=0):
r"""
``real_nmf`` computes a non-negative matrix factorization for a real non-negative :math:`m\times n` matrix :math:`A`.
.. _f01sa-py2-py-doc:
For full information please refer to the NAG Library document for f01sa
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01saf.html
.. _f01sa-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(m, n\right)`
The :math:`m\times n` non-negative matrix :math:`A`.
**k** : None or int, optional
Note: if this argument is **None** then a default value will be used, determined as follows: dimension 1 of :math:`\mathrm{h}`.
:math:`k`, the factorization rank.
This argument is only referenced if you are not supplying initial iterates :math:`W` and :math:`H`.
If you are providing initial iterates :math:`W` and :math:`H` then your supplied value of :math:`k` will be ignored and it will be inferred from those arrays instead.
**w** : None or float, array-like, shape :math:`\left(m, \mathrm{k}\right)`, optional
If :math:`\mathrm{seed} \leq 0`, :math:`\mathrm{w}` should be set to an initial iterate for the non-negative matrix factor, :math:`W`.
If :math:`\mathrm{seed} \geq 1`, :math:`\mathrm{w}` need not be set. ``real_nmf`` will generate a random initial iterate.
**h** : None or float, array-like, shape :math:`\left(\mathrm{k}, n\right)`, optional
If :math:`\mathrm{seed} \leq 0`, :math:`\mathrm{h}` should be set to an initial iterate for the non-negative matrix factor, :math:`H`.
If :math:`\mathrm{seed} \geq 1`, :math:`\mathrm{h}` need not be set. ``real_nmf`` will generate a random initial iterate.
**seed** : None or int, optional
Note: if this argument is **None** then a default value will be used, determined as follows: if :math:`\mathrm{w}\text{ is not }\mathbf{None}`: :math:`{ 0 }`; otherwise: :math:`{ 1 }`.
If :math:`\mathrm{seed} \leq 0`, the supplied values of :math:`W` and :math:`H` are used for the initial iterate.
If :math:`\mathrm{seed} \geq 1`, the value of :math:`\mathrm{seed}` is used to seed a random number generator for the initial iterates :math:`W` and :math:`H`. See `Generating Random Initial Iterates <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01saf.html#fc-genrii>`__ for further details.
**errtol** : float, optional
The convergence tolerance for when the Hierarchical Alternating Least Squares iteration has reached a stationary point. If :math:`\mathrm{errtol}\leq 0.0`, :math:`\mathrm{max}\left(m, n\right)\times \sqrt{\text{machine precision}}` is used.
**maxit** : int, optional
Specifies the maximum number of iterations to be used. If :math:`\mathrm{maxit}\leq 0`, :math:`200` is used.
**Returns**
**w** : float, ndarray, shape :math:`\left(m, \mathrm{k}\right)`
The non-negative matrix factor, :math:`W`.
**h** : float, ndarray, shape :math:`\left(\mathrm{k}, n\right)`
The non-negative matrix factor, :math:`H`.
.. _f01sa-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq 2`.
(`errno` :math:`2`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 2`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{k} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`1\leq \mathrm{k} < \mathrm{min}\left(m, n\right)`.
(`errno` :math:`8`)
An internal error occurred when generating initial values for :math:`\mathrm{w}` and :math:`\mathrm{h}`. Please contact `NAG <https://www.nag.com>`__.
(`errno` :math:`9`)
On entry, one of more of the elements of :math:`\mathrm{a}`, :math:`\mathrm{w}` or :math:`\mathrm{h}` were negative.
(`errno` :math:`14`)
Both or neither of :math:`\mathrm{w}` and :math:`\mathrm{h}` must be provided.
(`errno` :math:`15`)
:math:`\mathrm{h}` or :math:`\mathrm{k}` must be provided.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`7`)
The function has failed to converge after :math:`\langle\mathit{\boldsymbol{value}}\rangle` iterations. The factorization given by :math:`\mathrm{w}` and :math:`\mathrm{h}` may still be a good enough approximation to be useful. Alternatively an improved factorization may be obtained by increasing :math:`\mathrm{maxit}` or using different initial choices of :math:`\mathrm{w}` and :math:`\mathrm{h}`.
.. _f01sa-py2-py-notes:
**Notes**
The matrix :math:`A` is factorized into the product of an :math:`m\times k` matrix :math:`W` and a :math:`k\times n` matrix :math:`H`, both with non-negative elements.
The factorization is approximate, :math:`A≈WH`, with :math:`W` and :math:`H` chosen to minimize the functional
.. math::
f\left(W, H\right) = \left\lVert A-WH\right\rVert_F^2\text{.}
You are free to choose any value for :math:`k`, provided :math:`k < \mathrm{min}\left(m, n\right)`.
The product :math:`WH` will then be a low-rank approximation to :math:`A`, with rank at most :math:`k`.
``real_nmf`` finds :math:`W` and :math:`H` using an iterative method known as the Hierarchical Alternating Least Squares algorithm.
You may specify initial values for :math:`W` and :math:`H`, or you may provide a seed value for ``real_nmf`` to generate the initial values using a random number generator.
.. _f01sa-py2-py-references:
**References**
Cichocki, A and Phan, A--H, 2009, `Fast local algorithms for large scale nonnegative matrix and tensor factorizations`, IEICE Transactions on Fundamentals of Electronics, Communications and Computer Sciences (E92--A), 708--721
Cichocki, A, Zdunek, R and Amari, S--I, 2007, `Hierarchical ALS algorithms for nonnegative matrix and 3D tensor factorization`, Lecture Notes in Computer Science (4666), Springer, 169--176
Ho, N--D, 2008, `Nonnegative matrix factorization algorithms and applications`, PhD Thesis, Univ. Catholique de Louvain
"""
raise NotImplementedError
[docs]def real_nmf_rcomm(irevcm, w, h, ht, comm, seed=1, errtol=0.0):
r"""
``real_nmf_rcomm`` computes a non-negative matrix factorization for a real non-negative :math:`m\times n` matrix :math:`A`.
It uses reverse communication for evaluating matrix products, so that the matrix :math:`A` is not accessed explicitly.
.. _f01sb-py2-py-doc:
For full information please refer to the NAG Library document for f01sb
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01sbf.html
.. _f01sb-py2-py-parameters:
**Parameters**
**irevcm** : int
`On initial entry`: must be set to :math:`0`.
**w** : float, ndarray, shape :math:`\left(m, k\right)`, modified in place
`On initial entry`:
if :math:`\mathrm{seed} \leq 0`, :math:`\mathrm{w}` should be set to an initial iterate for the non-negative matrix factor, :math:`W`.
If :math:`\mathrm{seed} \geq 1`, :math:`\mathrm{w}` need not be set. ``real_nmf_rcomm`` will generate a random initial iterate.
`On intermediate exit`: if :math:`\mathrm{irevcm} = 1` or :math:`2`, :math:`\mathrm{w}` contains the current iterate of the :math:`m\times k` non-negative matrix :math:`W`.
`On intermediate entry`:
if :math:`\mathrm{irevcm} = 3`, :math:`\mathrm{w}` must contain :math:`AH^\mathrm{T}`, where :math:`H^\mathrm{T}` is stored in :math:`\textit{ht}`.
If :math:`\mathrm{irevcm} = 0`, :math:`1` or :math:`2`, :math:`\mathrm{w}` must not be changed.
`On final exit`: :math:`\mathrm{w}` contains the :math:`m\times k` non-negative matrix :math:`W`.
**h** : float, ndarray, shape :math:`\left(k, n\right)`, modified in place
`On initial entry`:
if :math:`\mathrm{seed} \leq 0`, :math:`\mathrm{h}` should be set to an initial iterate for the non-negative matrix factor, :math:`H`.
If :math:`\mathrm{seed} \geq 1`, :math:`\mathrm{h}` need not be set. ``real_nmf_rcomm`` will generate a random initial iterate.
`On intermediate exit`: if :math:`\mathrm{irevcm} = 1`, :math:`\mathrm{h}` contains the current iterate of the :math:`k\times n` non-negative matrix :math:`H`.
`On intermediate entry`: :math:`\mathrm{h}` must not be changed.
`On final exit`: :math:`\mathrm{h}` contains the :math:`k\times n` non-negative matrix :math:`H`.
**ht** : float, ndarray, shape :math:`\left(n, k\right)`, modified in place
`On initial entry`: :math:`\mathrm{ht}` need not be set.
`On intermediate exit`: if :math:`\mathrm{irevcm} = 3`, :math:`\mathrm{ht}` contains the :math:`n\times k` non-negative matrix :math:`H^\mathrm{T}`, which is required in order to form :math:`AH^\mathrm{T}`.
`On intermediate entry`: if :math:`\mathrm{irevcm} = 2`, :math:`\mathrm{ht}` must contain :math:`A^\mathrm{T}W`.
If :math:`\mathrm{irevcm} = 0`, :math:`1` or :math:`3`, :math:`\mathrm{ht}` must not be changed.
`On final exit`: :math:`\mathrm{ht}` is undefined.
**comm** : dict, communication object, modified in place
Communication structure.
`On initial entry`: need not be set.
**seed** : int, optional
`On initial entry`:
if :math:`\mathrm{seed} \leq 0`, the supplied values of :math:`W` and :math:`H` are used for the initial iterate.
If :math:`\mathrm{seed} \geq 1`, the value of :math:`\mathrm{seed}` is used to seed a random number generator for the initial iterates :math:`W` and :math:`H`. See `Generating Random Initial Iterates <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01sbf.html#fc-genrii>`__ for further details.
**errtol** : float, optional
The convergence tolerance for when the Hierarchical Alternating Least Squares iteration has reached a stationary point. If :math:`\mathrm{errtol}\leq 0.0`, :math:`\mathrm{max}\left(m, n\right)\times \sqrt{\text{machine precision}}` is used.
**Returns**
**irevcm** : int
`On intermediate exit`: specifies what action you must take before re-entering ``real_nmf_rcomm`` with :math:`\mathrm{irevcm}` unchanged. The value of :math:`\mathrm{irevcm}` should be interpreted as follows:
:math:`\mathrm{irevcm} = 1`
Indicates the start of a new iteration. No action is required by you, but :math:`\mathrm{w}` and :math:`\mathrm{h}` are available for printing, and a limit on the number of iterations can be applied.
:math:`\mathrm{irevcm} = 2`
Indicates that before re-entry to ``real_nmf_rcomm``, the product :math:`A^\mathrm{T}W` must be computed and stored in :math:`\mathrm{ht}`.
:math:`\mathrm{irevcm} = 3`
Indicates that before re-entry to ``real_nmf_rcomm``, the product :math:`AH^\mathrm{T}` must be computed and stored in :math:`\mathrm{w}`.
`On final exit`: :math:`\mathrm{irevcm} = 0`.
.. _f01sb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On intermediate re-entry, :math:`\mathrm{irevcm} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{irevcm} = 1`, :math:`2` or :math:`3`.
(`errno` :math:`1`)
On initial entry, :math:`\mathrm{irevcm} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{irevcm} = 0`.
(`errno` :math:`2`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m\geq 2`.
(`errno` :math:`3`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 2`.
(`errno` :math:`4`)
On entry, :math:`k = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`1\leq k < \mathrm{min}\left(m, n\right)`.
(`errno` :math:`8`)
An internal error occurred when generating initial values for :math:`\mathrm{w}` and :math:`\mathrm{h}`. Please contact `NAG <https://www.nag.com>`__.
(`errno` :math:`9`)
On entry, one of more of the elements of :math:`\mathrm{w}` or :math:`\mathrm{h}` were negative.
.. _f01sb-py2-py-notes:
**Notes**
The matrix :math:`A` is factorized into the product of an :math:`m\times k` matrix :math:`W` and a :math:`k\times n` matrix :math:`H`, both with non-negative elements.
The factorization is approximate, :math:`A≈WH`, with :math:`W` and :math:`H` chosen to minimize the functional
.. math::
f\left(W, H\right) = \left\lVert A-WH\right\rVert_F^2\text{.}
You are free to choose any value for :math:`k`, provided :math:`k < \mathrm{min}\left(m, n\right)`.
The product :math:`WH` will then be a low-rank approximation to :math:`A`, with rank at most :math:`k`.
``real_nmf_rcomm`` finds :math:`W` and :math:`H` using an iterative method known as the Hierarchical Alternating Least Squares algorithm.
You may specify initial values for :math:`W` and :math:`H`, or you may provide a seed value for ``real_nmf_rcomm`` to generate the initial values using a random number generator.
``real_nmf_rcomm`` does not explicitly need to access the elements of :math:`A`; it only requires the result of matrix multiplications of the form :math:`AX` or :math:`A^\mathrm{T}Y`.
A reverse communication interface is used, in which control is returned to the calling program whenever a matrix product is required.
.. _f01sb-py2-py-references:
**References**
Cichocki, A and Phan, A--H, 2009, `Fast local algorithms for large scale nonnegative matrix and tensor factorizations`, IEICE Transactions on Fundamentals of Electronics, Communications and Computer Sciences (E92--A), 708--721
Cichocki, A, Zdunek, R and Amari, S--I, 2007, `Hierarchical ALS algorithms for nonnegative matrix and 3D tensor factorization`, Lecture Notes in Computer Science (4666), Springer, 169--176
Ho, N--D, 2008, `Nonnegative matrix factorization algorithms and applications`, PhD Thesis, Univ. Catholique de Louvain
"""
raise NotImplementedError
[docs]def dtrttp(uplo, a):
r"""
``dtrttp`` copies a real triangular matrix, stored in a full format array, to a standard packed format array.
.. _f01va-py2-py-doc:
For full information please refer to the NAG Library document for f01va
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01vaf.html
.. _f01va-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**a** : float, array-like, shape :math:`\left(n, n\right)`
The triangular matrix :math:`A`.
**Returns**
**ap** : float, ndarray, shape :math:`\left(n\times \left(n+1\right)/2\right)`
The :math:`n\times n` triangular matrix :math:`A`, packed by columns.
.. _f01va-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
.. _f01va-py2-py-notes:
**Notes**
``dtrttp`` packs a real :math:`n\times n` triangular matrix :math:`A`, stored conventionally in a full format array, into an array of length :math:`n\left(n+1\right)/2`.
The matrix is packed by columns.
This function is intended for possible use in conjunction with functions from submodule :mod:`~naginterfaces.library.blas`, submodule :mod:`~naginterfaces.library.blast`, submodule :mod:`~naginterfaces.library.lapacklin` and submodule :mod:`~naginterfaces.library.lapackeig` where some functions use triangular matrices stored in the packed form. Packed storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f07/f07intro.html#recomm_32>`__.
"""
raise NotImplementedError
[docs]def ztrttp(uplo, a):
r"""
``ztrttp`` copies a complex triangular matrix, stored in a full format array, to a packed format array.
.. _f01vb-py2-py-doc:
For full information please refer to the NAG Library document for f01vb
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01vbf.html
.. _f01vb-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The triangular matrix :math:`A`.
**Returns**
**ap** : complex, ndarray, shape :math:`\left(n\times \left(n+1\right)/2\right)`
The :math:`n\times n` triangular matrix :math:`A`, packed by columns.
.. _f01vb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
.. _f01vb-py2-py-notes:
**Notes**
``ztrttp`` packs a complex :math:`n\times n` triangular matrix :math:`A`, stored conventionally in a full format array, into an array of length :math:`n\left(n+1\right)/2`.
The matrix is packed by columns.
This function is intended for possible use in conjunction with functions from submodule :mod:`~naginterfaces.library.blas`, submodule :mod:`~naginterfaces.library.blast`, submodule :mod:`~naginterfaces.library.lapacklin` and submodule :mod:`~naginterfaces.library.lapackeig` where some functions use triangular matrices stored in the packed form. Packed storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f07/f07intro.html#recomm_32>`__.
"""
raise NotImplementedError
[docs]def dtpttr(uplo, n, ap):
r"""
``dtpttr`` unpacks a real triangular matrix, stored in a standard packed format array, to a full format array.
.. _f01vc-py2-py-doc:
For full information please refer to the NAG Library document for f01vc
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01vcf.html
.. _f01vc-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**n** : int
:math:`n`, the order of the matrix :math:`A`.
**ap** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
The :math:`n\times n` triangular matrix :math:`A`, packed by columns.
**Returns**
**a** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
The triangular matrix :math:`A`.
.. _f01vc-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
.. _f01vc-py2-py-notes:
**Notes**
``dtpttr`` unpacks a real :math:`n\times n` triangular matrix :math:`A`, stored in an array of length :math:`n\left(n+1\right)/2`, to conventional storage in a full format array.
This function is intended for possible use in conjunction with functions from submodule :mod:`~naginterfaces.library.blas`, submodule :mod:`~naginterfaces.library.blast`, submodule :mod:`~naginterfaces.library.lapacklin` and submodule :mod:`~naginterfaces.library.lapackeig` where some functions use triangular matrices stored in the packed form. Packed storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f07/f07intro.html#recomm_32>`__.
"""
raise NotImplementedError
[docs]def ztpttr(uplo, n, ap):
r"""
``ztpttr`` unpacks a complex triangular matrix, stored in a standard packed format array, to a full format array.
.. _f01vd-py2-py-doc:
For full information please refer to the NAG Library document for f01vd
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01vdf.html
.. _f01vd-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**n** : int
:math:`n`, the order of the matrix :math:`A`.
**ap** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
The :math:`n\times n` triangular matrix :math:`A`, packed by columns.
**Returns**
**a** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
The triangular matrix :math:`A`.
.. _f01vd-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
.. _f01vd-py2-py-notes:
**Notes**
``ztpttr`` unpacks a complex :math:`n\times n` triangular matrix :math:`A`, stored in an array of length :math:`n\left(n+1\right)/2`, to conventional storage in a full format array.
This function is intended for possible use in conjunction with functions from submodule :mod:`~naginterfaces.library.blas`, submodule :mod:`~naginterfaces.library.blast`, submodule :mod:`~naginterfaces.library.lapacklin` and submodule :mod:`~naginterfaces.library.lapackeig` where some functions use triangular matrices stored in the packed form. Packed storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f07/f07intro.html#recomm_32>`__.
"""
raise NotImplementedError
[docs]def dtrttf(transr, uplo, a):
r"""
``dtrttf`` copies a real triangular matrix, stored in a full format array, to a Rectangular Full Packed (RFP) format array.
.. _f01ve-py2-py-doc:
For full information please refer to the NAG Library document for f01ve
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01vef.html
.. _f01ve-py2-py-parameters:
**Parameters**
**transr** : str, length 1
Specifies whether the normal RFP representation of :math:`A` or its transpose is stored.
:math:`\mathrm{transr} = \texttt{'N'}`
The RFP representation of the matrix :math:`A` is stored.
:math:`\mathrm{transr} = \texttt{'T'}`
The transpose of the RFP representation of the matrix :math:`A` is stored.
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**a** : float, array-like, shape :math:`\left(n, n\right)`
The triangular matrix :math:`A`.
**Returns**
**ar** : float, ndarray, shape :math:`\left(n\times \left(n+1\right)/2\right)`
The upper or lower :math:`n\times n` triangular matrix :math:`A` (as specified by :math:`\mathrm{uplo}`) in either normal or transposed RFP format (as specified by :math:`\mathrm{transr}`). The storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f07/f07intro.html#recomm_32a>`__.
.. _f01ve-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{transr}`.
Constraint: :math:`\mathrm{transr} = \texttt{'N'}` or :math:`\texttt{'T'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
.. _f01ve-py2-py-notes:
**Notes**
``dtrttf`` packs a real :math:`n\times n` triangular matrix :math:`A`, stored conventionally in a full format array, into RFP format.
This function is intended for possible use in conjunction with functions from submodule :mod:`~naginterfaces.library.blas`, submodule :mod:`~naginterfaces.library.blast` and submodule :mod:`~naginterfaces.library.lapacklin` where some functions that use triangular matrices store them in RFP format. The RFP storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f07/f07intro.html#recomm_32a>`__.
.. _f01ve-py2-py-references:
**References**
Gustavson, F G, Waśniewski, J, Dongarra, J J and Langou, J, 2010, `Rectangular full packed format for Cholesky's algorithm: factorization, solution, and inversion`, ACM Trans. Math. Software (37, 2)
"""
raise NotImplementedError
[docs]def ztrttf(transr, uplo, a):
r"""
``ztrttf`` copies a complex triangular matrix, stored in a full format array, to a Rectangular Full Packed (RFP) format array.
.. _f01vf-py2-py-doc:
For full information please refer to the NAG Library document for f01vf
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01vff.html
.. _f01vf-py2-py-parameters:
**Parameters**
**transr** : str, length 1
Specifies whether the normal RFP representation of :math:`A` or its conjugate transpose is stored.
:math:`\mathrm{transr} = \texttt{'N'}`
The RFP representation of the matrix :math:`A` is stored.
:math:`\mathrm{transr} = \texttt{'C'}`
The conjugate transpose of the RFP representation of the matrix :math:`A` is stored.
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The triangular matrix :math:`A`.
**Returns**
**ar** : complex, ndarray, shape :math:`\left(n\times \left(n+1\right)/2\right)`
The upper or lower :math:`n\times n` triangular matrix :math:`A` (as specified by :math:`\mathrm{uplo}`) in either normal or transposed RFP format (as specified by :math:`\mathrm{transr}`). The storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f07/f07intro.html#recomm_32a>`__.
.. _f01vf-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{transr}`.
Constraint: :math:`\mathrm{transr} = \texttt{'N'}` or :math:`\texttt{'C'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
.. _f01vf-py2-py-notes:
**Notes**
``ztrttf`` packs a complex :math:`n\times n` triangular matrix :math:`A`, stored conventionally in a full format array, into RFP format.
This function is intended for possible use in conjunction with functions from submodule :mod:`~naginterfaces.library.blas`, submodule :mod:`~naginterfaces.library.blast` and submodule :mod:`~naginterfaces.library.lapacklin` where some functions that use triangular matrices store them in RFP format. The RFP storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f07/f07intro.html#recomm_32a>`__.
.. _f01vf-py2-py-references:
**References**
Gustavson, F G, Waśniewski, J, Dongarra, J J and Langou, J, 2010, `Rectangular full packed format for Cholesky's algorithm: factorization, solution, and inversion`, ACM Trans. Math. Software (37, 2)
"""
raise NotImplementedError
[docs]def dtfttr(transr, uplo, n, ar):
r"""
``dtfttr`` unpacks a real triangular matrix, stored in a Rectangular Full Packed (RFP) format array, to a full format array.
.. _f01vg-py2-py-doc:
For full information please refer to the NAG Library document for f01vg
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01vgf.html
.. _f01vg-py2-py-parameters:
**Parameters**
**transr** : str, length 1
Specifies whether the normal RFP representation of :math:`A` or its transpose is stored.
:math:`\mathrm{transr} = \texttt{'N'}`
The RFP representation of the matrix :math:`A` is stored.
:math:`\mathrm{transr} = \texttt{'T'}`
The transpose of the RFP representation of the matrix :math:`A` is stored.
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**n** : int
:math:`n`, the order of the matrix :math:`A`.
**ar** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
The upper or lower :math:`n\times n` triangular matrix :math:`A` (as specified by :math:`\mathrm{uplo}`) in either normal or transposed RFP format (as specified by :math:`\mathrm{transr}`). The storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f07/f07intro.html#recomm_32a>`__.
**Returns**
**a** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
The triangular matrix :math:`A`.
.. _f01vg-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{transr}`.
Constraint: :math:`\mathrm{transr} = \texttt{'N'}` or :math:`\texttt{'T'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
.. _f01vg-py2-py-notes:
**Notes**
``dtfttr`` unpacks a real :math:`n\times n` triangular matrix :math:`A`, stored in RFP format to conventional storage in a full format array.
This function is intended for possible use in conjunction with functions from submodule :mod:`~naginterfaces.library.blas`, submodule :mod:`~naginterfaces.library.blast` and submodule :mod:`~naginterfaces.library.lapacklin` where some functions that use triangular matrices store them in RFP format. The RFP storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f07/f07intro.html#recomm_32a>`__.
.. _f01vg-py2-py-references:
**References**
Gustavson, F G, Waśniewski, J, Dongarra, J J and Langou, J, 2010, `Rectangular full packed format for Cholesky's algorithm: factorization, solution, and inversion`, ACM Trans. Math. Software (37, 2)
"""
raise NotImplementedError
[docs]def ztfttr(transr, uplo, n, ar):
r"""
``ztfttr`` unpacks a complex triangular matrix, stored in a Rectangular Full Packed (RFP) format array, to a full format array.
.. _f01vh-py2-py-doc:
For full information please refer to the NAG Library document for f01vh
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01vhf.html
.. _f01vh-py2-py-parameters:
**Parameters**
**transr** : str, length 1
Specifies whether the normal RFP representation of :math:`A` or its conjugate transpose is stored.
:math:`\mathrm{transr} = \texttt{'N'}`
The RFP representation of the matrix :math:`A` is stored.
:math:`\mathrm{transr} = \texttt{'C'}`
The conjugate transpose of the RFP representation of the matrix :math:`A` is stored.
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**n** : int
:math:`n`, the order of the matrix :math:`A`.
**ar** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
The upper or lower :math:`n\times n` triangular matrix :math:`A` (as specified by :math:`\mathrm{uplo}`) in either normal or transposed RFP format (as specified by :math:`\mathrm{transr}`). The storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f07/f07intro.html#recomm_32a>`__.
**Returns**
**a** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
The triangular matrix :math:`A`.
.. _f01vh-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{transr}`.
Constraint: :math:`\mathrm{transr} = \texttt{'N'}` or :math:`\texttt{'C'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
.. _f01vh-py2-py-notes:
**Notes**
``ztfttr`` unpacks a complex :math:`n\times n` triangular matrix :math:`A`, stored in RFP format to conventional storage in a full format array.
This function is intended for possible use in conjunction with functions from submodule :mod:`~naginterfaces.library.blas`, submodule :mod:`~naginterfaces.library.blast` and submodule :mod:`~naginterfaces.library.lapacklin` where some functions that use triangular matrices store them in RFP format. The RFP storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f07/f07intro.html#recomm_32a>`__.
.. _f01vh-py2-py-references:
**References**
Gustavson, F G, Waśniewski, J, Dongarra, J J and Langou, J, 2010, `Rectangular full packed format for Cholesky's algorithm: factorization, solution, and inversion`, ACM Trans. Math. Software (37, 2)
"""
raise NotImplementedError
[docs]def dtpttf(transr, uplo, n, ap):
r"""
``dtpttf`` copies a real triangular matrix, stored in a standard packed format array, to a Rectangular Full Packed (RFP) format array.
.. _f01vj-py2-py-doc:
For full information please refer to the NAG Library document for f01vj
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01vjf.html
.. _f01vj-py2-py-parameters:
**Parameters**
**transr** : str, length 1
Specifies whether the normal RFP representation of :math:`A` or its transpose is stored.
:math:`\mathrm{transr} = \texttt{'N'}`
The RFP representation of the matrix :math:`A` is stored.
:math:`\mathrm{transr} = \texttt{'T'}`
The transpose of the RFP representation of the matrix :math:`A` is stored.
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**n** : int
:math:`n`, the order of the matrix :math:`A`.
**ap** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
The :math:`n\times n` triangular matrix :math:`A`, packed by columns.
**Returns**
**ar** : float, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
The upper or lower :math:`n\times n` triangular matrix :math:`A` (as specified by :math:`\mathrm{uplo}`) in either normal or transposed RFP format (as specified by :math:`\mathrm{transr}`). The storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f07/f07intro.html#recomm_32a>`__.
.. _f01vj-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{transr}`.
Constraint: :math:`\mathrm{transr} = \texttt{'N'}` or :math:`\texttt{'T'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
.. _f01vj-py2-py-notes:
**Notes**
``dtpttf`` copies a real :math:`n\times n` triangular matrix, :math:`A`, stored in packed format, to RFP format.
This function is intended for possible use in conjunction with functions from submodule :mod:`~naginterfaces.library.blas`, submodule :mod:`~naginterfaces.library.blast` and submodule :mod:`~naginterfaces.library.lapacklin` where some functions that use triangular matrices store them in RFP format. The RFP storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f07/f07intro.html#recomm_32a>`__ and the packed storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f07/f07intro.html#recomm_32>`__.
.. _f01vj-py2-py-references:
**References**
Gustavson, F G, Waśniewski, J, Dongarra, J J and Langou, J, 2010, `Rectangular full packed format for Cholesky's algorithm: factorization, solution, and inversion`, ACM Trans. Math. Software (37, 2)
"""
raise NotImplementedError
[docs]def ztpttf(transr, uplo, n, ap):
r"""
``ztpttf`` copies a complex triangular matrix, stored in a standard packed format array, to a Rectangular Full Packed (RFP) format array.
.. _f01vk-py2-py-doc:
For full information please refer to the NAG Library document for f01vk
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01vkf.html
.. _f01vk-py2-py-parameters:
**Parameters**
**transr** : str, length 1
Specifies whether the normal RFP representation of :math:`A` or its conjugate transpose is stored.
:math:`\mathrm{transr} = \texttt{'N'}`
The RFP representation of the matrix :math:`A` is stored.
:math:`\mathrm{transr} = \texttt{'C'}`
The conjugate transpose of the RFP representation of the matrix :math:`A` is stored.
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**n** : int
:math:`n`, the order of the matrix :math:`A`.
**ap** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
The :math:`n\times n` triangular matrix :math:`A`, packed by columns.
**Returns**
**ar** : complex, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
The upper or lower :math:`n\times n` triangular matrix :math:`A` (as specified by :math:`\mathrm{uplo}`) in either normal or transposed RFP format (as specified by :math:`\mathrm{transr}`). The storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f07/f07intro.html#recomm_32a>`__.
.. _f01vk-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{transr}`.
Constraint: :math:`\mathrm{transr} = \texttt{'N'}` or :math:`\texttt{'C'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
.. _f01vk-py2-py-notes:
**Notes**
``ztpttf`` copies a complex :math:`n\times n` triangular matrix, :math:`A`, stored in packed format, to RFP format.
This function is intended for possible use in conjunction with functions from submodule :mod:`~naginterfaces.library.blas`, submodule :mod:`~naginterfaces.library.blast` and submodule :mod:`~naginterfaces.library.lapacklin` where some functions that use triangular matrices store them in RFP format. The RFP storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f07/f07intro.html#recomm_32a>`__ and the packed storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f07/f07intro.html#recomm_32>`__.
.. _f01vk-py2-py-references:
**References**
Gustavson, F G, Waśniewski, J, Dongarra, J J and Langou, J, 2010, `Rectangular full packed format for Cholesky's algorithm: factorization, solution, and inversion`, ACM Trans. Math. Software (37, 2)
"""
raise NotImplementedError
[docs]def dtfttp(transr, uplo, n, ar):
r"""
``dtfttp`` copies a real triangular matrix, stored in a Rectangular Full Packed (RFP) format array, to a standard packed format array.
.. _f01vl-py2-py-doc:
For full information please refer to the NAG Library document for f01vl
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01vlf.html
.. _f01vl-py2-py-parameters:
**Parameters**
**transr** : str, length 1
Specifies whether the normal RFP representation of :math:`A` or its transpose is stored.
:math:`\mathrm{transr} = \texttt{'N'}`
The RFP representation of the matrix :math:`A` is stored.
:math:`\mathrm{transr} = \texttt{'T'}`
The transpose of the RFP representation of the matrix :math:`A` is stored.
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**n** : int
:math:`n`, the order of the matrix :math:`A`.
**ar** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
The upper or lower :math:`n\times n` triangular matrix :math:`A` (as specified by :math:`\mathrm{uplo}`) in either normal or transposed RFP format (as specified by :math:`\mathrm{transr}`). The storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f07/f07intro.html#recomm_32a>`__.
**Returns**
**ap** : float, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
The :math:`n\times n` triangular matrix :math:`A`, packed by columns.
.. _f01vl-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{transr}`.
Constraint: :math:`\mathrm{transr} = \texttt{'N'}` or :math:`\texttt{'T'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
.. _f01vl-py2-py-notes:
**Notes**
``dtfttp`` packs a real :math:`n\times n` triangular matrix :math:`A`, stored in RFP format, to packed format.
This function is intended for possible use in conjunction with functions from submodule :mod:`~naginterfaces.library.blas`, submodule :mod:`~naginterfaces.library.blast` and submodule :mod:`~naginterfaces.library.lapacklin` where some functions that use triangular matrices store them in RFP format. The RFP storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f07/f07intro.html#recomm_32a>`__ and the packed storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f07/f07intro.html#recomm_32>`__.
.. _f01vl-py2-py-references:
**References**
Gustavson, F G, Waśniewski, J, Dongarra, J J and Langou, J, 2010, `Rectangular full packed format for Cholesky's algorithm: factorization, solution, and inversion`, ACM Trans. Math. Software (37, 2)
"""
raise NotImplementedError
[docs]def ztfttp(transr, uplo, n, ar):
r"""
``ztfttp`` copies a complex triangular matrix, stored in a Rectangular Full Packed (RFP) format array, to a standard packed format array.
.. _f01vm-py2-py-doc:
For full information please refer to the NAG Library document for f01vm
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01vmf.html
.. _f01vm-py2-py-parameters:
**Parameters**
**transr** : str, length 1
Specifies whether the normal RFP representation of :math:`A` or its conjugate transpose is stored.
:math:`\mathrm{transr} = \texttt{'N'}`
The RFP representation of the matrix :math:`A` is stored.
:math:`\mathrm{transr} = \texttt{'C'}`
The conjugate transpose of the RFP representation of the matrix :math:`A` is stored.
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**n** : int
:math:`n`, the order of the matrix :math:`A`.
**ar** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
The upper or lower :math:`n\times n` triangular matrix :math:`A` (as specified by :math:`\mathrm{uplo}`) in either normal or transposed RFP format (as specified by :math:`\mathrm{transr}`). The storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f07/f07intro.html#recomm_32a>`__.
**Returns**
**ap** : complex, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
The :math:`n\times n` triangular matrix :math:`A`, packed by columns.
.. _f01vm-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{transr}`.
Constraint: :math:`\mathrm{transr} = \texttt{'N'}` or :math:`\texttt{'C'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
.. _f01vm-py2-py-notes:
**Notes**
``ztfttp`` packs a complex :math:`n\times n` triangular matrix :math:`A`, stored in RFP format, to packed format.
This function is intended for possible use in conjunction with functions from submodule :mod:`~naginterfaces.library.blas`, submodule :mod:`~naginterfaces.library.blast` and submodule :mod:`~naginterfaces.library.lapacklin` where some functions that use triangular matrices store them in RFP format. The RFP storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f07/f07intro.html#recomm_32a>`__ and the packed storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f07/f07intro.html#recomm_32>`__.
.. _f01vm-py2-py-references:
**References**
Gustavson, F G, Waśniewski, J, Dongarra, J J and Langou, J, 2010, `Rectangular full packed format for Cholesky's algorithm: factorization, solution, and inversion`, ACM Trans. Math. Software (37, 2)
"""
raise NotImplementedError
[docs]def real_tri_pack(job, uplo, diag, a, b):
r"""
``real_tri_pack`` copies a real triangular matrix stored in a packed one-dimensional array into an unpacked two-dimensional array, or vice versa.
.. _f01za-py2-py-doc:
For full information please refer to the NAG Library document for f01za
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01zaf.html
.. _f01za-py2-py-parameters:
**Parameters**
**job** : str, length 1
Specifies whether the triangular matrix is to be packed or unpacked.
:math:`\mathrm{job} = \texttt{'P'}` (Pack)
The matrix is to be packed into array :math:`\mathrm{b}`.
:math:`\mathrm{job} = \texttt{'U'}` (Unpack)
The matrix is to be unpacked into array :math:`\mathrm{a}`.
**uplo** : str, length 1
Specifies the type of the matrix to be copied
:math:`\mathrm{uplo} = \texttt{'L'}` (Lower)
The matrix is lower triangular. In this case the packed vector holds, or will hold on exit, the matrix elements in the following order: :math:`\left(1, 1\right),\left(2, 1\right),\ldots,\left(n, 1\right),\left(2, 2\right),\left(3, 2\right),\ldots,\left(n, 2\right)`, etc..
:math:`\mathrm{uplo} = \texttt{'U'}` (Upper)
The matrix is upper triangular. In this case the packed vector holds, or will hold on exit, the matrix elements in the following order: :math:`\left(1, 1\right)`, :math:`\left(1, 2\right)`, :math:`\left(2, 2\right)`, :math:`\left(1, 3\right)`, :math:`\left(2, 3\right)`, :math:`\left(3, 3\right)`, :math:`\left(1, 4\right)`, etc..
**diag** : str, length 1
Must specify whether the diagonal elements of the matrix are to be copied.
:math:`\mathrm{diag} = \texttt{'B'}` (Blank)
The diagonal elements of the matrix are not referenced and not copied.
:math:`\mathrm{diag} = \texttt{'U'}` (Unit diagonal)
The diagonal elements of the matrix are not referenced, but are assumed all to be unity, and are copied as such.
:math:`\mathrm{diag} = \texttt{'N'}` (Non-unit diagonal)
The diagonal elements of the matrix are referenced and copied.
**a** : float, array-like, shape :math:`\left(n, n\right)`
If :math:`\mathrm{job} = \texttt{'P'}`, the leading :math:`\textit{n}` by :math:`\textit{n}` part of :math:`\mathrm{a}` must contain the matrix to be copied, stored in unpacked form, in the upper or lower triangle depending on argument :math:`\mathrm{uplo}`. The opposite triangle of :math:`\mathrm{a}` is not referenced and need not be assigned.
**b** : float, array-like, shape :math:`\left(\left(n\times \left(n+1\right)\right)/2\right)`
If :math:`\mathrm{job} = \texttt{'U'}`, :math:`\mathrm{b}` must contain the triangular matrix packed by column.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
If :math:`\mathrm{job} = \texttt{'U'}`, the leading :math:`\textit{n}` by :math:`\textit{n}` part of array :math:`\mathrm{a}` contains the copied matrix, stored in unpacked form, in the upper or lower triangle depending on argument :math:`\mathrm{uplo}`. The opposite triangle of :math:`\mathrm{a}` is not referenced.
**b** : float, ndarray, shape :math:`\left(\left(n\times \left(n+1\right)\right)/2\right)`
If :math:`\mathrm{job} = \texttt{'P'}`, :math:`\mathrm{b}` contains the triangular matrix packed by column.
Note that :math:`\mathrm{b}` must have space for the diagonal elements of the matrix, even if these are not stored.
.. _f01za-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{job} \neq \texttt{'P'}` or :math:`\texttt{'U'}`: :math:`\mathrm{job} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{uplo} \neq \texttt{'U'}` or :math:`\texttt{'L'}`: :math:`\mathrm{uplo} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{diag} \neq \texttt{'N'}`, :math:`\texttt{'U'}` or :math:`\texttt{'B'}`: :math:`\mathrm{diag} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`4`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 1`.
.. _f01za-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``real_tri_pack`` unpacks a triangular matrix stored in a vector into a two-dimensional array, or packs a triangular matrix stored in a two-dimensional array into a vector.
The matrix is packed by column.
This function is intended for possible use in conjunction with functions from submodule :mod:`~naginterfaces.library.blas`, submodule :mod:`~naginterfaces.library.lapacklin` and submodule :mod:`~naginterfaces.library.lapackeig` where some functions that use triangular matrices store them in the packed form described below.
"""
raise NotImplementedError
[docs]def complex_tri_pack(job, uplo, diag, a, b):
r"""
``complex_tri_pack`` copies a complex triangular matrix stored in a packed one-dimensional array into an unpacked two-dimensional array, or vice versa.
.. _f01zb-py2-py-doc:
For full information please refer to the NAG Library document for f01zb
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01zbf.html
.. _f01zb-py2-py-parameters:
**Parameters**
**job** : str, length 1
Specifies whether the triangular matrix is to be packed or unpacked.
:math:`\mathrm{job} = \texttt{'P'}` (Pack)
The matrix is to be packed into array :math:`\mathrm{b}`.
:math:`\mathrm{job} = \texttt{'U'}` (Unpack)
The matrix is to be unpacked into array :math:`\mathrm{a}`.
**uplo** : str, length 1
Specifies the type of the matrix to be copied
:math:`\mathrm{uplo} = \texttt{'L'}` (Lower)
The matrix is lower triangular. In this case the packed vector holds, or will hold on exit, the matrix elements in the following order: :math:`\left(1, 1\right),\left(2, 1\right),\ldots,\left(n, 1\right),\left(2, 2\right),\left(3, 2\right),\ldots,\left(n, 2\right)`, etc..
:math:`\mathrm{uplo} = \texttt{'U'}` (Upper)
The matrix is upper triangular. In this case the packed vector holds, or will hold on exit, the matrix elements in the following order: :math:`\left(1, 1\right)`, :math:`\left(1, 2\right)`, :math:`\left(2, 2\right)`, :math:`\left(1, 3\right)`, :math:`\left(2, 3\right)`, :math:`\left(3, 3\right)`, :math:`\left(1, 4\right)`, etc..
**diag** : str, length 1
Must specify whether the diagonal elements of the matrix are to be copied.
:math:`\mathrm{diag} = \texttt{'B'}` (Blank)
The diagonal elements of the matrix are not referenced and not copied.
:math:`\mathrm{diag} = \texttt{'U'}` (Unit diagonal)
The diagonal elements of the matrix are not referenced, but are assumed all to be unity, and are copied as such.
:math:`\mathrm{diag} = \texttt{'N'}` (Non-unit diagonal)
The diagonal elements of the matrix are referenced and copied.
**a** : complex, array-like, shape :math:`\left(n, n\right)`
If :math:`\mathrm{job} = \texttt{'P'}`, the leading :math:`\textit{n}` by :math:`\textit{n}` part of :math:`\mathrm{a}` must contain the matrix to be copied, stored in unpacked form, in the upper or lower triangle depending on argument :math:`\mathrm{uplo}`. The opposite triangle of :math:`\mathrm{a}` is not referenced and need not be assigned.
**b** : complex, array-like, shape :math:`\left(\left(n\times \left(n+1\right)\right)/2\right)`
If :math:`\mathrm{job} = \texttt{'U'}`, :math:`\mathrm{b}` must contain the triangular matrix packed by column.
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
If :math:`\mathrm{job} = \texttt{'U'}`, the leading :math:`\textit{n}` by :math:`\textit{n}` part of array :math:`\mathrm{a}` contains the copied matrix, stored in unpacked form, in the upper or lower triangle depending on argument :math:`\mathrm{uplo}`. The opposite triangle of :math:`\mathrm{a}` is not referenced.
**b** : complex, ndarray, shape :math:`\left(\left(n\times \left(n+1\right)\right)/2\right)`
If :math:`\mathrm{job} = \texttt{'P'}`, :math:`\mathrm{b}` contains the triangular matrix packed by column.
Note that :math:`\mathrm{b}` must have space for the diagonal elements of the matrix, even if these are not stored.
.. _f01zb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{job} \neq \texttt{'P'}` or :math:`\texttt{'U'}`: :math:`\mathrm{job} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{uplo} \neq \texttt{'U'}` or :math:`\texttt{'L'}`: :math:`\mathrm{uplo} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{diag} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}`, :math:`\texttt{'U'}` or :math:`\texttt{'B'}`.
(`errno` :math:`4`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 1`.
.. _f01zb-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``complex_tri_pack`` unpacks a triangular matrix stored in a vector into a two-dimensional array, or packs a triangular matrix stored in a two-dimensional array into a vector.
The matrix is packed by column.
This function is intended for possible use in conjunction with functions from submodule :mod:`~naginterfaces.library.blas`, submodule :mod:`~naginterfaces.library.lapacklin` and submodule :mod:`~naginterfaces.library.lapackeig`, where some functions that use triangular matrices store them in the packed form described below.
"""
raise NotImplementedError
[docs]def real_band_pack(job, kl, ku, a, b):
r"""
``real_band_pack`` copies a real band matrix stored in a packed array into an unpacked array, or vice versa.
.. _f01zc-py2-py-doc:
For full information please refer to the NAG Library document for f01zc
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01zcf.html
.. _f01zc-py2-py-parameters:
**Parameters**
**job** : str, length 1
Specifies whether the band matrix is to be packed or unpacked.
:math:`\mathrm{job} = \texttt{'P'}` (Pack)
The band matrix is to be packed into array :math:`\mathrm{b}`.
:math:`\mathrm{job} = \texttt{'U'}` (Unpack)
The band matrix is to be unpacked into array :math:`\mathrm{a}`.
**kl** : int
:math:`k_l`, the number of subdiagonals of the band matrix.
**ku** : int
:math:`k_u`, the number of superdiagonals of the band matrix.
**a** : float, array-like, shape :math:`\left(m, n\right)`
If :math:`\mathrm{job} = \texttt{'P'}`, the leading :math:`m\times n` part of :math:`\mathrm{a}` must contain the band matrix stored in unpacked form. Elements of the array that lie outside the banded part of the matrix are not referenced and need not be assigned.
**b** : float, array-like, shape :math:`\left(\left(\mathrm{kl}+\mathrm{ku}+1\right), \min\left({m+\mathrm{ku}},n\right)\right)`
If :math:`\mathrm{job} = \texttt{'U'}`, :math:`\mathrm{b}` must contain the band matrix in packed form, in the leading :math:`\left(k_l+k_u+1\right)\times \mathrm{min}\left({m+k_u}, n\right)` part of the array. The matrix is packed column by column, with the leading diagonal of the matrix in row :math:`\left(k_u+1\right)` of :math:`\mathrm{b}`, the first superdiagonal starting at position :math:`2` in row :math:`k_u`, the first subdiagonal starting at position :math:`1` in row :math:`\left(k_u+2\right)`, and so on. Elements of :math:`\mathrm{b}` that are not needed to store the band matrix, for instance the leading :math:`k_u\times k_u` triangle, are not referenced and need not be assigned.
**Returns**
**a** : float, ndarray, shape :math:`\left(m, n\right)`
If :math:`\mathrm{job} = \texttt{'U'}`, the leading :math:`m\times n` part of :math:`\mathrm{a}` contains the band matrix stored in unpacked form. Elements of the leading :math:`m\times n` part of :math:`\mathrm{a}` that are not within the banded part of the matrix are assigned the value zero.
**b** : float, ndarray, shape :math:`\left(\left(\mathrm{kl}+\mathrm{ku}+1\right), \min\left({m+\mathrm{ku}},n\right)\right)`
If :math:`\mathrm{job} = \texttt{'P'}`, :math:`\mathrm{b}` contains the band matrix stored in packed form. Elements of :math:`\mathrm{b}` that are not needed to store the band matrix are not referenced.
.. _f01zc-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{job} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{job} = \texttt{'P'}` or :math:`\texttt{'U'}`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{kl} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{kl}\geq 0`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{ku} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ku}\geq 0`.
(`errno` :math:`5`)
On entry, :math:`\textit{ldb} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{kl} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{ku} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{ldb}\geq \mathrm{kl}+\mathrm{ku}+1`.
(`errno` :math:`6`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n > 0`.
(`errno` :math:`6`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m > 0`.
.. _f01zc-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``real_band_pack`` unpacks a band matrix that is stored in a packed array, or packs a band matrix that is stored in an unpacked array.
The band matrix has :math:`m` rows, :math:`n` columns, :math:`k_l` nonzero subdiagonals, and :math:`k_u` nonzero superdiagonals.
This function is intended for possible use in conjunction with functions from submodule :mod:`~naginterfaces.library.blas`, submodule :mod:`~naginterfaces.library.lapacklin` and submodule :mod:`~naginterfaces.library.lapackeig`, where functions that use band matrices store them in the packed form described below.
"""
raise NotImplementedError
[docs]def complex_band_pack(job, kl, ku, a, b):
r"""
``complex_band_pack`` copies a complex band matrix stored in a packed array into an unpacked array, or vice versa.
.. _f01zd-py2-py-doc:
For full information please refer to the NAG Library document for f01zd
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f01/f01zdf.html
.. _f01zd-py2-py-parameters:
**Parameters**
**job** : str, length 1
Specifies whether the band matrix is to be packed or unpacked.
:math:`\mathrm{job} = \texttt{'P'}` (Pack)
The band matrix is to be packed into array :math:`\mathrm{b}`.
:math:`\mathrm{job} = \texttt{'U'}` (Unpack)
The band matrix is to be unpacked into array :math:`\mathrm{a}`.
**kl** : int
:math:`k_l`, the number of subdiagonals of the band matrix.
**ku** : int
:math:`k_u`, the number of superdiagonals of the band matrix.
**a** : complex, array-like, shape :math:`\left(m, n\right)`
If :math:`\mathrm{job} = \texttt{'P'}`, the leading :math:`m\times n` part of :math:`\mathrm{a}` must contain the band matrix stored in unpacked form. Elements of the array that lie outside the banded part of the matrix are not referenced and need not be assigned.
**b** : complex, array-like, shape :math:`\left(\left(\mathrm{kl}+\mathrm{ku}+1\right), \min\left({m+\mathrm{ku}},n\right)\right)`
If :math:`\mathrm{job} = \texttt{'U'}`, :math:`\mathrm{b}` must contain the band matrix in packed form, in the leading :math:`\left(k_l+k_u+1\right)\times \mathrm{min}\left({m+k_u}, n\right)` part of the array. The matrix is packed column by column, with the leading diagonal of the matrix in row :math:`\left(k_u+1\right)` of :math:`\mathrm{b}`, the first superdiagonal starting at position :math:`2` in row :math:`k_u`, the first subdiagonal starting at position :math:`1` in row :math:`\left(k_u+2\right)`, and so on. Elements of :math:`\mathrm{b}` that are not needed to store the band matrix, for instance the leading :math:`k_u\times k_u` triangle, are not referenced and need not be assigned.
**Returns**
**a** : complex, ndarray, shape :math:`\left(m, n\right)`
If :math:`\mathrm{job} = \texttt{'U'}`, the leading :math:`m\times n` part of :math:`\mathrm{a}` contains the band matrix stored in unpacked form. Elements of the leading :math:`m\times n` part of :math:`\mathrm{a}` that are not within the banded part of the matrix are assigned the value zero.
**b** : complex, ndarray, shape :math:`\left(\left(\mathrm{kl}+\mathrm{ku}+1\right), \min\left({m+\mathrm{ku}},n\right)\right)`
If :math:`\mathrm{job} = \texttt{'P'}`, :math:`\mathrm{b}` contains the band matrix stored in packed form. Elements of :math:`\mathrm{b}` that are not needed to store the band matrix are not referenced.
.. _f01zd-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{job} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{job} = \texttt{'P'}` or :math:`\texttt{'U'}`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{kl} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{kl}\geq 0`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{ku} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ku}\geq 0`.
(`errno` :math:`5`)
On entry, :math:`\textit{ldb} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{kl} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{ku} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{ldb}\geq \mathrm{kl}+\mathrm{ku}+1`.
(`errno` :math:`6`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n > 0`.
(`errno` :math:`6`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m > 0`.
.. _f01zd-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``complex_band_pack`` unpacks a band matrix that is stored in a packed array, or packs a band matrix that is stored in an unpacked array.
The band matrix has :math:`m` rows, :math:`n` columns, :math:`k_l` nonzero subdiagonals, and :math:`k_u` nonzero superdiagonals.
This function is intended for possible use in conjunction with functions from submodule :mod:`~naginterfaces.library.blas`, submodule :mod:`~naginterfaces.library.lapacklin` and submodule :mod:`~naginterfaces.library.lapackeig`, where functions that use band matrices store them in the packed form described below.
"""
raise NotImplementedError
