Add analytic tests

[samhatfield]

Will explain this properly once it's working (you can probably guess what it is).

[samhatfield]

Okay, mostly in a good state now:

This PR adds analytic tests for INV_TRANS. This is based heavily on initial work by @anmrde a few years ago, but drastically simplified. I decided that it would be better to introduce the functionality of https://github.com/anmrde/ectrans/tree/feature/analytic-tmp bit-by-bit rather than all at once.

The PR adds a new test directory, "analytic". This contains a test program, analytic_test.F90. This program is similar to the ecTrans benchmark program, but with fewer options, no timing capability, and a more targeted, analytic correctness checker.

The core of the program is a loop over all zonal m and total n wavenumbers:

ZMAX_ERROR = 0.0_JPRB

! Loop over all wavenumbers (check actually tested wavenumber inside)
DO M = 0, NSMAX
  ! Prepare Legendre polynomials for this zonal wavenumber
  CALL PREPARE_LEGENDRE_POLYNOMIALS(M, NSMAX)

  DO N = M, NSMAX
    CALL INITIALIZE_SPECTRAL_ARRAY(NSMAX, M, N, ZSPSCALAR)

    ! Compute analytic solutions
    ZSPH_ANALYTIC = COMPUTE_ANALYTIC_SOLUTION(NPROMA, NGPBLKS, NGPTOT, M, N)

    ! Do inverse transform
    CALL INV_TRANS(PSPSCALAR=ZSPSCALAR, KPROMA=NPROMA, KVSETSC=IVSET, PGP=ZGP)

    ZMAX_ERROR = MAX(ZMAX_ERROR, COMPUTE_MAX_ERROR(NGPTOT, NPROMA, ZGP(:, 1, :), ZSPH_ANALYTIC(:, :)))

    ! Do direct transform
    CALL DIR_TRANS(PGP=ZGP, KPROMA=NPROMA, KVSETSC=IVSET, PSPSCALAR=ZSPSCALAR)
  END DO
END DO

At each (m, n), a spectral array is filled with (0.0 + 0.0i) except a (1.0 + 0i) at the given (m, n). This will give a spherical harmonic in grid point space when the field is inverse transformed. An "analytic" solution is also computed, which is the gridded values of that spherical harmonic computed from the Legendre polynomials and a cosine function. The maximum absolute difference between these two is calculated and kept. If all maximum absolute differences over all wavenumbers is below a prescribed tolerance, the test passes.

Computation of the analytic solutions uses SUPOLF to prepare the Legendre polynomials. This is the same function as is used when initialising ecTrans. Therefore the test cannot check correctness of SUPOLF. IMO, this is better done separately through an API test of TRANS_PNM, which is basically a thin wrapper around SUPOLF.

Crucially, computation of the analytic solution doesn't involve a GEMM, an FFT, nor any of TRGTOL etc. So it is a meaningful test.

I will mark this as ready for review so reviewers can give any early opinions, but the following still needs to be done:

• Replace direct call of SUPOLF in PREPARE_LEGENDRE_POLYNOMIALS with a call of TRANS_PNM (not supposed to call ecTrans internal routines).
• Implement a check for DIR_TRANS also. Idea: perform DIR_TRANS on analytic solution and check spectral coefficients are all 0.0 + 0.0i except for one.
• General code quality check for ANALYTIC_TEST and ANALYTIC_UTILS.
• Introduce OOP to better manage state in ANALYTIC_UTILS.

[Copilot]

Pull request overview

Adds a new Fortran-based analytic correctness test suite for ecTrans transforms, wiring it into the existing CTest/ecbuild test structure.

Changes:

• Introduces ANALYTIC_UTILS helper module for grid geometry lookup and Legendre polynomial preparation.
• Adds ANALYTIC_TEST program that runs inverse/direct transforms across wavenumbers and checks error against a tolerance.
• Integrates the new analytic test targets into the test CMake configuration.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 14 comments.

File	Description
tests/trans/analytic/analytic_utils.F90	New helper module to build lon/lat arrays, precompute Legendre polynomials, and compute analytic reference fields/errors.
tests/trans/analytic/analytic_test.F90	New test driver program that sets up ecTrans, generates analytic references, runs transforms, and checks errors.
tests/trans/analytic/CMakeLists.txt	Adds library/executable build rules and registers analytic tests for precisions/platforms/MPI configurations.
tests/CMakeLists.txt	Hooks trans/analytic into the global tests build, alongside existing test suites.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.