Add 1D divergence and laplacian operators

[rouson]

What type of PR is this? (check all applicable)

• Refactor
• Feature
• Bug Fix
• Optimization
• Example
• Documentation

Description

Change Log

1. Add 1D divergence and Laplacian operators and related types:
   • Public operators: .div. and .laplacian.
   • Derived types: divergence_1D_t and laplacian_1D_t
2. Add operator-matrix assembly generic bindings (assemble) for the gradient_operator_1D_t and divergence_operator_1D_t derived types along with corresponding private type-bound functions that produce the assembled matrices, including zeros.
3. Add programs in the example subdirectory:
   • print-assembled-1D-operators prints the assembled 1D gradient and divergence matrices
   • div-grad-laplacian-1D prints
     • the result of applying .grad. to a scalar_1D_t object
     • the result of applying.div. to a vector_1D_t object
     • the result of applying .laplacian. to a scalar_1D_t object
     • usage information if -- --help is appended to the above fpm command
4. Add a UML class diagram in doc/fortran-classes.md depicting
   • User-facing derived types: scalar_1D_t, vector_1D_t, divergence_1D_t, laplacian_1D_t
   • Important internal derived types: tensor_1D_t, mimetic_matrix_1D_t, gradient_operator_1D_t, divergence_operator_1D_t
5. Add unit tests in the test subdirectory:
   • divergence_operator_1D_test_m tests the .div. result values and convergence rates
   • laplacian_operator_1D_test_m tests the .laplacian. result values and convergence rates
6. Chores and workarounds:
   • Work around several gfortran compiler bugs or missing features
   • Use slightly larger tolerances with ifx in two tests
   • Restrict ifx runs to a single image because MOLE Fortran uses no multi-image features but ifx defaults to multi-image execution, resulting in redundant output for test failures. (Julienne avoids duplicative reporting for passing tests.)

Related Issues & Documents

N.A.

QA Instructions, Screenshots, Recordings

LLVM

Version 20 or later

fpm test --compiler flang-new --flag "-O3"
fpm run --example div-grad-laplacian-1D --compiler flang-new --flag "-O3" -- --help
fpm run --example div-grad-laplacian-1D --compiler flang-new --flag "-O3"
fpm run --example  print-assembled-1D-operators --compiler flang-new --flag "-O3"

Version 19

Add -mmlir -allow-assumed-rank inside the double quotes into the above commands with a space separating the new flags from -O3.

GCC

Version 14 or later

fpm test --compiler gfortran --profile release
fpm run --example div-grad-laplacian-1D --compiler gfortran --profile release -- --help
fpm run --example div-grad-laplacian-1D --compiler gfortran --profile release
fpm run --example  print-assembled-1D-operators --compiler gfortran --profile release

Version 13

Append --flag -ffree-line-length-0 to the above commands, except in the one with the trailing -- --help, in which case the added flag must precede -- --help.

Intel

fpm test --compiler ifx --profile release --flag -fpp
fpm run --example div-grad-laplacian-1D --compiler fix --profile release --flag -fpp -- --help
fpm run --example div-grad-laplacian-1D --compiler fix --profile release --flag -fpp
fpm run --example  print-assembled-1D-operators --compiler gfortran --profile release

NAG

This release drops support for the nagfor compiler unless and until blocking compiler bugs have been isolated, reported, and fixed.

Added/updated tests?

• Yes
• No, and this is why: please replace this line with details on why tests
  have not been included
• I need help with writing tests

Read Contributing Guide and Code of Conduct

• I have read and followed the Contributing Guide and the Code of Conduct

Are there any post deployment tasks we need to perform?

No.

What gif best describes this PR or how it makes you feel?

[rouson]

@joehellmers this PR is ready for review. I'm tagging you because I don't have the permissions to designate a reviewer. It's gargantuan so I recommend just running fpm commands in the QA Instructions with the compiler of your choice. If you want to do a detailed review, let's do that interactively so I can explain some motivations and subtleties. I can also show you where and how to add 6th-order schemes with corresponding unit tests and how to expand the example programs to include any new schemes you add.

My original submission was marked draft because I expected merge conflicts, but I'm happy to see that there are none. Additionally, all tests pass so this is safe to merge.