From efbbdbde27127d8593e3e9b4bb57dd94f24d8e43 Mon Sep 17 00:00:00 2001 From: sanderdemeyer Date: Tue, 30 Jun 2026 11:58:50 +0200 Subject: [PATCH 1/6] add docs Add documentation for general matrix functions, specifically for `exponential`. --- docs/src/user_interface/algorithms.md | 3 ++ docs/src/user_interface/matrix_functions.md | 34 ++++++++++++++++++++- 2 files changed, 36 insertions(+), 1 deletion(-) diff --git a/docs/src/user_interface/algorithms.md b/docs/src/user_interface/algorithms.md index 74c85a9b9..eeb665179 100644 --- a/docs/src/user_interface/algorithms.md +++ b/docs/src/user_interface/algorithms.md @@ -95,6 +95,9 @@ They all accept an optional `driver` keyword to select the computational backend | [`SVDViaPolar`](@ref) | SVD | `fixgauge`, `tol` | | [`PolarViaSVD`](@ref) | polar | positional `svd_alg` argument | | [`PolarNewton`](@ref) | polar | `maxiter`, `tol` | +| [`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). diff --git a/docs/src/user_interface/matrix_functions.md b/docs/src/user_interface/matrix_functions.md index 16a894431..b03b9b6e3 100644 --- a/docs/src/user_interface/matrix_functions.md +++ b/docs/src/user_interface/matrix_functions.md @@ -1,3 +1,35 @@ +```@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 rectangular matrix `A` is used in many quantum many-body problems. This is implemented in `LinearAlgebra`, which 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. This is done by `eig_full` and `eigh_full` via the algorithms [`MatrixFunctionViaEig`](@ref) and [`MatrixFunctionViaEigh`](@ref), 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 +``` + +```@autodocs; canonical=false +Modules = [MatrixAlgebraKit] +Filter = t -> t isa Type && (t <: MatrixAlgebraKit.MatrixFunctionViaLA || t <: MatrixAlgebraKit.MatrixFunctionViaEig || t <: MatrixAlgebraKit.MatrixFunctionViaEigh) +``` From 4b7d05d0aa1d715d2dfba440daddfc6232d704f6 Mon Sep 17 00:00:00 2001 From: Sander De Meyer <74001142+sanderdemeyer@users.noreply.github.com> Date: Tue, 30 Jun 2026 14:18:30 +0200 Subject: [PATCH 2/6] Update docs/src/user_interface/matrix_functions.md Co-authored-by: Lukas Devos --- docs/src/user_interface/matrix_functions.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/src/user_interface/matrix_functions.md b/docs/src/user_interface/matrix_functions.md index b03b9b6e3..c61faff03 100644 --- a/docs/src/user_interface/matrix_functions.md +++ b/docs/src/user_interface/matrix_functions.md @@ -22,8 +22,11 @@ Additionally, the `f!` method typically assumes that it is allowed to destroy th ## Exponential -The [exponential](https://en.wikipedia.org/wiki/Matrix_exponential) of a rectangular matrix `A` is used in many quantum many-body problems. This is implemented in `LinearAlgebra`, which 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. This is done by `eig_full` and `eigh_full` via the algorithms [`MatrixFunctionViaEig`](@ref) and [`MatrixFunctionViaEigh`](@ref), respectively. -Additionally, in order to calculate `exp(τ*A)`, the function `exponential` can be called with (τ,A), using the same algorithms as before. +The [exponential](https://en.wikipedia.org/wiki/Matrix_exponential) of a rectangular matrix `A` is used in many quantum many-body problems. +This is implemented in `LinearAlgebra`, which 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. +This is done by `eig_full` and `eigh_full` via the algorithms [`MatrixFunctionViaEig`](@ref) and [`MatrixFunctionViaEigh`](@ref), 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 From dc28447ed4f159756d80e86a792f4afecd0a57f8 Mon Sep 17 00:00:00 2001 From: sanderdemeyer Date: Tue, 30 Jun 2026 14:26:58 +0200 Subject: [PATCH 3/6] separate decompositions and matrix functions --- docs/src/user_interface/algorithms.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/src/user_interface/algorithms.md b/docs/src/user_interface/algorithms.md index eeb665179..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` | @@ -95,6 +97,11 @@ They all accept an optional `driver` keyword to select the computational backend | [`SVDViaPolar`](@ref) | SVD | `fixgauge`, `tol` | | [`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` | From 8788b2bcd4c95b66d1891353a842c97f5aa9b991 Mon Sep 17 00:00:00 2001 From: sanderdemeyer Date: Tue, 30 Jun 2026 14:31:12 +0200 Subject: [PATCH 4/6] change docs --- docs/src/user_interface/matrix_functions.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/src/user_interface/matrix_functions.md b/docs/src/user_interface/matrix_functions.md index c61faff03..263c8af02 100644 --- a/docs/src/user_interface/matrix_functions.md +++ b/docs/src/user_interface/matrix_functions.md @@ -30,9 +30,7 @@ This is done by `eig_full` and `eigh_full` via the algorithms [`MatrixFunctionVi ```@docs; canonical=false exponential -``` - -```@autodocs; canonical=false -Modules = [MatrixAlgebraKit] -Filter = t -> t isa Type && (t <: MatrixAlgebraKit.MatrixFunctionViaLA || t <: MatrixAlgebraKit.MatrixFunctionViaEig || t <: MatrixAlgebraKit.MatrixFunctionViaEigh) +MatrixAlgebraKit.MatrixFunctionViaLA +MatrixAlgebraKit.MatrixFunctionViaEig +MatrixAlgebraKit.MatrixFunctionViaEigh ``` From bd45f9b763d02a2222d1a91885cad513afeb6546 Mon Sep 17 00:00:00 2001 From: Sander De Meyer <74001142+sanderdemeyer@users.noreply.github.com> Date: Wed, 1 Jul 2026 10:40:56 +0200 Subject: [PATCH 5/6] Update docs/src/user_interface/matrix_functions.md Co-authored-by: Jutho --- docs/src/user_interface/matrix_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/user_interface/matrix_functions.md b/docs/src/user_interface/matrix_functions.md index 263c8af02..78c1bd306 100644 --- a/docs/src/user_interface/matrix_functions.md +++ b/docs/src/user_interface/matrix_functions.md @@ -22,7 +22,7 @@ Additionally, the `f!` method typically assumes that it is allowed to destroy th ## Exponential -The [exponential](https://en.wikipedia.org/wiki/Matrix_exponential) of a rectangular matrix `A` is used in many quantum many-body problems. +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. This is implemented in `LinearAlgebra`, which 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. This is done by `eig_full` and `eigh_full` via the algorithms [`MatrixFunctionViaEig`](@ref) and [`MatrixFunctionViaEigh`](@ref), respectively. From 79ba9b9c50b8c4e5034f5a6be2c9fbbb9497eca4 Mon Sep 17 00:00:00 2001 From: Sander De Meyer <74001142+sanderdemeyer@users.noreply.github.com> Date: Wed, 1 Jul 2026 10:41:28 +0200 Subject: [PATCH 6/6] Update docs/src/user_interface/matrix_functions.md Co-authored-by: Jutho --- docs/src/user_interface/matrix_functions.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/src/user_interface/matrix_functions.md b/docs/src/user_interface/matrix_functions.md index 78c1bd306..20564773c 100644 --- a/docs/src/user_interface/matrix_functions.md +++ b/docs/src/user_interface/matrix_functions.md @@ -23,10 +23,11 @@ Additionally, the `f!` method typically assumes that it is allowed to destroy th ## 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. -This is implemented in `LinearAlgebra`, which 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. -This is done by `eig_full` and `eigh_full` via the algorithms [`MatrixFunctionViaEig`](@ref) and [`MatrixFunctionViaEigh`](@ref), respectively. - Additionally, in order to calculate `exp(τ * A)`, the function `exponential` can be called with `(τ, A)`, using the same algorithms as before. +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