MueLu: check that Tutorial is built and tested somewhere nightly

[jhux2]

@trilinos/muelu

[lucbv]

@jhux2 looking at it, the tests associated with the tutorial are building fine, the pdf itself is not built as a test and after trying to build it manually I can confirm that it does not build anymore. The usual issue is at fault: the tutorial is built by a python script that relies on MueLu's output which break every time the output changes...

[jhux2]

@lucbv Thank you for looking into this. If there are any other details you think are relevant to resolving this, could you please post them?

[mayrmt]

I tried to build it a couple of weeks ago and it ran almost all the way to the end. I think it got stuck at line 181 runXMLfile("s3b3", "MueLu_tutorial_recirc2d.exe") or 183 runXMLfile("s5a", "MueLu_tutorial_laplace2d.exe")ofprepareTexTutorial.py` if I remember correctly.

When I execute it now, it already breaks in the first example. Here's the full log from my attempt this morning:

./prepareTexTutorial.py 
Prepare files... 
Split source files in src folder for inclusion in pdf... 
Run test examples to include results in pdf... 
s1_easy.txt OK
Traceback (most recent call last):
  File "./prepareTexTutorial.py", line 166, in <module>
    runXMLfile("s1_easy_10levels", "MueLu_tutorial_laplace2d.exe")
  File "./prepareTexTutorial.py", line 102, in runXMLfile
    splitfileintofragments(xmlfile+'.txt_3.fragment','--------------------------------------------------------------------------------')
  File "./prepareTexTutorial.py", line 80, in splitfileintofragments
    file = open( inputfile )
IOError: [Errno 2] No such file or directory: 's1_easy_10levels.txt_3.fragment'

[mayrmt]

@lucbv @jhux2 During preparations for the MueLu presentation at the European Trilinos User Group meeting, the MueLu tutorial came to my mind again. The error is still the same as outlined above.

Are there any plans to revive the Tutorial? Personally, I always found it a very useful reference, especially for advanced features that are not covered by the User Guide.

I'm happy to assist in fixing the PDF generation. If the PDF builds again, we should include that into testing somehow, though I don't know how.

[mayrmt]

I looked into prepareTexTutorial.py where the *.txt_3.fragment is created by parsing the MueLu output. As indicated by @lucbv's previous comment, the identifying string to create this fragment is not part of the MueLu output anymore. I commented the respective line from this script's function runXMLfile() as follows:

def runXMLfile(xmlfile, executable):
  # run simple easy input xml deck test (10 multigrid levels)
  cmd = "mpirun -np 2 ../src/"+executable+" --xml=../src/xml/"+xmlfile+ ".xml > "+xmlfile+".txt"
  runCommand(cmd)
  if os.path.isfile(xmlfile+".txt") and os.access(xmlfile+".txt", os.R_OK):
    splitfileintofragments(xmlfile+'.txt','========================================================')
    # splitfileintofragments(xmlfile+'.txt_3.fragment','--------------------------------------------------------------------------------')
    print xmlfile + bcolors.OKGREEN+" OK"+bcolors.ENDC
    #runCommand("rm s1_easy.txt")
  else:
    print xmlfile + bcolors.FAIL+" Failure"+bcolors.ENDC
    bAllDataPrepared = False  # some data are missing
    runCommand("rm " + xmlfile + ".txt")

Now, the script works until it tries to run pdflatex main.tex where it gets stuck. As recommended by the screen output, I cancelled and ran pdflatex main.tex manually on the command line. This works, except for the missing *.txt_3.fragment files. The first of several errors then is

! Package Listings Error: File `s1_easy_10levels(.txt_3.fragment_3.fragment)' n
ot found.

Type X to quit or <RETURN> to proceed,
or enter new name. (Default extension: txt_3.fragment_3.fragment)

I just hit return to skip this. Eventually, I got this main.pdf.

I haven't figured out yet, what txt_3.fragment is supposed to represent, so I don't know, which parts are missing. Some parts should be missing as some of the files have been skipped.

[github-actions[bot]]

This issue has had no activity for 365 days and is marked for closure. It will be closed after an additional 30 days of inactivity. If you would like to keep this issue open please add a comment and/or remove the MARKED_FOR_CLOSURE label. If this issue should be kept open even with no activity beyond the time limits you can add the label DO_NOT_AUTOCLOSE. If it is ok for this issue to be closed, feel free to go ahead and close it. Please do not add any comments or change any labels or otherwise touch this issue unless your intention is to reset the inactivity counter for an additional year.

[mayrmt]

One of my students @Max-pert is currently looking into this. He'll have some results after the summer break.

[mayrmt]

@trilinos/muelu I had one of my students @Max-pert migrate the content of the PDF to a sphinx-based website using "read the docs". This work is currently part of this branch in my fork of trilinos: https://github.com/mayrmt/Trilinos/tree/muelu-read-the-docs

I have setup a read-the-docs site for this branch to preview the result. It's here: https://muelu-tutorial.readthedocs.io/en/latest/index.html

Now, all examples from the tutorial are covered by tests in packages/muelu/text/tutorial/*, such that the tutorial itself is also part of nightly testing. Of course, the documenting text can still get out of sync, but at least the source code examples compile and run.

For now, this is just a migration of all content of @tawiesn's Latex/PDF tutorial to the read-the-docs website. For the future, this requires some more cleanup. In particular,

• switch tests/examples from Epetra to Tpetra
• add more content to cover recent developments
• decide about the fate of the docker image (see also #10608)

I'll open a PR soon. Please let me know, what you think.

[github-actions[bot]]

This issue has had no activity for 365 days and is marked for closure. It will be closed after an additional 30 days of inactivity. If you would like to keep this issue open please add a comment and/or remove the MARKED_FOR_CLOSURE label. If this issue should be kept open even with no activity beyond the time limits you can add the label DO_NOT_AUTOCLOSE. If it is ok for this issue to be closed, feel free to go ahead and close it. Please do not add any comments or change any labels or otherwise touch this issue unless your intention is to reset the inactivity counter for an additional year.

[mayrmt]

@GrahamBenHarper and I are working on this.

[github-actions[bot]]

This issue has had no activity for 365 days and is marked for closure. It will be closed after an additional 30 days of inactivity. If you would like to keep this issue open please add a comment and/or remove the MARKED_FOR_CLOSURE label. If this issue should be kept open even with no activity beyond the time limits you can add the label DO_NOT_AUTOCLOSE. If it is ok for this issue to be closed, feel free to go ahead and close it. Please do not add any comments or change any labels or otherwise touch this issue unless your intention is to reset the inactivity counter for an additional year.

[mayrmt]

Still WIP.