Add FastScape documentation to manual and tester

[anne-glerum]

Since FastScape is now included in the tester images, I think it is also time to include the coupling to FastScape in the documentation. This PR updates the .md file with the documentation and includes FS in the tester that checks the documentation.

I need to check if the test workflow is correct, so WIP.

For all pull requests:

• I have followed the instructions for indenting my code.
• I followed the AI Policy:
  • Significant parts of this PR were written by AI (please add a sentence below).
  • AI has not been used in significant ways.

If yes, please describe your usage of AI models in the creation of this pull request

For new features/models or changes of existing features:

• I have tested my new feature locally to ensure it is correct.
• I have created a testcase for the new feature/benchmark in the tests/ directory.
• I have added a changelog entry in the doc/modules/changes directory that will inform other users of my change.

[bangerth]

This is ok with me, but it means that for those of us who don't have Fastscape installed locally, we definitely can't create the parameter .md files locally any more.

[bangerth]

-- Setting up ASPECT for Debug mode.
-- 
-- ===== Configuring external libraries ===============
-- Found deal.II version 9.6.0 at '/usr/share/cmake/deal.II'
-- Using ASPECT_USE_TPETRA = 'OFF'
-- Found ZLIB: /usr/lib/x86_64-linux-gnu/libz.so (found version "1.3")  
-- Using ASPECT_WITH_ZLIB = 'ON'
-- Using ASPECT_WITH_PYTHON = 'OFF'
-- Using ASPECT_WITH_LIBDAP = 'OFF'
-- Using ASPECT_WITH_FASTSCAPE = 'ON'
CMake Error at CMakeLists.txt:350 (message):
  Trying to link with FastScape but neither libfastscapelib_fortran.so nor
  libfastscapelib_fortran.a was found in ../fastscapelib-fortran/build or its
  subdirectories.

[anne-glerum]

it means that for those of us who don't have Fastscape installed locally, we definitely can't create the parameter .md files locally any more

I think you could still run make parameters, it would change the Mesh deformation .md file, but one could simply not commit that change. This is what people with FastScape installed have to do right now, not commit FS additions to that file.

However, I do think that is prone to mistakes (e.g. if one just commits all changes instead of adding individual files), and complicated when actual changes to mesh deformation plugins are made.

Not having FastScape in the manual is also not ideal. Perhaps we could somehow insert the FastScape part to the manual in the tester if it has gone missing, or not test for it, but that also seems questionable.

[bangerth]

Yes, good point about it being the other way around. I approved the PR, so I'm ok with this direction, just wanted to bring up the issue so nobody can be surprised :-)

[anne-glerum]

/rebuild

[anne-glerum]

Alright, this now works.

I put in the absolute path (/home/runner/fastscapelib-fortran/build) to FastScape as a CMake flag, it could also be $GITHUB_WORKSPACE/../../fastscapelib-fortran/build if that is preferred.

[anne-glerum]

/rebuild

[gassmoeller]

Ah, this discrepancy will cause us a lot of headache in the future I think. Most users wont have fastscape installed and will not be able to use make parameters without an extra round of applying reference tester documentation. And of course the current state where fastscape users cant run make parameters is not useful either (plus we want the documentation to appear on the website).

What do you think about modifying the mesh_deformation/fastscape class to always exist and declare its input parameters, no matter if Fastscape was detected. Then the class could just throw an assert at run-time if ASPECT was compiled without Fastscape. Then everyone would generate the same parameter documentation indpendent of the Fastscape installation. This seems like a cleaner solution to me, we would only need to make sure that the actual calls to Fastscape functions (and the extern C block) would still be guarded behind a precompiler define to avoid compiler problems.

[bangerth]

The extern "C" block is always fine -- it's just declaring certain functions. It's just that you can't call these functions if Fastscape hasn't been detected: You'd get linker errors. So you'd have to #ifdef ... out the bodies of all of the member functions that call Fastscape functions.

[tjhei]

What do you think about modifying the mesh_deformation/fastscape class to always exist and declare its input parameters, no matter if Fastscape was detected.

Yes, this makes the most sense. @danieldouglas92 we should do the same for Landlab.