-
Notifications
You must be signed in to change notification settings - Fork 53
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[documentation] Improve the docstring of SimpleStats #917
Changes from 2 commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
|
@@ -7,15 +7,16 @@ import Base.copyto! | |||||
abstract type KrylovStats{T} end | ||||||
|
||||||
""" | ||||||
Type for statistics returned by the majority of Krylov solvers, the attributes are: | ||||||
- niter | ||||||
- solved | ||||||
- inconsistent | ||||||
- residuals | ||||||
- Aresiduals | ||||||
- Acond | ||||||
- timer | ||||||
- status | ||||||
Type for storing statistics returned by the majority of Krylov solvers. | ||||||
The fields are as follows: | ||||||
- `niter`: The total number of iterations completed by the solver; | ||||||
- `solved`: Indicates whether the solver successfully reached convergence (`true` if solved, ``false` otherwise); | ||||||
- `inconsistent`: Flags whether the system was detected as inconsistent (i.e., when `b` is not in the range of `A`); | ||||||
- `residuals`: A vector containing the residual norms at each iteration; | ||||||
- `Aresiduals`: A vector of `Aᴴ`-residual norms at each iteration; | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What is There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The adjoint of There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. My bad, I'm more used to There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I will use There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Some of those were probably explained elsewhere in the docs, like
amontoison marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
- `Acond`: An estimate of the condition number of matrix `A`. | ||||||
- `timer`: The elapsed time (in seconds) taken by the solver to complete all iterations; | ||||||
- `status`: A string indicating the outcome of the solve, providing additional details beyond `solved`. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Can you give an example? What are its possible values? |
||||||
""" | ||||||
mutable struct SimpleStats{T} <: KrylovStats{T} | ||||||
niter :: Int | ||||||
|
@@ -47,7 +48,8 @@ function copyto!(dest :: SimpleStats, src :: SimpleStats) | |||||
end | ||||||
|
||||||
""" | ||||||
Type for statistics returned by LSMR. The attributes are: | ||||||
Type for storing statistics returned by LSMR. | ||||||
The fields are as follows: | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Same for the other more sophisticated stats, so that you don't need to document every field again There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What is There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The norm of the solution There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. okay, we should probably explain it here then |
||||||
- niter | ||||||
- solved | ||||||
- inconsistent | ||||||
|
@@ -96,7 +98,8 @@ function copyto!(dest :: LsmrStats, src :: LsmrStats) | |||||
end | ||||||
|
||||||
""" | ||||||
Type for statistics returned by CG-LANCZOS, the attributes are: | ||||||
Type for storing statistics returned by CG-LANCZOS. | ||||||
The fields are as follows: | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What is There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It means that the matrix is indefinite. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. okay, we should probably explain it here or in a high-level preamble |
||||||
- niter | ||||||
- solved | ||||||
- residuals | ||||||
|
@@ -134,7 +137,8 @@ function copyto!(dest :: LanczosStats, src :: LanczosStats) | |||||
end | ||||||
|
||||||
""" | ||||||
Type for statistics returned by CG-LANCZOS with shifts, the attributes are: | ||||||
Type for storing statistics returned by CG-LANCZOS-SHIFT and CGLS-LANCZOS-SHIFT. | ||||||
The fields are as follows: | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What is |
||||||
- niter | ||||||
- solved | ||||||
- residuals | ||||||
|
@@ -174,7 +178,8 @@ function copyto!(dest :: LanczosShiftStats, src :: LanczosShiftStats) | |||||
end | ||||||
|
||||||
""" | ||||||
Type for statistics returned by SYMMLQ, the attributes are: | ||||||
Type for storing statistics returned by SYMMLQ. | ||||||
The fields are as follows: | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What are |
||||||
- niter | ||||||
- solved | ||||||
- residuals | ||||||
|
@@ -221,7 +226,8 @@ function copyto!(dest :: SymmlqStats, src :: SymmlqStats) | |||||
end | ||||||
|
||||||
""" | ||||||
Type for statistics returned by adjoint systems solvers BiLQR and TriLQR, the attributes are: | ||||||
Type for storing statistics returned by adjoint systems solvers BiLQR and TriLQR. | ||||||
The fields are as follows: | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What do the There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. You solve two systems here There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. maybe this docstring could link to an explanation of the algorithm itself for these details There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It's just that you checked the docstring in the wrong way. Nobody will ever use There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. fair enough |
||||||
- niter | ||||||
- solved_primal | ||||||
- solved_dual | ||||||
|
@@ -258,7 +264,8 @@ end | |||||
|
||||||
|
||||||
""" | ||||||
Type for statistics returned by the LNLQ method, the attributes are: | ||||||
Type for storing statistics returned by the LNLQ method. | ||||||
The fields are as follows: | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What do the |
||||||
- niter | ||||||
- solved | ||||||
- residuals | ||||||
|
@@ -298,7 +305,8 @@ function copyto!(dest :: LNLQStats, src :: LNLQStats) | |||||
end | ||||||
|
||||||
""" | ||||||
Type for statistics returned by the LSLQ method, the attributes are: | ||||||
Type for storing statistics returned by the LSLQ method. | ||||||
The fields are as follows: | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What are the new fields here? |
||||||
- niter | ||||||
- solved | ||||||
- inconsistent | ||||||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Also, convergence according to which criterion? A tolerance I assume?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The answer is quite complex. It depends which shopping condition is triggered.
It could be also related to the callback.
I need to document that since a long time too: #552