Improvement of solver documentation

[Lucas Campos]

Dear all,

While I was learning how to use the deal.ii library, one of the my major

theoretical problems was the plethora of choices in solvers+preconditioners

available, as I mentioned in another post. For instance, most of the Tutorial steps

mention that you can use CG when the tangent matrix is symmetric, but not often

does it mention what to do if your matrix is asymmetric. I think having a short

summary or a table with the solvers in the documentation could help solve

(hehe) this issue. Naturally, something similar could be done regarding

preconditioners.

I am willing to write such documentation. 

As I plan it right now, a lot of of the work would to summarise and write

down the contents of Prof. Bangerth's Lectures 34-38 and 41.75. As for 

the algebraic properties required for the solvers to work, I think using the 

Templates book and PETSc documentation should suffice, but I am always 

open to more sources.

That said all, I can see a few reasons why one would *not* want to have this

summary in the documentation, the most important being that it is possible that

a beginner could get a "good enough" idea and not look deeper into the

documentation to something that would be more beneficial to them. Therefore,

before starting this side project, I would like to know if the maintainers

think it is a good idea to have such summary in the documentation, and would be

pleased to hear more thoughts on the issue. 

Bests,

Lucas

[Wolfgang Bangerth]

Hi Lucas,

> While I was learning how to use the deal.ii library, one of the my major
> theoretical problems was the plethora of choices in solvers+preconditioners
> available, as I mentioned in another post. For instance, most of the Tutorial
> steps
> mention that you can use CG when the tangent matrix is symmetric, but not often
> does it mention what to do if your matrix is asymmetric. I think having a short
> summary or a table with the solvers in the documentation could help solve
> (hehe) this issue. Naturally, something similar could be done regarding
> preconditioners.
>
> I am willing to write such documentation.

I think that would be fantastic!

> As I plan it right now, a lot of of the work would to summarise and write
> down the contents of Prof. Bangerth's Lectures 34-38 and 41.75. As for
> the algebraic properties required for the solvers to work, I think using the
> Templates book and PETSc documentation should suffice, but I am always
> open to more sources.

These are good resources that would be nice to summarize and link to in the
documentation.

> That said all, I can see a few reasons why one would *not* want to have this
> summary in the documentation, the most important being that it is possible that
> a beginner could get a "good enough" idea and not look deeper into the
> documentation to something that would be more beneficial to them. Therefore,
> before starting this side project, I would like to know if the maintainers
> think it is a good idea to have such summary in the documentation, and would be
> pleased to hear more thoughts on the issue.

I think that the main reason we don't have such an overview in the
documentation is that nobody wrote it so far. So if you're willing to do this,
then that would be great and I'm sure something that the community would very
much appreciate!

Would it help you if I sent you the original OpenOffice/LibreOffice slides I
used for the lectures you mention? The PDFs are of course all online already.

Best
Wolfgang


--
------------------------------------------------------------------------
Wolfgang Bangerth email: bang...@colostate.edu
www: http://www.math.colostate.edu/~bangerth/

[Lucas Campos]

Dear Wolfgang,

I will start writing it soon. I will post a draft in the next few days. Unfortunately, I cannot do it much earlier as I will be in a Spring School the next days. 

The first version will include only the required properties for the serial Solvers. As it is my first time writing documentation not only for deal.ii but also in Doxygen, I prefer to check somewhat often if I am using the correct style. BTW, Lecture 23 has been quite helpful in this regard.

Regarding the slides, would be nice having them, if you are willing to share! I think the PDFs should suffice, but it is better to be safe than sorry, and extra documentation does not hurt!

Bests,

Lucas

[Wolfgang Bangerth]

Lucas,

> I will start writing it soon. I will post a draft in the next few days.
> Unfortunately, I cannot do it much earlier as I will be in a Spring School the
> next days.

Work on it whenever you have time -- there is certainly no urgency. In any
case, always start with the current version from github since things change
over time.

Have you thought about where this kind of documentation should go?

> Regarding the slides, would be nice having them, if you are willing to share!
> I think the PDFs should suffice, but it is better to be safe than sorry, and
> extra documentation does not hurt!

I'll send you the parts in question in separate mail. (The file with all
slides for these lectures is now at around 20MB and has a total of 1169 pages
;-) )

Cheers
W.

[Lucas Campos]

Wolfgang,

> Work on it whenever you have time -- there is certainly no urgency. In any case, always start with the current version from github since things change over time.

Sure! I already have a fork of deal.ii on my github account. 

> Have you thought about where this kind of documentation should go?

Initally, I thought about putting into two different parts. Namely, I think the Solvers conditions should go into the Linear Solver module, and the Preconditioners part on the Preconditioners and Relaxation operators. I am not sure which file generates these pages, but I am sure it is possible to find with some grepping. 

Do these choices make sense?

> I'll send you the parts in question in separate mail. (The file with all slides for these lectures is now at around 20MB and has a total of 1169 pages ;-) )

Thanks, both for the documentation and for the filtering. 1169 would lead to a *lot* of searching around.

Bests,
Lucas

                           www: http://www.math.colostate.edu/~bangerth/

--
The deal.II project is located at http://www.dealii.org/
For mailing list/forum options, see https://groups.google.com/d/forum/dealii?hl=en
--- You received this message because you are subscribed to a topic in the Google Groups "deal.II User Group" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/dealii/gWJO4gFmdbA/unsubscribe.
To unsubscribe from this group and all its topics, send an email to dealii+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Wolfgang Bangerth]

> Sure! I already have a fork of deal.ii on my github account.

Right. But what I mean is: Keep it updated.

> > Have you thought about where this kind of documentation should go?
>
> Initally, I thought about putting into two different parts. Namely, I think
> the Solvers conditions should go into the Linear Solver module, and the
> Preconditioners part on the Preconditioners and Relaxation operators. I am not
> sure which file generates these pages, but I am sure it is possible to find
> with some grepping.
>
> Do these choices make sense?

Yes, I think these are good places. And of course you can cross-link from both
so that it's easy to follow connections.

The files in question are in doc/doxygen/headers along with all of the other
module-level documentation.

Best

[Lucas Campos]

One addendum to my previous post. 

By Linear Solver module, I mean this page: https://www.dealii.org/developer/doxygen/deal.II/group__Solvers.html

By Preconditioners and Relaxation operators, I mean this other page: https://www.dealii.org/developer/doxygen/deal.II/group__Preconditioners.html

Lucas