# Source code for naginterfaces.library.matop

# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 28.5 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://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f01/f01intro.html#background1>__ where these problems are discussed.

--------
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**

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://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f01/f01intro.html
"""

[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://www.nag.com/numeric/nl/nagdoc_28.5/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.

For full information please refer to the NAG Library document for f01ad

**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.

**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.

**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}.

**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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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::

and on exit it holds

.. math::

.. _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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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

--------
: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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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 real_gen_rq_formq(wheret, m, nrowp, a, zeta):
r"""
real_gen_rq_formq returns the first :math:\ell rows of the real :math:n\times n orthogonal matrix :math:P^\mathrm{T}, where :math:P is given as the product of Householder transformation matrices.

This function is intended for use following :meth:real_gen_rq.

.. _f01qk-py2-py-doc:

For full information please refer to the NAG Library document for f01qk

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f01/f01qkf.html

.. _f01qk-py2-py-parameters:

**Parameters**
**wheret** : str, length 1
Indicates where the elements of :math:\zeta are to be found.

:math:\mathrm{wheret} = \texttt{'I'} (In :math:\mathrm{a})

The elements of :math:\zeta are in :math:\mathrm{a}.

:math:\mathrm{wheret} = \texttt{'S'} (Separate)

The elements of :math:\zeta are separate from :math:\mathrm{a}, in :math:\mathrm{zeta}.

**m** : int
:math:m, the number of rows of the matrix :math:A.

**nrowp** : int
:math:\ell, the required number of rows of :math:P.

If :math:\mathrm{nrowp} = 0, an immediate return is effected.

**a** : float, array-like, shape :math:\left(\max\left(\mathrm{m},\mathrm{nrowp}\right), n\right)
The leading :math:m\times m strictly lower triangular part of the array :math:\mathrm{a}, and the :math:m\times \left(n-m\right) rectangular part of :math:\mathrm{a} with top left-hand corner at element :math:\mathrm{a}[0,\mathrm{m}] must contain details of the matrix :math:P. In addition, if :math:\mathrm{wheret} = \texttt{'I'}, the diagonal elements of :math:\mathrm{a} must contain the elements of :math:\zeta.

**zeta** : float, array-like, shape :math:\left(:\right)
Note: the required length for this argument is determined as follows: if :math:\mathrm{wheret}=\texttt{'S'}: :math:\mathrm{m}; otherwise: :math:1.

With :math:\mathrm{wheret} = \texttt{'S'}, the array :math:\mathrm{zeta} must contain the elements of :math:\zeta. If :math:\mathrm{zeta}[k-1] = 0.0 then :math:P_k is assumed to be :math:I, otherwise :math:\mathrm{zeta}[k-1] is assumed to contain :math:\zeta_k.

When :math:\mathrm{wheret} = \texttt{'I'}, the array :math:\mathrm{zeta} is not referenced.

**Returns**
**a** : float, ndarray, shape :math:\left(\max\left(\mathrm{m},\mathrm{nrowp}\right), n\right)
The first :math:\mathrm{nrowp} rows of the array :math:\mathrm{a} are overwritten by the first :math:\mathrm{nrowp} rows of the :math:n\times n orthogonal matrix :math:P^T.

.. _f01qk-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, :math:\textit{lda} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nrowp} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{lda}\geq \mathrm{max}\left(\mathrm{m}, \mathrm{nrowp}\right).

(errno :math:-1)
On entry, :math:\mathrm{nrowp} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nrowp}\geq 0 and :math:\mathrm{nrowp}\leq n.

