Merge branch 'main' into testsuite

Author: kshyatt

.github/workflows/Documentation.yml

@@ -25,7 +25,7 @@ jobs:
         arch:
           - x64
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: julia-actions/setup-julia@latest
         with:
           version: ${{ matrix.version }}

.github/workflows/DocumentationCleanup.yml

@@ -16,7 +16,7 @@ jobs:
       contents: write
     steps:
       - name: Checkout gh-pages branch
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           ref: gh-pages
       - name: Delete preview and history + push changes

Project.toml

@@ -1,7 +1,7 @@
 name = "MatrixAlgebraKit"
 uuid = "6c742aac-3347-4629-af66-fc926824e5e4"
 authors = ["Jutho <[email protected]> and contributors"]
-version = "0.5.0"
+version = "0.6.0"
 
 [deps]
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
@@ -12,13 +12,15 @@ ChainRulesCore = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4"
 CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba"
 GenericLinearAlgebra = "14197337-ba66-59df-a3e3-ca00e7dcff7a"
 GenericSchur = "c145ed77-6b09-5dd9-b285-bf645a82121e"
+Mooncake = "da2b9cff-9c12-43a0-ae48-6db2b0edb7d6"
 
 [extensions]
 MatrixAlgebraKitChainRulesCoreExt = "ChainRulesCore"
 MatrixAlgebraKitAMDGPUExt = "AMDGPU"
 MatrixAlgebraKitCUDAExt = "CUDA"
 MatrixAlgebraKitGenericLinearAlgebraExt = "GenericLinearAlgebra"
 MatrixAlgebraKitGenericSchurExt = "GenericSchur"
+MatrixAlgebraKitMooncakeExt = "Mooncake"
 
 [compat]
 AMDGPU = "2"
@@ -31,6 +33,7 @@ GenericSchur = "0.5.6"
 JET = "0.9, 0.10"
 LinearAlgebra = "1"
 Random = "1"
+Mooncake = "0.4.174"
 SafeTestsets = "0.1"
 StableRNGs = "1"
 Test = "1"
@@ -45,11 +48,12 @@ ChainRulesTestUtils = "cdddcdb0-9152-4a09-a978-84456f9df70a"
 CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba"
 JET = "c3a54625-cd67-489e-a8e7-0a5a0ff4e31b"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+Mooncake = "da2b9cff-9c12-43a0-ae48-6db2b0edb7d6"
 SafeTestsets = "1bc83da4-3b8d-516f-aca4-4fe02f6d838f"
 StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 TestExtras = "5ed8adda-3752-4e41-b88a-e8b09835ee3a"
 Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"
 
 [targets]
-test = ["Aqua", "JET", "SafeTestsets", "Test", "TestExtras", "ChainRulesCore", "ChainRulesTestUtils", "StableRNGs", "Zygote", "CUDA", "AMDGPU", "GenericLinearAlgebra", "GenericSchur", "Random"]
+test = ["Aqua", "JET", "SafeTestsets", "Test", "TestExtras", "ChainRulesCore", "ChainRulesTestUtils", "StableRNGs", "Zygote", "CUDA", "AMDGPU", "GenericLinearAlgebra", "GenericSchur", "Random", "Mooncake"]

docs/make.jl

@@ -57,6 +57,7 @@ makedocs(;
         ],
         "Developer Interface" => "dev_interface.md",
         "Library" => "library.md",
+        "Changelog" => "changelog.md",
     ],
     checkdocs = :exports,
     doctest = true,

