Speeding up running Macaulay2Doc examples

[mahrud]

Once #1469 is fixed and #1454 is merged, we can run examples from Macaulay2Doc in the same process. This would cut at least 35 minutes from the install time (there are 1185 documentation keys, each starting a new M2 process which takes at least 1.8s on my relatively fast machine).

However, even after that some of the tests seem to take a lot longer, and it would be good to reduce them. For instance, here is the line that contributes to the fifth longest example from the node "communicating with programs", which takes about 8s: https://github.com/Macaulay2/M2/blob/65332ed07101a51255182fb5a16e4e6e20809292/M2/Macaulay2/packages/Macaulay2Doc/overview2.m2#L826

Here is the top percentile of examples by running time:

16.5518 seconds elapsed -- isPseudoprime(ZZ)
10.88 seconds elapsed -- minimalBetti(Ideal)
9.45877 seconds elapsed -- FastNonminimal
8.25365 seconds elapsed -- benchmark
8.0775 seconds elapsed -- communicating with programs
6.79511 seconds elapsed -- computing resolutions
6.21707 seconds elapsed -- betti(..., Minimize => ...)
4.50856 seconds elapsed -- quotient(..., Strategy => ...)
4.07333 seconds elapsed -- variety(Ring)
3.90818 seconds elapsed -- cancelTask(Task)
3.83857 seconds elapsed -- parallel programming with threads and tasks
3.65652 seconds elapsed -- Tutorial: Divisors
3.51705 seconds elapsed -- HH^ZZ CoherentSheaf
3.17934 seconds elapsed -- randomKRationalPoint
3.1685 seconds elapsed -- computing Groebner bases
3.09443 seconds elapsed -- elimination of variables
3.03655 seconds elapsed -- Tutorial: Fano varieties

PS: parallelization with capture is probably going to take a lot more work, since the task supervisor needs fixes before it can handle IO access in parallel. That's not the topic of this issue, however. See #1689 and #992 instead.

[DanGrayson]

Yes, examples for documentation should not take a lot of time to run.

[mahrud]

By the way, on one of my recent PRs you can easily find the location of each of these documentation nodes:

i1 : locate makeDocumentTag "computing resolutions"
o1 = (../../../../Macaulay2/packages/./Macaulay2Doc/./overview4.m2, 361, , , , , )

[mahrud]

Here is a snapshot of the speed comparison:

[0/3] Installing package FirstPackage
 -- making example results for firstFunction(ZZ)
     -- 3.18109 seconds elapsed
 -- making example results for FirstPackage
     -- 2.92795 seconds elapsed
[1/3] Installing package Style
[2/3] Installing package Macaulay2Doc
 -- making example results for random(RR)
     -- 2.96832 seconds elapsed
 -- making example results for betti(Matrix)
     -- 2.8983 seconds elapsed
 -- making example results for singularLocus
     -- 2.60319 seconds elapsed
 -- making example results for pdim(Module)
     -- 2.7054 seconds elapsed
 -- making example results for symmetricPower
     -- 2.79408 seconds elapsed
 -- making example results for reshape(Module,Module,Matrix)
     -- 2.52828 seconds elapsed
 -- making example results for betti(GradedModule)
     -- 2.71032 seconds elapsed
 -- making example results for monomialIdeal(Ideal)
     -- 2.85004 seconds elapsed
 -- making example results for flattenRing(..., CoefficientRing => ...)
     -- 3.01679 seconds elapsed
 -- making example results for module(CoherentSheaf)
     -- 3.08141 seconds elapsed
 -- making example results for listUserSymbols
     -- 2.82672 seconds elapsed
 -- making example results for quotient(..., MinimalGenerators => ...)
     -- 2.72262 seconds elapsed
 -- making example results for communicating with programs
     -- 8.79006 seconds elapsed
...

Versus:

[0/3] Installing package FirstPackage
 -- capturing example results for firstFunction(ZZ)
     -- 1.69663 seconds elapsed
 -- capturing example results for FirstPackage
     -- 0.0291035 seconds elapsed
--warning: file doc.css not installed yet in package Style
--warning: file katex not installed yet in package Style
--warning: file doc.css not installed yet in package Style
--warning: file katex not installed yet in package Style
--warning: file doc.css not installed yet in package Style
--warning: file katex not installed yet in package Style
--warning: file doc.css not installed yet in package Style
--warning: file katex not installed yet in package Style
[1/3] Installing package Style
[2/3] Installing package Macaulay2Doc
 -- capturing example results for random(RR)
     -- 2.37314 seconds elapsed
 -- capturing example results for betti(Matrix)
     -- 0.0618474 seconds elapsed
 -- capturing example results for singularLocus
     -- 0.0491057 seconds elapsed
 -- capturing example results for pdim(Module)
     -- 0.0720532 seconds elapsed
 -- capturing example results for symmetricPower
     -- 0.157453 seconds elapsed
 -- capturing example results for reshape(Module,Module,Matrix)
     -- 0.0323668 seconds elapsed
 -- capturing example results for betti(GradedModule)
     -- 0.0817457 seconds elapsed
 -- capturing example results for monomialIdeal(Ideal)
     -- 0.0485014 seconds elapsed
 -- capturing example results for flattenRing(..., CoefficientRing => ...)
     -- 0.0796984 seconds elapsed
 -- capturing example results for module(CoherentSheaf)
     -- 0.0321765 seconds elapsed
 -- capturing example results for listUserSymbols
     -- 0.0295442 seconds elapsed
 -- capturing example results for quotient(..., MinimalGenerators => ...)
     -- 0.0727786 seconds elapsed
 -- capturing example results for communicating with programs
Linux noether 5.7.15-200.fc32.x86_64 #1 SMP Tue Aug 11 16:36:14 UTC 2020 x86_64 x86_64 x86_64 GNU/Linux
 ba 
 ad 
     -- 6.06104 seconds elapsed

The time spent is a tiny fraction!! There are a few issues remaining, including dealing with examples that change debuggingMode or stopIfError and also stderr isn't captured.

[mahrud]

@d-torrance can you capture examples and tests in parallel?

[d-torrance]

So installPackage and check would each fire up a bunch of different tasks? I don't see why not. Definitely something to try out!