(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.

(errno :math:-1)
On entry, :math:\mathrm{wheret} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{wheret} = \texttt{'I'} or :math:\texttt{'S'}.

.. _f01qk-py2-py-notes:

**Notes**
No equivalent traditional C interface for this routine exists in the NAG Library.

:math:P is assumed to be given by

.. math::
P = P_mP_{{m-1}} \cdots P_1

where

.. math::
\begin{array}{c} P_k = I - u_k u_k^\mathrm{T} \text{,} \\\\u_k = \begin{pmatrix}w_k\\\zeta_k\\0\\z_k\end{pmatrix}\text{,} \end{array}

:math:\zeta_k is a scalar, :math:w_k is a (:math:k-1) element vector and :math:z_k is an (:math:n-m) element vector. :math:w_k must be supplied in the :math:k\ th row of :math:\mathrm{a} in elements :math:\mathrm{a}[k-1,0],\ldots,\mathrm{a}[k-1,k-2]. :math:z_k must be supplied in the :math:k\ th row of :math:\mathrm{a} in elements :math:\mathrm{a}[k-1,m],\ldots,\mathrm{a}[k-1,n-1] and :math:\zeta_k must be supplied either in :math:\mathrm{a}[k-1,k-1] or in :math:\mathrm{zeta}[k-1], depending upon the argument :math:\mathrm{wheret}.

.. _f01qk-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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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 complex_gen_rq_formq(wheret, m, nrowp, a, theta):
r"""
complex_gen_rq_formq returns the first :math:\ell rows of the :math:n\times n unitary matrix :math:P^\mathrm{H}, where :math:P is given as the product of Householder transformation matrices.

This function is intended for use following :meth:complex_gen_rq.

.. _f01rk-py2-py-doc:

For full information please refer to the NAG Library document for f01rk

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f01/f01rkf.html

.. _f01rk-py2-py-parameters:

**Parameters**
**wheret** : str, length 1
Indicates where the elements of :math:\theta are to be found.

:math:\mathrm{wheret} = \texttt{'I'} (In :math:\mathrm{a})

The elements of :math:\theta are in :math:\mathrm{a}.

:math:\mathrm{wheret} = \texttt{'S'} (Separate)

The elements of :math:\theta are separate from :math:\mathrm{a}, in :math:\mathrm{theta}.

**m** : int
:math:m, the number of rows of the matrix :math:A.

**nrowp** : int
:math:\ell, the required number of rows of :math:P.

If :math:\mathrm{nrowp} = 0, an immediate return is effected.

**a** : complex, array-like, shape :math:\left(\max\left(\mathrm{m},\mathrm{nrowp}\right), n\right)
The leading :math:m\times m strictly lower triangular part of the array :math:\mathrm{a}, and the :math:m\times \left(n-m\right) rectangular part of :math:\mathrm{a} with top left-hand corner at element :math:\mathrm{a}[0,\mathrm{m}] must contain details of the matrix :math:P. In addition, if :math:\mathrm{wheret} = \texttt{'I'}, the diagonal elements of :math:\mathrm{a} must contain the elements of :math:\theta.

**theta** : complex, array-like, shape :math:\left(:\right)
Note: the required length for this argument is determined as follows: if :math:\mathrm{wheret}=\texttt{'S'}: :math:\mathrm{m}; otherwise: :math:1.

If :math:\mathrm{wheret} = \texttt{'S'}, the array :math:\mathrm{theta} must contain the elements of :math:\theta. If :math:\mathrm{theta}[k-1] = 0.0, :math:P_k is assumed to be :math:I, if :math:\mathrm{theta}[k-1] = \alpha and :math:\mathrm{Re}\left(\alpha \right) < 0.0, :math:P_k is assumed to be of the form

.. math::
P_k = \begin{pmatrix}I&0&0\\0&\alpha &0\\0&0&I\end{pmatrix}\text{,}

otherwise :math:\mathrm{theta}[k-1] is assumed to contain :math:\theta_k given by

.. math::
\theta_k = \left(\zeta_k, {\mathrm{Im}\left(\gamma_k\right)}\right)\text{.}

If :math:\mathrm{wheret} = \texttt{'I'}, the array :math:\mathrm{theta} is not referenced.

**Returns**
**a** : complex, ndarray, shape :math:\left(\max\left(\mathrm{m},\mathrm{nrowp}\right), n\right)
The first :math:\mathrm{nrowp} rows of the array :math:\mathrm{a} are overwritten by the first :math:\mathrm{nrowp} rows of the :math:n\times n unitary matrix :math:P^H.

.. _f01rk-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, :math:\textit{lda} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nrowp} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{lda}\geq \mathrm{max}\left(\mathrm{m}, \mathrm{nrowp}\right).

(errno :math:-1)
On entry, :math:\mathrm{nrowp} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nrowp}\geq 0 and :math:\mathrm{nrowp}\leq n.

(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.

(errno :math:-1)
On entry, :math:\mathrm{wheret} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{wheret} = \texttt{'I'} or :math:\texttt{'S'}.

.. _f01rk-py2-py-notes:

**Notes**
No equivalent traditional C interface for this routine exists in the NAG Library.

:math:P is assumed to be given by

.. math::
P = P_mP_{{m-1}} \cdots P_1\text{,}

where

.. math::
\begin{array}{c}P_k = I-\gamma_ku_ku_k^H\text{,}\\\\u_k = \begin{pmatrix}w_k\\\zeta_k\\0\\z_k\end{pmatrix} \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, :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:w_k must be supplied in the :math:k\ th row of :math:\mathrm{a} in elements :math:\mathrm{a}[k-1,0],\ldots,\mathrm{a}[k-1,k-2]. :math:z_k must be supplied in the :math:k\ th row of :math:\mathrm{a} in elements :math:\mathrm{a}[k-1,m],\ldots,\mathrm{a}[k-1,n-1] and :math:\theta_k, given by

.. math::
\theta_k = \left(\zeta_k, {\mathrm{Im}\left(\gamma_k\right)}\right)\text{,}

must be supplied either in :math:\mathrm{a}[k-1,k-1] or in :math:\mathrm{theta}[k-1], depending upon the argument :math:\mathrm{wheret}.

.. _f01rk-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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f07/f07intro.html#recomm_32a>__ and the packed storage format is described in the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f07/f07intro.html#recomm_32a>__ and the packed storage format is described in the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f07/f07intro.html#recomm_32a>__ and the packed storage format is described in the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f07/f07intro.html#recomm_32a>__ and the packed storage format is described in the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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://www.nag.com/numeric/nl/nagdoc_28.5/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