Improve solver documentation

[guyer]

Suggestions made by @wd15 in #1030:

• A lot of the information on this page could be summed up in a table of solver v feature with ticks and crosses. This might be a lot less verbose and have a lot less of the warning boxes.
• Add a label to the x-axis of part (a) of the first figure.
• The performance comparison section could do with a little explanation about the history of FiPy and what you just did. Give the take away in a few sentences and why we need this analysis.
• The second figure is a little confusing. It's not clear why the PCG solver in in bold. Is this because it's the baseline?
• Maybe add Figure numbers and refer to them in the text.
• There is quite a lot of variation in the prepare time / elapsed time results within each suite. Maybe say why different solvers are better / worse in this regard in the same suite?
• It says " For this problem, Trilinos has the lowest ratio of prepare to elapsed time". All suites have some solvers that do well in this regard.
• I'm not sure you can claim that Trilinos is better overall. Scipy seems to get the lowest for the majority of solvers. Linear PCG does better with Trilinos.
• How are the prepare time / elapsed time > 1 for petsc?
• Having two keys in a plot is hard work for the reader. Maybe make two plots for the parallel performance plot each with a single key
  • I'm thinking that having the curves for the parallel laws is confusing. Maybe split those out into separate plots.

[guyer]

• Add a label to the x-axis of part (a) of the first figure.

Matplotlib does this with shared axes (there's no y-axis label in (b), either). I've tried unsharing and then it seems very cluttered with the same label over and over (see the prepare fraction plot).

• The second figure is a little confusing. It's not clear why the PCG solver in in bold. Is this because it's the baseline?

The intent was to show the range of possible behaviors with the fine lines and to compare one particular (well-performing) example with the thick lines.

• Maybe add Figure numbers and refer to them in the text.

Set numfig and use :numref:

• It says " For this problem, Trilinos has the lowest ratio of prepare to elapsed time". All suites have some solvers that do well in this regard. I'm not sure you can claim that Trilinos is better overall. Scipy seems to get the lowest for the majority of solvers. Linear PCG does better with Trilinos.

I was thinking about unpreconditioned LinearPCGSolver when I wrote this. The fact that SciPy has many lines that are very low is exactly the point I was trying to make. All SciPy solves of a particular mesh size have the same prepare time. If prepare/elapsed is small, it's because the solver is slow, not because the prepare is fast.

• How are the prepare time / elapsed time > 1 for petsc?

Not > 1; asymptotically 1. Prepare time is dreadful for PETSc >= 3.19 and FiPy 3.4.4.

• Having two keys in a plot is hard work for the reader. Maybe make two plots for the parallel performance plot each with a single key
  • I'm thinking that having the curves for the parallel laws is confusing. Maybe split those out into separate plots.

Separate plots for Amdahl and Gunther fits makes sense.

[guyer]

@wd15 responded

Not > 1; asymptotically 1. Prepare time is dreadful for PETSc >= 3.19 and FiPy 3.4.4.

Oh, then I suggest plotting with ymax greater than 1 if you happen to ever redo those plots just to make it clear.

Separate plots for Amdahl and Gunther fits makes sense.

Actually, I was suggesting separate plots with both of the fits in one figure. So one plot without the fits (just an interpolation or joined up points or no lines at all) and then one with the laws fit to the data.

[guyer]

• Maybe add Figure numbers and refer to them in the text.

Set numfig and use :numref:

Unfortunately :numref: doesn't work with .. plot::. There's a workaround, but it's gross.