Refactor initial guess (#539)

* First draft of refactoring initial guesses.
* initial guess file with HZ and Armijo
* Inf norm for HZI
* Fix calls to initial guess to include the eta.
* docs
* Provide a more detailed linesearch backtrack documentation
* increase test coverage
* Bump version.

---------

Co-authored-by: Ronny Bergmann <git@ronnybergmann.net>

Author: mateuszbaran

.github/workflows/ci.yml

@@ -19,7 +19,6 @@ jobs:
         with:
           version: ${{ matrix.julia-version }}
           arch: x64
-      - uses: julia-actions/cache@v2
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-runtest@v1
       - uses: julia-actions/julia-processcoverage@v1

.github/workflows/documenter.yml

@@ -16,7 +16,7 @@ jobs:
           version: "1.7.29"
       - uses: julia-actions/setup-julia@latest
         with:
-          version: "1.11"
+          version: "1.12"
       - name: Julia Cache
         uses: julia-actions/cache@v2
       - name: Cache Quarto

.github/workflows/nightly.yml

@@ -16,7 +16,6 @@ jobs:
         with:
           version: ${{ matrix.julia-version }}
           arch: x64
-      - uses: julia-actions/cache@v2
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-runtest@v1
         env:

Changelog.md

@@ -6,14 +6,21 @@ The file was started with Version `0.4`.
 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).
 
-## [Unreleased]
+## [0.5.28] November 17, 2025
+
+### Changed
+
+* Unified the interfaces for line search related functions, especially,
+  * `linesearch_backtrack(M, F, p, X, s, decrease, contract, η, f0; kwargs...)` now has `lf0=` and `gradient=` keyword arguments instead of positional ones for `X` and the last `f0`, respectively. It additionally has a `Dlf0=` keyword argument to pass the evaluated differential instead of the gradient, which otherwise defaults to calling the inner product.
+* Refactor the nonmonotone linesearch stepsize to have an initial guess that can be set. For now it still afterwards performs the Barzilai-Borwein initial guess,
+so a constant initial guess is recommended here. The initial guess may be refactored in the future in a non-breaking release and the meaning of the initial guess in nonmonotone line search may change.
 
 ### Fixed
 
 * Change the construction of the product manifold in `interior_point_newton` from `×` to `ProductManifold`, so that the algorithm also work on Product manifolds `M`, where it now correctly wraps `M` instead of extending it.
-* unifies the doc strings for constrained problems
-* fixes a few typos in the doc strings of matrix update formulae within the quasi-Newton and CG solver.
-* covers one last line in `proximal_gradient_plan`
+* Unified the doc strings for constrained problems.
+* Fixed a few typos in the doc strings of matrix update formulae within the quasi-Newton and CG solver.
+* Covered one last line in `proximal_gradient_plan`
 
 ## [0.5.27] November 11, 2025
 

Project.toml

@@ -1,7 +1,7 @@
 name = "Manopt"
 uuid = "0fc0a36d-df90-57f3-8f93-d78a9fc72bb5"
 authors = ["Ronny Bergmann <manopt@ronnybergmann.net>"]
-version = "0.5.27"
+version = "0.5.28"
 
 [deps]
 ColorSchemes = "35d6a980-a343-548e-a6ea-1d62b119f2f4"

docs/make.jl

@@ -156,8 +156,8 @@ makedocs(;
     format = Documenter.HTML(;
         prettyurls = run_on_CI || ("--prettyurls" ∈ ARGS),
         assets = ["assets/favicon.ico", "assets/citations.css", "assets/link-icons.css"],
-        size_threshold_warn = 250 * 2^10, # raise slightly from 100 to 200 KiB
         size_threshold = 350 * 2^10,      # raise slightly 200 to to 300 KiB
+        size_threshold_warn = 11 * 2^12, # raise from 500 KiB to 1.1 MB (for search index)
     ),
     modules = [
         Manopt,

docs/src/plans/stepsize.md

@@ -1,4 +1,4 @@
-# [Stepsize and line search](@id Stepsize)
+# [Stepsize and line search](@id Sec-Stepsize)
 
 ```@meta
 CurrentModule = Manopt
@@ -32,6 +32,17 @@ WolfePowellLinesearch
 WolfePowellBinaryLinesearch
 ```
 
+Additionally, initial stepsize guesses are handled by subtypes of `AbstractInitialLinesearchGuess`:
+
+```@docs
+AbstractInitialLinesearchGuess
+ConstantInitialGuess
+ArmijoInitialGuess
+HagerZhangInitialGuess
+```
+
+Onw implementations can also (just) be functions.
+
 Some step sizes use [`max_stepsize`](@ref) function as a rough upper estimate for the trust region size.
 It is by default equal to injectivity radius of the exponential map but in some cases a different value is used.
 For the `FixedRankMatrices` manifold an estimate from Manopt is used.
@@ -58,6 +69,13 @@ Then the following state can be used to wrap these locally
 StepsizeState
 ```
 
+The Hager-Zhang initial guess uses two helper functions to determine initial stepsize in the first iteration on manifolds which have "expected minimizer", for example the zero point on the Euclidean manifold:
+
+```@docs
+default_vector_norm
+default_point_distance
+```
+
 ## Literature
 
 ```@bibliography

docs/src/references.bib

@@ -501,7 +501,7 @@ @article{HagerZhang:2005
     VOLUME    = {16},
     YEAR      = {2005}
 }
-@article{HagerZhang:2006,
+@article{HagerZhang:2006:1,
     AUTHOR       = {Hager, W. W. and Zhang, H.},
     JOURNAL      = {Pacific Journal of Optimization},
     NUMBER       = {1},
@@ -511,6 +511,18 @@ @article{HagerZhang:2006
     VOLUME       = {2},
     YEAR         = {2006}
 }
+@article{HagerZhang:2006:2,
+	title = {Algorithm 851: {CG}_{DESCENT}, a conjugate gradient method with guaranteed descent},
+	volume = {32},
+	issn = {0098-3500},
+	doi = {10.1145/1132973.1132979},
+	number = {1},
+	journal = {ACM Transactions on Mathematical Software},
+	author = {Hager, William W. and Zhang, Hongchao},
+	month = mar,
+	year = {2006},
+	pages = {113--137},
+}
 
 @article{Hansen:2023,
 	AUTHOR = {Hansen, Nikolaus},

docs/src/solvers/proximal_gradient_method.md

@@ -28,7 +28,7 @@ ProximalGradientNonsmoothCost
 StopWhenGradientMappingNormLess
 ```
 
-## Stepsize
+## [Stepsize](@id Sec-ProxGrad-Stepsize)
 
 ```@docs
 ProximalGradientMethodBacktracking

docs/src/solvers/vectorbundle_newton.md

@@ -17,7 +17,7 @@ VectorBundleManoptProblem
 VectorBundleNewtonState
 ```
 
-# Stepsize
+# [Stepsize](@id Sec-VectorBundleNewton-Stepsize)
 
 ```@docs
 AffineCovariantStepsize