Skip to content
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.

Sign up for GitHub

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

Jump to bottom

[documentation] Improve the docstring of SimpleStats #917

Merged
merged 3 commits into from
Oct 30, 2024
Merged

[documentation] Improve the docstring of SimpleStats #917

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
be06c1d
[documentation] Improve the docstring of SimpleStats
amontoison Oct 29, 2024
a7614ae
Update src/krylov_stats.jl
amontoison Oct 29, 2024
3c16848
Update src/krylov_stats.jl
amontoison Oct 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 24 additions & 16 deletions src/krylov_stats.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `solved`: Indicates whether the solver successfully reached convergence (`true` if solved, ``false` otherwise);
- `solved`: Indicates whether the solver successfully reached convergence (`true` if solved, `false` otherwise);

Copy link

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?

Copy link
Member Author

@amontoison amontoison Oct 29, 2024 •
edited
Loading

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

- `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;
- `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`.
Copy link

Choose a reason for hiding this comment

The 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
Expand Down Expand Up @@ -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:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The fields are as follows:
The fields are as follows (see [`Krylov.SimpleStats`](@ref)):

Copy link

Choose a reason for hiding this comment

The 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

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is xNorm here?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The norm of the solution x.
You can compute it cheaply for many methods because the Krylov basis is orthonormal.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

okay, we should probably explain it here then

- niter
- solved
- inconsistent
Expand Down Expand Up @@ -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:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The fields are as follows:
The fields are as follows (see [`Krylov.SimpleStats`](@ref)):

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is indefinite here?

Copy link
Member Author

@amontoison amontoison Oct 29, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It means that the matrix is indefinite.
A matrix is indefinite if it has positive and negative eigenvalues.

Copy link

Choose a reason for hiding this comment

The 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
Expand Down Expand Up @@ -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:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The fields are as follows:
The fields are as follows (see [`Krylov.SimpleStats`](@ref)):

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is indefinite here?

- niter
- solved
- residuals
Expand Down Expand Up @@ -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:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The fields are as follows:
The fields are as follows (see [`Krylov.SimpleStats`](@ref)):

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What are residualscg, errors and errorscg here?

- niter
- solved
- residuals
Expand Down Expand Up @@ -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:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The fields are as follows:
The fields are as follows (see [`Krylov.SimpleStats`](@ref)):

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do the primal and dual suffixes mean here?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You solve two systems here Ax = b and A'y = c. The primal refers to the first system while the dual refers to the second one.

Copy link

Choose a reason for hiding this comment

The 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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's just that you checked the docstring in the wrong way.
I don't think any user wants to understand how to use a result before knowing how to obtain it. 😉

Nobody will ever use AdjointStats without previously calling bilqr and trilqr, which explain everything and that gives a pointer to this structure: https://jso.dev/Krylov.jl/dev/solvers/as/

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fair enough

- niter
- solved_primal
- solved_dual
Expand Down Expand Up @@ -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:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The fields are as follows:
The fields are as follows (see [`Krylov.SimpleStats`](@ref)):

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do the error_ fields mean here?

- niter
- solved
- residuals
Expand Down Expand Up @@ -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:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The fields are as follows:
The fields are as follows (see [`Krylov.SimpleStats`](@ref)):

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What are the new fields here?

- niter
- solved
- inconsistent
Expand Down
Loading