Consolidating logging and error handling in CABLE

[SeanBryan51]

Currently, CABLE is inconsistent in how the program is aborted or STOPed throughout the code base. For example, when using an MPI build, STOP should be replaced with a call to MPI_Abort (via mpi_grp_abort) and there is also an abort subroutine defined in cable_abort_module which is sometimes used. It would be nice if these approaches were consolidated across the codebase (also potentially for use in the coupled model).

A nice (but maybe naive) approach would be to use the existing abort functionality to encapsulate the abort logic however this will probably depend on some state in the top level scope (e.g. the current MPI rank or the total number of MPI ranks). Passing this state information as an argument to abort seems like it will be a bit burdensome to pass throughout the entire code base. A better approach could be to instantiate a singleton logging object to handle the logging and abort behaviour.

This also raises questions on how we want do error handling and logging in general (also in a coupled model context noting that CABLE maybe built as a library in the future). It would be good to have an idea of the key requirements for a consolidated logging and error handling framework for CABLE.

[SeanBryan51]

Requirements:

• Runtime switch which controls: 1. writing logs only to the log file or 2. writing logs only to standard output/error or 3. writing logs both to the log file and standard output/error
• Runtime switch which controls the amount of logging for different severity/verbosity levels.

Potentially relevant:

• MOM6 error handling routines
• 3.19 Error reporting (UMDP 003: coding standards)

[Whyborn]

I think our error handling requirements are fairly small- the main benefit to an error handling procedure (I think) is to be able to explicitly test that the code exits in an expected way. I think the potential risks if the code doesn't exit in the expected way are pretty small. As long as we're consistent, I'd be happy

[SeanBryan51]

__FILE__ and __LINE__ macros are useful for describing where warnings or errors come from in the source code.

• https://www.intel.com/content/www/us/en/docs/fortran-compiler/developer-guide-reference/2025-0/fpp-preprocessor-directives.html
• https://gcc.gnu.org/onlinedocs/cpp/Standard-Predefined-Macros.html

[SeanBryan51]

In the context of #641, I'm going to see if I can make some progress on this.

I think I will split this issue into two issues, one tackling the error handling of fatal errors, and another addressing the way logging is handled. From my experimentation in #641, the handling of fatal errors seems easier address than the logging, so I will try working on that first.

On logging, we currently have a verbose namelist flag which could be used to set the verbosity level of the logger.