diff --git a/docs/src/user_interface/algorithms.md b/docs/src/user_interface/algorithms.md index 74c85a9b9..e6030787d 100644 --- a/docs/src/user_interface/algorithms.md +++ b/docs/src/user_interface/algorithms.md @@ -80,9 +80,11 @@ DefaultAlgorithm ## Available Algorithm Types -The following high-level algorithm types are available. +There are several high-level algorithm types available. They all accept an optional `driver` keyword to select the computational backend; see [Driver Selection](@ref sec_driverselection) for details. +The following algorithms for matrix decompositions are available. + | Algorithm | Applicable decompositions | Key keyword arguments | |:----------|:--------------------------|:----------------------| | [`Householder`](@ref) | QR, LQ | `positive`, `pivoted`, `blocksize` | @@ -96,6 +98,14 @@ They all accept an optional `driver` keyword to select the computational backend | [`PolarViaSVD`](@ref) | polar | positional `svd_alg` argument | | [`PolarNewton`](@ref) | polar | `maxiter`, `tol` | +The following algorithms for matrix functions are available. + +| Algorithm | Applicable matrix functions | Key keyword arguments | +|:----------|:--------------------------|:----------------------| +| [`MatrixFunctionViaLA`](@ref) | exponential | | +| [`MatrixFunctionViaEig`](@ref) | exponential | `eig_alg` | +| [`MatrixFunctionViaEigh`](@ref) | exponential | `eigh_alg` | + For full docstring details on each algorithm type, see the corresponding section in [Decompositions](@ref). ## [Driver Selection](@id sec_driverselection) diff --git a/docs/src/user_interface/matrix_functions.md b/docs/src/user_interface/matrix_functions.md index 16a894431..20564773c 100644 --- a/docs/src/user_interface/matrix_functions.md +++ b/docs/src/user_interface/matrix_functions.md @@ -1,3 +1,37 @@ +```@meta +CurrentModule = MatrixAlgebraKit +CollapsedDocStrings = true +``` + # Matrix functions -Coming soon... +Another class of matrix algebra methods consists of calculating some function of a single input `A`. +In order to streamline these functions, they all follow a similar common code pattern. +For a given function `f`, this consists of the following methods: + +```julia +f(A; kwargs...) -> F... +f!(A, [F]; kwargs...) -> F... +``` + +Here, the input matrix is always the first argument, and optionally the output can be provided as well. +The keywords are algorithm-specific, and can be used to influence the behavior of the algorithms. +For a full description of how to select and configure algorithms, see [Algorithm Selection](@ref sec_algorithmselection). +Importantly, for generic code patterns it is recommended to always use the output `F` explicitly, since some implementations may not be able to reuse the provided memory. +Additionally, the `f!` method typically assumes that it is allowed to destroy the input `A`, and making use of the contents of `A` afterwards should be deemed as undefined behavior. + +## Exponential + +The [exponential](https://en.wikipedia.org/wiki/Matrix_exponential) of a square matrix `A` is used in many scientific applications, as it arises in the solution of an autonomous linear differential equation. +An implementation for the matrix exponential based on a Padé approximation is available in `LinearAlgebra`, and can be accessed by the algorithm [`MatrixFunctionViaLA`](@ref). +For more generic data types, the exponential can be calculated by first calculating the (hermitian) eigenvalue decomposition, and then computing +the scalar exponential of the diagonal elements. +This strategy is implemented via the algorithms [`MatrixFunctionViaEig`](@ref) and [`MatrixFunctionViaEigh`](@ref), and call `eig_full` and `eigh_full`, respectively. +Additionally, in order to calculate `exp(τ * A)`, the function `exponential` can be called with `(τ, A)`, using the same algorithms as before. + +```@docs; canonical=false +exponential +MatrixAlgebraKit.MatrixFunctionViaLA +MatrixAlgebraKit.MatrixFunctionViaEig +MatrixAlgebraKit.MatrixFunctionViaEigh +```