Source code for naginterfaces.library.det

# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 30.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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f03/f03intro.html
"""

# NAG Copyright 2017-2024.

[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://support.nag.com/numeric/nl/nagdoc_30.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://support.nag.com/numeric/nl/nagdoc_30.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://support.nag.com/numeric/nl/nagdoc_30.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://support.nag.com/numeric/nl/nagdoc_30.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