# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 29.3 `det` Chapter.
``det`` - Determinants
This module is concerned with the calculation of determinants of square matrices.
Functionality Index
-------------------
**Determinants of factorized matrices**
complex matrix: :meth:`complex_gen`
real matrix: :meth:`real_gen`
real symmetric band positive definite matrix: :meth:`real_band_sym`
real symmetric positive definite matrix: :meth:`real_sym`
For full information please refer to the NAG Library document
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/f03/f03intro.html
"""
# NAG Copyright 2017-2023.
[docs]def real_gen(a, ipiv):
r"""
``real_gen`` computes the determinant of a real :math:`n\times n` matrix :math:`A`. :meth:`lapacklin.dgetrf <naginterfaces.library.lapacklin.dgetrf>` must be called first to supply the matrix :math:`A` in factorized form.
.. _f03ba-py2-py-doc:
For full information please refer to the NAG Library document for f03ba
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/f03/f03baf.html
.. _f03ba-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A` in factorized form as returned by :meth:`lapacklin.dgetrf <naginterfaces.library.lapacklin.dgetrf>`.
**ipiv** : int, array-like, shape :math:`\left(n\right)`
The row interchanges used to factorize matrix :math:`A` as returned by :meth:`lapacklin.dgetrf <naginterfaces.library.lapacklin.dgetrf>`.
**Returns**
**d** : float
The determinant of :math:`A` is given by :math:`\mathrm{d}\times 2.0^{\mathrm{dexp}}`. It is given in this form to avoid overflow or underflow.
**dexp** : int
The determinant of :math:`A` is given by :math:`\mathrm{d}\times 2.0^{\mathrm{dexp}}`. It is given in this form to avoid overflow or underflow.
.. _f03ba-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 1`.
(`errno` :math:`4`)
The matrix :math:`A` is approximately singular.
.. _f03ba-py2-py-notes:
**Notes**
``real_gen`` computes the determinant of a real :math:`n\times n` matrix :math:`A` that has been factorized by a call to :meth:`lapacklin.dgetrf <naginterfaces.library.lapacklin.dgetrf>`.
The determinant of :math:`A` is the product of the diagonal elements of :math:`U` with the correct sign determined by the row interchanges.
.. _f03ba-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_sym(a):
r"""
``real_sym`` computes the determinant of a real :math:`n\times n` symmetric positive definite matrix :math:`A`. :meth:`lapacklin.dpotrf <naginterfaces.library.lapacklin.dpotrf>` must be called first to supply the symmetric matrix :math:`A` in Cholesky factorized form.
The storage (upper or lower triangular) used by :meth:`lapacklin.dpotrf <naginterfaces.library.lapacklin.dpotrf>` is not relevant to ``real_sym`` since only the diagonal elements of the factorized :math:`A` are referenced.
.. _f03bf-py2-py-doc:
For full information please refer to the NAG Library document for f03bf
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/f03/f03bff.html
.. _f03bf-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n, n\right)`
The lower or upper triangle of the Cholesky factorized form of the :math:`n\times n` positive definite symmetric matrix :math:`A`. Only the diagonal elements are referenced.
**Returns**
**d** : float
The determinant of :math:`A` is given by :math:`\mathrm{d}\times 2.0^{\mathrm{dexp}}`. It is given in this form to avoid overflow or underflow.
**dexp** : int
The determinant of :math:`A` is given by :math:`\mathrm{d}\times 2.0^{\mathrm{dexp}}`. It is given in this form to avoid overflow or underflow.
.. _f03bf-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n > 0`.
(`errno` :math:`4`)
The matrix :math:`A` is not positive definite.
.. _f03bf-py2-py-notes:
**Notes**
``real_sym`` computes the determinant of a real :math:`n\times n` symmetric positive definite matrix :math:`A` that has been factorized as :math:`A = U^\mathrm{T}U`, where :math:`U` is upper triangular, or :math:`A = LL^\mathrm{T}`, where :math:`L` is lower triangular.
The determinant is the product of the squares of the diagonal elements of :math:`U` or :math:`L`.
The Cholesky factorized form of the matrix must be supplied; this is returned by a call to :meth:`lapacklin.dpotrf <naginterfaces.library.lapacklin.dpotrf>`.
.. _f03bf-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_band_sym(uplo, kd, ab):
r"""
``real_band_sym`` computes the determinant of an :math:`n\times n` symmetric positive definite banded matrix :math:`A` that has been stored in band-symmetric storage. :meth:`lapacklin.dpbtrf <naginterfaces.library.lapacklin.dpbtrf>` must be called first to supply the Cholesky factorized form.
The storage (upper or lower triangular) used by :meth:`lapacklin.dpbtrf <naginterfaces.library.lapacklin.dpbtrf>` is relevant as this determines which elements of the stored factorized form are referenced.
.. _f03bh-py2-py-doc:
For full information please refer to the NAG Library document for f03bh
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/f03/f03bhf.html
.. _f03bh-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. This should not be altered following a call to :meth:`lapacklin.dpbtrf <naginterfaces.library.lapacklin.dpbtrf>`.
:math:`\mathrm{uplo} = \texttt{'U'}`
The upper triangular part of :math:`A` was originally stored and :math:`A` was factorized as :math:`U^\mathrm{T}U` where :math:`U` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
The lower triangular part of :math:`A` was originally stored and :math:`A` was factorized as :math:`LL^\mathrm{T}` where :math:`L` is lower triangular.
**kd** : int
:math:`k_d`, the number of superdiagonals or subdiagonals of the matrix :math:`A`.
**ab** : float, array-like, shape :math:`\left(\mathrm{kd}+1, n\right)`
The Cholesky factor of :math:`A`, as returned by :meth:`lapacklin.dpbtrf <naginterfaces.library.lapacklin.dpbtrf>`.
**Returns**
**d** : float
The determinant of :math:`A` is given by :math:`\mathrm{d}\times 2.0^{\mathrm{dexp}}`. It is given in this form to avoid overflow or underflow.
**dexp** : int
The determinant of :math:`A` is given by :math:`\mathrm{d}\times 2.0^{\mathrm{dexp}}`. It is given in this form to avoid overflow or underflow.
.. _f03bh-py2-py-errors:
**Raises**
**NagValueError**
(`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:`2`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n > 0`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{kd} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{kd}\geq 0`.
(`errno` :math:`6`)
The matrix :math:`A` is not positive definite.
.. _f03bh-py2-py-notes:
**Notes**
The determinant of :math:`A` is calculated using the Cholesky factorization :math:`A = U^\mathrm{T}U`, where :math:`U` is an upper triangular band matrix, or :math:`A = LL^\mathrm{T}`, where :math:`L` is a lower triangular band matrix.
The determinant of :math:`A` is the product of the squares of the diagonal elements of :math:`U` or :math:`L`.
.. _f03bh-py2-py-references:
**References**
Wilkinson, J H and Reinsch, C, 1971, `Handbook for Automatic Computation II, Linear Algebra`, Springer--Verlag
"""
raise NotImplementedError
[docs]def complex_gen(a, ipiv):
r"""
``complex_gen`` computes the determinant of a complex :math:`n\times n` matrix :math:`A`. :meth:`lapacklin.zgetrf <naginterfaces.library.lapacklin.zgetrf>` must be called first to supply the matrix :math:`A` in factorized form.
.. _f03bn-py2-py-doc:
For full information please refer to the NAG Library document for f03bn
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/f03/f03bnf.html
.. _f03bn-py2-py-parameters:
**Parameters**
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A` in factorized form as returned by :meth:`lapacklin.zgetrf <naginterfaces.library.lapacklin.zgetrf>`.
**ipiv** : int, array-like, shape :math:`\left(n\right)`
The row interchanges used to factorize matrix :math:`A` as returned by :meth:`lapacklin.zgetrf <naginterfaces.library.lapacklin.zgetrf>`.
**Returns**
**d** : complex
The mantissa of the real and imaginary parts of the determinant.
**dexp** : int, ndarray, shape :math:`\left(2\right)`
The exponents for the real and imaginary parts of the determinant. The determinant, :math:`d = \left(d_r, d_i\right)`, is returned as :math:`d_r = D_r\times 2^j` and :math:`d_i = D_i\times 2^k`, where :math:`\mathrm{d} = \left(D_r, D_i\right)` and :math:`j` and :math:`k` are stored in the first and second elements respectively of the array :math:`\mathrm{dexp}` on successful exit.
.. _f03bn-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 1`.
(`errno` :math:`4`)
The matrix :math:`A` is approximately singular.
.. _f03bn-py2-py-notes:
**Notes**
``complex_gen`` computes the determinant of a complex :math:`n\times n` matrix :math:`A` that has been factorized by a call to :meth:`lapacklin.zgetrf <naginterfaces.library.lapacklin.zgetrf>`.
The determinant of :math:`A` is the product of the diagonal elements of :math:`U` with the correct sign determined by the row interchanges.
.. _f03bn-py2-py-references:
**References**
Wilkinson, J H and Reinsch, C, 1971, `Handbook for Automatic Computation II, Linear Algebra`, Springer--Verlag
"""
raise NotImplementedError