docs/src/changelog.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Guidelines for updating this changelog
+
+When making changes to this project, please update the "Unreleased" section with your changes under the appropriate category:
+
+- **Added** for new features.
+- **Changed** for changes in existing functionality.
+- **Deprecated** for soon-to-be removed features.
+- **Removed** for now removed features.
+- **Fixed** for any bug fixes.
+- **Security** in case of vulnerabilities.
+
+When releasing a new version, move the "Unreleased" changes to a new version section with the release date.
+
+[Unreleased]: https://github.com/QuantumKitHub/MatrixAlgebraKit.jl/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/QuantumKitHub/MatrixAlgebraKit.jl/releases/tag/v0.6.0
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+## [0.6.0] - 2025-11-14
+
+### Added
+- New `project_isometric` function for projecting matrices onto isometric manifold ([#67](https://github.com/QuantumKitHub/MatrixAlgebraKit.jl/pull/67))
+- New `PolarNewton` algorithm for polar decomposition ([#67](https://github.com/QuantumKitHub/MatrixAlgebraKit.jl/pull/67))
+- New matrix property functions: `ishermitian`, `isantihermitian`, `hermitianpart!`, `hermitianpart`, `antihermitianpart!`, and `antihermitianpart` ([#64](https://github.com/QuantumKitHub/MatrixAlgebraKit.jl/pull/64))
+- Support for `BigFloat` via new `GenericLinearAlgebra` extension ([#87](https://github.com/QuantumKitHub/MatrixAlgebraKit.jl/pull/87))
+- Mooncake reverse-mode AD rules ([#85](https://github.com/QuantumKitHub/MatrixAlgebraKit.jl/pull/85))
+- GPU support for image and null space computations ([#82](https://github.com/QuantumKitHub/MatrixAlgebraKit.jl/pull/82))
+- GPU support for polar decomposition ([#83](https://github.com/QuantumKitHub/MatrixAlgebraKit.jl/pull/83))
+- GPU support for new projection operations ([#81](https://github.com/QuantumKitHub/MatrixAlgebraKit.jl/pull/81))
+- Output truncation error for truncated decompositions ([#75](https://github.com/QuantumKitHub/MatrixAlgebraKit.jl/pull/75))
+- Documentation for truncated decomposition keyword arguments ([#71](https://github.com/QuantumKitHub/MatrixAlgebraKit.jl/pull/71))
+- Default algorithm implementations for GPU wrapper array types ([#49](https://github.com/QuantumKitHub/MatrixAlgebraKit.jl/pull/49))
+
+### Changed
+
+- Made `gaugefix!` optional ([#95](https://github.com/QuantumKitHub/MatrixAlgebraKit.jl/pull/95))
+- Renamed `isisometry` to `isisometric` for consistency with `project_isometric` ([#73](https://github.com/QuantumKitHub/MatrixAlgebraKit.jl/pull/73))
+- Refactored `left_orth`, `right_orth`, `left_null` and `right_null` interface ([#79](https://github.com/QuantumKitHub/MatrixAlgebraKit.jl/pull/79))
+- Improved GPU support for SVD operations ([#80](https://github.com/QuantumKitHub/MatrixAlgebraKit.jl/pull/80))
+- Loosened strictness on hermitian checks ([#78](https://github.com/QuantumKitHub/MatrixAlgebraKit.jl/pull/78))
+- Updated pullback tolerances ([#92](https://github.com/QuantumKitHub/MatrixAlgebraKit.jl/pull/92))
+
+### Removed
+
+### Fixed

docs/src/user_interface/decompositions.md

@@ -72,6 +72,11 @@ eigh_trunc
 eigh_vals
 ```
 
+!!! note "Gauge Degrees of Freedom"
+    The eigenvectors returned by these functions have residual phase degrees of freedom.
+    By default, MatrixAlgebraKit applies a gauge fixing convention to ensure reproducible results.
+    See [Gauge choices](@ref sec_gaugefix) for more details.
+
 Alongside these functions, we provide a LAPACK-based implementation for dense arrays, as provided by the following algorithms:
 
 ```@autodocs; canonical=false
@@ -89,6 +94,11 @@ eig_trunc
 eig_vals
 ```
 
+!!! note "Gauge Degrees of Freedom"
+    The eigenvectors returned by these functions have residual phase degrees of freedom.
+    By default, MatrixAlgebraKit applies a gauge fixing convention to ensure reproducible results.
+    See [Gauge choices](@ref sec_gaugefix) for more details.
+
 Alongside these functions, we provide a LAPACK-based implementation for dense arrays, as provided by the following algorithms:
 
 ```@autodocs; canonical=false
@@ -137,6 +147,11 @@ svd_vals
 svd_trunc
 ```
 
+!!! note "Gauge Degrees of Freedom"
+    The singular vectors returned by these functions have residual phase degrees of freedom.
+    By default, MatrixAlgebraKit applies a gauge fixing convention to ensure reproducible results.
+    See [Gauge choices](@ref sec_gaugefix) for more details.
+
 MatrixAlgebraKit again ships with LAPACK-based implementations for dense arrays:
 
 ```@autodocs; canonical=false
@@ -371,3 +386,48 @@ norm(A * N1') < 1e-14 && norm(A * N2') < 1e-14 &&
 # output
 true
 ```
+
+## [Gauge choices](@id sec_gaugefix)
+
+Both eigenvalue and singular value decompositions have residual gauge degrees of freedom even when the eigenvalues or singular values are unique.
+These arise from the fact that even after normalization, the eigenvectors and singular vectors are only determined up to a phase factor.
+
+### Phase Ambiguity in Decompositions
+
+For the eigenvalue decomposition `A * V = V * D`, if `v` is an eigenvector with eigenvalue `λ` and `|v| = 1`, then so is `e^(iθ) * v` for any real phase `θ`.
+When `λ` is non-degenerate (i.e., has multiplicity 1), the eigenvector is unique up to this phase.
+
+Similarly, for the singular value decomposition `A = U * Σ * Vᴴ`, the singular vectors `u` and `v` corresponding to a non-degenerate singular value `σ` are unique only up to a common phase.
+We can replace `u → e^(iθ) * u` and `vᴴ → e^(-iθ) * vᴴ` simultaneously.
+
+### Gauge Fixing Convention
+
+To remove this phase ambiguity and ensure reproducible results, MatrixAlgebraKit implements a gauge fixing convention by default.
+The convention ensures that **the entry with the largest magnitude in each eigenvector or left singular vector is real and positive**.
+
+For eigenvectors, this means that for each column `v` of `V`, we multiply by `conj(sign(v[i]))` where `i` is the index of the entry with largest absolute value.
+
+For singular vectors, we apply the phase factor to both `u` and `v` based on the entry with largest magnitude in `u`.
+This preserves the decomposition `A = U * Σ * Vᴴ` while fixing the gauge.
+
+### Disabling Gauge Fixing
+
+Gauge fixing is enabled by default for all eigenvalue and singular value decompositions.
+If you prefer to obtain the raw results from the underlying computational routines without gauge fixing, you can disable it using the `fixgauge` keyword argument:
+
+```julia
+# With gauge fixing (default)
+D, V = eigh_full(A)
+
+# Without gauge fixing
+D, V = eigh_full(A; fixgauge = false)
+```
+
+The same keyword is available for `eig_full`, `eig_trunc`, `svd_full`, `svd_compact`, and `svd_trunc` functions.
+Additionally, the default value can also be controlled with a global toggle using [`MatrixAlgebraKit.default_fixgauge`](@ref).
+
+```@docs; canonical=false
+MatrixAlgebraKit.gaugefix!
+MatrixAlgebraKit.default_fixgauge
+```
+

ext/MatrixAlgebraKitGenericLinearAlgebraExt.jl

@@ -1,7 +1,7 @@
 module MatrixAlgebraKitGenericLinearAlgebraExt
 
 using MatrixAlgebraKit
-using MatrixAlgebraKit: sign_safe, check_input, diagview
+using MatrixAlgebraKit: sign_safe, check_input, diagview, gaugefix!, default_fixgauge
 using GenericLinearAlgebra: svd!, svdvals!, eigen!, eigvals!, Hermitian, qr!
 using LinearAlgebra: I, Diagonal, lmul!
 
@@ -13,18 +13,26 @@ for f! in (:svd_compact!, :svd_full!, :svd_vals!)
     @eval MatrixAlgebraKit.initialize_output(::typeof($f!), A::AbstractMatrix, ::GLA_QRIteration) = nothing
 end
 
-function MatrixAlgebraKit.svd_compact!(A::AbstractMatrix, USVᴴ, ::GLA_QRIteration)
+function MatrixAlgebraKit.svd_compact!(A::AbstractMatrix, USVᴴ, alg::GLA_QRIteration)
     F = svd!(A)
     U, S, Vᴴ = F.U, Diagonal(F.S), F.Vt
-    return MatrixAlgebraKit.gaugefix!(svd_compact!, U, S, Vᴴ, size(A)...)
+
+    do_gauge_fix = get(alg.kwargs, :fixgauge, default_fixgauge())::Bool
+    do_gauge_fix && gaugefix!(svd_compact!, U, Vᴴ)
+
+    return U, S, Vᴴ
 end
 
-function MatrixAlgebraKit.svd_full!(A::AbstractMatrix, USVᴴ, ::GLA_QRIteration)
+function MatrixAlgebraKit.svd_full!(A::AbstractMatrix, USVᴴ, alg::GLA_QRIteration)
     F = svd!(A; full = true)
     U, Vᴴ = F.U, F.Vt
     S = MatrixAlgebraKit.zero!(similar(F.S, (size(U, 2), size(Vᴴ, 1))))
     diagview(S) .= F.S
-    return MatrixAlgebraKit.gaugefix!(svd_full!, U, S, Vᴴ, size(A)...)
+
+    do_gauge_fix = get(alg.kwargs, :fixgauge, default_fixgauge())::Bool
+    do_gauge_fix && gaugefix!(svd_full!, U, Vᴴ)
+
+    return U, S, Vᴴ
 end
 
 function MatrixAlgebraKit.svd_vals!(A::AbstractMatrix, S, ::GLA_QRIteration)