Add a persistent layer of setting options and introduce a Tutorial mode

.gitignore

@@ -22,3 +22,4 @@ docs/src/tutorials/Optimize!_files
 docs/src/tutorials/*.html
 docs/src/changelog.md
 docs/styles/Google
+tutorials/LocalPreferences.toml

Changelog.md

@@ -5,17 +5,19 @@ All notable Changes to the Julia package `Manopt.jl` will be documented in this
 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.4.52]
 
 ### Added
 
-* Allow the `message=` of the `DebugIfEntry` debug action to contain a format element to print the field in the message as well.
+* introduce an environment persistent way of setting global values with the `set_manopt_parameter!` function using [Preferences.jl](https://github.com/JuliaPackaging/Preferences.jl).
+* introduce such a value named `:Mode` to enable a `"Tutorial"` mode that shall often provide more warnings and information for people getting started with optimisation on manifolds
 
 ## [0.4.51] January 30, 2024
 
 ### Added
 
 * A `StopWhenSubgradientNormLess` stopping criterion for subgradient-based optimization.
+* Allow the `message=` of the `DebugIfEntry` debug action to contain a format element to print the field in the message as well.
 
 ## [0.4.50] January 26, 2024
 

Project.toml

@@ -1,7 +1,7 @@
 name = "Manopt"
 uuid = "0fc0a36d-df90-57f3-8f93-d78a9fc72bb5"
 authors = ["Ronny Bergmann <[email protected]>"]
-version = "0.4.51"
+version = "0.4.52"
 
 [deps]
 ColorSchemes = "35d6a980-a343-548e-a6ea-1d62b119f2f4"
@@ -14,6 +14,7 @@ ManifoldDiff = "af67fdf4-a580-4b9f-bbec-742ef357defd"
 ManifoldsBase = "3362f125-f0bb-47a3-aa74-596ffd7ef2fb"
 Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
 PolynomialRoots = "3a141323-8675-5d76-9d11-e1df1406c778"
+Preferences = "21216c6a-2e73-6563-6e65-726566657250"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Requires = "ae029012-a4dd-5104-9daa-d747884805df"
@@ -42,19 +43,20 @@ Colors = "0.11.2, 0.12"
 DataStructures = "0.17, 0.18"
 Dates = "1.6"
 JuMP = "1.15"
-LinearAlgebra = "1.6"
 LRUCache = "1.4"
+LinearAlgebra = "1.6"
 ManifoldDiff = "0.3.8"
 Manifolds = "0.9.11"
 ManifoldsBase = "0.15"
 ManoptExamples = "0.1.4"
 Markdown = "1.6"
 PolynomialRoots = "1"
+Preferences = "1.4"
 Printf = "1.6"
 Random = "1.6"
 Requires = "0.5, 1"
-Statistics = "1.6"
 SparseArrays = "1.6"
+Statistics = "1.6"
 Test = "1.6"
 julia = "1.6"
 

Readme.md

@@ -78,16 +78,17 @@ for the most recent version or a corresponding version specific DOI, see [the li
 
 If you are also using [`Manifolds.jl`](https://juliamanifolds.github.io/Manifolds.jl/stable/) please consider to cite
 
-```
+```biblatex
 @article{AxenBaranBergmannRzecki:2023,
-    AUTHOR     = {Seth D. Axen and Mateusz Baran and Ronny Bergmann and Krzysztof Rzecki},
-    DOI        = {10.1145/3618296},
-    EPRINT     = {2021.08777},
-    EPRINTTYPE = {arXiv},
-    JOURNAL    = {AMS Transactions on Mathematical Software},
-    NOTE       = {accepted for publication},
-    TITLE      = {Manifolds.jl: An Extensible {J}ulia Framework for Data Analysis on Manifolds},
-    YEAR       = {2023}
+    AUTHOR    = {Axen, Seth D. and Baran, Mateusz and Bergmann, Ronny and Rzecki, Krzysztof},
+    ARTICLENO = {33},
+    DOI       = {10.1145/3618296},
+    JOURNAL   = {ACM Transactions on Mathematical Software},
+    MONTH     = {dec},
+    NUMBER    = {4},
+    TITLE     = {Manifolds.Jl: An Extensible Julia Framework for Data Analysis on Manifolds},
+    VOLUME    = {49},
+    YEAR      = {2023}
 }
 ```
 

docs/src/index.md

@@ -48,16 +48,34 @@ To refer to a certain version or the source code in general cite for example
 
 ```biblatex
 @software{manoptjl-zenodo-mostrecent,
-    Author = {Ronny Bergmann},
+    Author    = {Ronny Bergmann},
     Copyright = {MIT License},
-    Doi = {10.5281/zenodo.4290905},
+    Doi       = {10.5281/zenodo.4290905},
     Publisher = {Zenodo},
-    Title = {Manopt.jl},
-    Year = {2022},
+    Title     = {Manopt.jl},
+    Year      = {2024},
 }
 ```
 
 for the most recent version or a corresponding version specific DOI, see [the list of all versions](https://zenodo.org/search?page=1&size=20&q=conceptrecid:%224290905%22&sort=-version&all_versions=True).
+
+
+If you are also using [`Manifolds.jl`](https://juliamanifolds.github.io/Manifolds.jl/stable/) please consider to cite
+
+```biblatex
+@article{AxenBaranBergmannRzecki:2023,
+    AUTHOR    = {Axen, Seth D. and Baran, Mateusz and Bergmann, Ronny and Rzecki, Krzysztof},
+    ARTICLENO = {33},
+    DOI       = {10.1145/3618296},
+    JOURNAL   = {ACM Transactions on Mathematical Software},
+    MONTH     = {dec},
+    NUMBER    = {4},
+    TITLE     = {Manifolds.Jl: An Extensible Julia Framework for Data Analysis on Manifolds},
+    VOLUME    = {49},
+    YEAR      = {2023}
+}
+```
+
 Note that both citations are in [BibLaTeX](https://ctan.org/pkg/biblatex) format.
 
 ## Main features

docs/src/plans/index.md

@@ -47,4 +47,10 @@ The column “generic” refers to a short hand that might be used for readabil
 Since the iterate is often stored in the states fields `s.p` one _could_ access the iterate
 often also with `:p` and similarly the gradient with `:X`.
 This is discouraged for both readability as well as to star more generic, and it is recommended
-to use `:Iterate` and `:Gradient` instead in generic settings.
+to use `:Iterate` and `:Gradient` instead in generic settings.
+
+You can further activate a “Tutorial” mode by `set_manopt_parameter!(:Mode, "Tutorial")`. Internally, the following convenience function is available.
+
+```@docs
+Manopt.is_tutorial_mode
+```

docs/src/references.bib

@@ -8,10 +8,10 @@
 @book{AbsilMahonySepulchre:2008,
     AUTHOR    = {Absil, P.-A. and Mahony, R. and Sepulchre, R.},
     DOI       = {10.1515/9781400830244},
+    NOTE      = {available online at \href{http://press.princeton.edu/chapters/absil/}{press.princeton.edu/chapters/absil/}},
     PUBLISHER = {Princeton University Press},
-    NOTE      = {[open access](http://press.princeton.edu/chapters/absil/)},
     TITLE     = {Optimization Algorithms on Matrix Manifolds},
-    YEAR      = {2008},
+    YEAR      = {2008}
 }
 @article{AbsilBakerGallivan:2006,
     DOI       = {10.1007/s10208-005-0179-9},
@@ -61,27 +61,29 @@ @article{AlmeidaNetoOliveiraSouza:2020
 %
 %
 @article{Bacak:2014,
-    AUTHOR  = {Bačák, M.},
-    DOI     = {10.1137/140953393},
-    JOURNAL = {SIAM Journal on Optimization},
-    NOTE    = {arXiv: [1210.2145](https://arxiv.org/abs/1210.2145)},
-    NUMBER  = {3},
-    PAGES   = {1542--1566},
-    TITLE   = {Computing medians and means in Hadamard spaces},
-    VOLUME  = {24},
-    YEAR    = {2014}
+    AUTHOR     = {Bačák, M.},
+    DOI        = {10.1137/140953393},
+    JOURNAL    = {SIAM Journal on Optimization},
+    EPRINT     = {1210.2145},
+    EPRINTTYPE = {arXiv},
+    NUMBER     = {3},
+    PAGES      = {1542--1566},
+    TITLE      = {Computing medians and means in Hadamard spaces},
+    VOLUME     = {24},
+    YEAR       = {2014}
 }
 
 @article{BacakBergmannSteidlWeinmann:2016,
     AUTHOR       = {Bačák, Miroslav and Bergmann, Ronny and Steidl, Gabriele and Weinmann, Andreas},
     YEAR         = {2016},
     DOI          = {10.1137/15M101988X},
+    EPRINT       = {1506.02409},
+    EPRINTTYPE   = {arXiv},
     JOURNAL      = {SIAM Journal on Scientific Computing},
     NUMBER       = {1},
     PAGES        = {A567--A597},
     TITLE        = {A second order non-smooth variational model for restoring manifold-valued images},
     VOLUME       = {38},
-    NOTE         = {arxiv: [1506.02409](https://arxiv.org/abs/1506.02409)}
 }
 
 @inproceedings{Beale:1972,
@@ -128,18 +130,20 @@ @article{BergmannFerreiraSantosSouza:2023
 @article{BergmannGousenbourger:2018,
     AUTHOR       = {Bergmann, Ronny and Gousenbourger, Pierre-Yves},
     YEAR         = {2018},
+    EPRINT       = {1807.10090},
+    EPRINTTYPE   = {arXiv},
     DOI          = {10.3389/fams.2018.00059},
     JOURNAL      = {Frontiers in Applied Mathematics and Statistics},
     TITLE        = {A variational model for data fitting on manifolds by minimizing the acceleration of a Bézier curve},
     VOLUME       = {4},
-    NOTE         = {arXiv: [1807.10090](https://arxiv.org/abs/1807.10090)}
 }
 
 @article{BergmannHerzog:2019,
     AUTHOR       = {Bergmann, Ronny and Herzog, Roland},
     DOI          = {10.1137/18M1181602},
     JOURNAL      = {SIAM Journal on Optimization},
-    NOTE         = {arXiv: [1804.06214](https://arxiv.org/abs/1804.06214)},
+    EPRINTTYPE   = {arXiv},
+    EPRINT       = {1804.06214},
     NUMBER       = {4},
     PAGES        = {2423–2444},
     TITLE        = {Intrinsic formulation of KKT conditions and constraint qualifications on smooth manifolds},
@@ -149,6 +153,8 @@ @article{BergmannHerzog:2019
 
 @article{BergmannHerzogSilvaLouzeiroTenbrinckVidalNunez:2021,
     AUTHOR       = {Bergmann, Ronny and Herzog, Roland and Silva Louzeiro, Maurício and Tenbrinck, Daniel and Vidal-Núñez, José},
+    EPRINT       = {1908.02022},
+    EPRINTTYPE = {arXiv},
     PUBLISHER    = {Springer Science and Business Media LLC},
     YEAR         = {2021},
     MONTH        = jan,
@@ -158,7 +164,6 @@ @article{BergmannHerzogSilvaLouzeiroTenbrinckVidalNunez:2021
     PAGES        = {1465--1504},
     TITLE        = {Fenchel duality theory and a primal-dual algorithm on Riemannian manifolds},
     VOLUME       = {21},
-    NOTE         = {arXiv: [1908.02022](http://arxiv.org/abs/1908.02022)}
 }
 
 @article{BergmannLausSteidlWeinmann:2014:1,
@@ -206,7 +211,7 @@ @book{Boumal:2023
     EDITION   = {First},
     PUBLISHER = {Cambridge University Press},
     DOI       = {10.1017/9781009166164},
-    NOTE      = {Homepage to the book: [nicolasboumal.net/book/index.html](https://www.nicolasboumal.net/book/index.html).},
+    URL       = {https://www.nicolasboumal.net/book/index.html},
     ABSTRACT  = {Optimization on Riemannian manifolds-the result of smooth geometry and optimization merging into one elegant modern framework-spans many areas of science and engineering, including machine learning, computer vision, signal processing, dynamical systems and scientific computing. This text introduces the differential geometry and Riemannian geometry concepts that will help students and researchers in applied mathematics, computer science and engineering gain a firm mathematical grounding to use these tools confidently in their research. Its charts-last approach will prove more intuitive from an optimizer's viewpoint, and all definitions and theorems are motivated to build time-tested optimization algorithms. Starting from first principles, the text goes on to cover current research on topics including worst-case complexity and geodesic convexity. Readers will appreciate the tricks of the trade for conducting research and for numerical implementations sprinkled throughout the book.},
     ISBN      = {978-1-00-916616-4}
 }
@@ -275,17 +280,18 @@ @article{DaiYuan:1999
     YEAR      = {1999}
 }
 @article{DiepeveenLellmann:2021,
-    AUTHOR    = {Willem Diepeveen and Jan Lellmann},
-    DOI       = {10.1137/21m1398513},
-    JOURNAL   = {SIAM Journal on Imaging Sciences},
-    MONTH     = jan,
-    NOTE      = {arXiv: [2102.10309](https://arxiv.org/abs/2102.10309)},
-    NUMBER    = {4},
-    PAGES     = {1565--1600},
-    PUBLISHER = {Society for Industrial \& Applied Mathematics ({SIAM})},
-    TITLE     = {An Inexact Semismooth Newton Method on Riemannian Manifolds with Application to Duality-Based Total Variation Denoising},
-    VOLUME    = {14},
-    YEAR      = {2021},
+    AUTHOR     = {Willem Diepeveen and Jan Lellmann},
+    DOI        = {10.1137/21m1398513},
+    JOURNAL    = {SIAM Journal on Imaging Sciences},
+    MONTH      = jan,
+    EPRINTTYPE = {arXiv},
+    EPRINT     = {2102.10309},
+    NUMBER     = {4},
+    PAGES      = {1565--1600},
+    PUBLISHER  = {Society for Industrial \& Applied Mathematics ({SIAM})},
+    TITLE      = {An Inexact Semismooth Newton Method on Riemannian Manifolds with Application to Duality-Based Total Variation Denoising},
+    VOLUME     = {14},
+    YEAR       = {2021},
 }
 @article{DuranMoelleSbertCremers:2016,
     AUTHOR   = {Duran, J. and Moeller, M. and Sbert, C. and Cremers, D.},
@@ -296,7 +302,8 @@ @article{DuranMoelleSbertCremers:2016
     PAGES    = {116-151},
     YEAR     = {2016},
     DOI      = {10.1137/15M102873X},
-    NOTE = {arxiv: [1508.01308](https://arxiv.org/abs/1508.01308)}
+    EPRINT   = {1508.01308},
+    EPRINTTYPE = {arXiv},
 }
 
 % --- E
@@ -343,7 +350,7 @@ @article{GrapigliaStella:2023
     DOI       = {10.1007/s10957-023-02227-y},
     JOURNAL   = {Journal of Optimization Theory and Applications},
     MONTH     = may,
-    NOTE      = {preprint: [optimization-online.org/wp-content/uploads/2022/04/8864.pdf](https://optimization-online.org/wp-content/uploads/2022/04/8864.pdf)},
+    URL       = {https://optimization-online.org/wp-content/uploads/2022/04/8864.pdf},
     NUMBER    = {3},
     PAGES     = {1140--1160},
     PUBLISHER = {Springer Science and Business Media {LLC}},
@@ -457,7 +464,7 @@ @article{LausNikolovaPerschSteidl:2017
     AUTHOR       = {Laus, F. and Nikolova, M. and Persch, J. and Steidl, G.},
     YEAR         = {2017},
     DOI          = {10.1137/16M1087114},
-    JOURNAL = {SIAM Journal on Imaging Sciences},
+    JOURNAL      = {SIAM Journal on Imaging Sciences},
     NUMBER       = {1},
     PAGES        = {416--448},
     TITLE        = {A nonlocal denoising algorithm for manifold-valued images using second order statistics},
@@ -472,7 +479,8 @@ @article{LiuBoumal:2019
     DOI       = {10.1007/s00245-019-09564-3},
     JOURNAL   = {Applied Mathematics \& Optimization},
     TITLE     = {Simple algorithms for optimization on Riemannian manifolds with constraints},
-    URL       = {https://arxiv.org/abs/1901.10000}
+    EPRINT    = {1091.10000},
+    EPRINTTYPE = {arXiv},
 }
 @article{Luenberger:1972,
     AUTHOR    = {Luenberger, David G},

src/Manopt.jl

@@ -122,6 +122,8 @@ using ManifoldsBase:
     ℂ,
     ℝ
 using Markdown
+using Preferences:
+    @load_preference, @set_preferences!, @has_preference, @delete_preferences!
 using Printf
 using Random: shuffle!, rand, randperm
 using Requires
@@ -470,7 +472,8 @@ export DebugDualResidual, DebugPrimalDualResidual, DebugPrimalResidual
 export DebugProximalParameter, DebugWarnIfCostIncreases
 export DebugGradient, DebugGradientNorm, DebugStepsize
 export DebugWhenActive, DebugWarnIfFieldNotFinite, DebugIfEntry
-export DebugWarnIfCostNotFinite, DebugWarnIfFieldNotFinite, DebugMessages
+export DebugWarnIfCostNotFinite, DebugWarnIfFieldNotFinite
+export DebugWarnIfGradientNormTooLarge, DebugMessages
 #
 # Records - and access functions
 export get_record, get_record_state, get_record_action, has_record