Error handling

[SeanBryan51]

This is a sub issue of #486 specifically tracking the implementation of a better error handling capability.

[Whyborn]

What are requirements of the error handler in your opinion? Mine would be:

• Provide a description of what the cause of the error is
• Describe which line and file triggered the error
• Handle MPI exit in a consistent way
• Provide an informative exit code that other tools e.g. CI/CD can catch and interpret
• No modification of any existing function/subroutine signatures. Should never be more than a one-liner addition.

[SeanBryan51]

Those sound good to me. I would also add the ability to configure the behaviour of how the error handler should exit the program, as this could be different if we are running unit tests, or if CABLE is running in a host model like the UM.

[Whyborn]

What ways of exiting are you imagining?

[SeanBryan51]

See 3.19 Error reporting (UMDP 003: coding standards)

[Whyborn]

That's just a distinction between errors and warnings right? I think they're separate concerns? If there are contexts where a program should error when running in a particular mode and just a warning in other modes, then should be separate calls. Say we want to be able choose whether an LAI too low causes the program to abort, or adjust the value and continue, then I think it's better to have:

if (LAI < LAI_minimum) then
  if (LAI_too_low_error) then
    call cable_abort("LAI fell below the minimum LAI", __LINE__, __FILE__, <some error code>)
  else
    call cable_warning("LAI fell below the minimum LAI. Setting to <some min value>", __LINE__, __FILE__, <some warning code?>)
    LAI = LAI_minimum
  endif
endif

I would much prefer this over a routine that behaved fundamentally different depending on the value of the error code passed, as the UM does.

[SeanBryan51]

My main concern was that the UM requires the code to call ereport when fatal errors happen. So we should provide the ability to overwrite the default abort behaviour with for example a call to ereport, instead of mpi_grp%abort() or error stop, etc.

I completely agree with your comments on how warnings should be treated errors.

[Whyborn]

Having CABLE call ereport is incompatible with including CABLE as a library- we can't call back to UM code within CABLE code (actually one of the things making the current library effort a pain- there was an effort to do things in the "UM" way, but this code can't live in the CABLE code, since we won't be able to call UM code if we make it a library)

[SeanBryan51]

we can't call back to UM code within CABLE code

I disagree, you can if you use dependency injection: https://en.wikipedia.org/wiki/Dependency_injection

[Whyborn]

Can you give an example as to how that would work in Fortran? Why wouldn't you have to use the module defining the ereport routine, leading to a compile failure when building the library?

[SeanBryan51]

Suppose we have a class(cable_error_handler_base_t), allocatable :: error_handler instance used by an error handling module in CABLE. There are initialisation routines for setting this error handler when initialising the error handling module:

module cable_error_handler_mod
  implicit none
  private

  class(cable_error_handler_base_t), allocatable :: error_handler

contains

 subroutine cable_error_handler_mod_init(new_error_handler)
    class(cable_error_handler_base_t), intent(in) :: new_error_handler
    error_handler = new_error_handler
  end subroutine

  subroutine cable_error_handler_mod_end()
    deallocate(error_handler)
  end subroutine

  subroutine cable_abort(message, file, line)
    character(len=*), intent(in) :: message
    character(len=*), intent(in) :: file
    integer, intent(in) :: line

    call error_handler%log_message(message, file, line)
    call error_handler%abort()

  end subroutine

end module

The class keyword is key as this facilitates dependency injection, and cable_error_handler_base_t, cable_error_handler_mod_init and cable_error_handler_mod_end are exported as part of the library interface for CABLE.

In the UM, you want to overwrite the behaviour of error_handler%abort(), so you define a subclass of cable_error_handler_base_t and overwrite the abort method. This would be a part of the CABLE coupling within the UM source files:

module cable_error_handler_um_mod
  use cable_error_handler_mod, only: cable_error_handler_base_t  
  use ..., only: ereport
  implicit none
  private

  type, extends(cable_error_handler_base_t) :: cable_error_handler_um_t
  contains
    procedure :: abort => cable_error_handler_um_abort
  end type cable_error_handler_um_t

contains

  subroutine cable_error_handler_um_abort(this, ...)
    class(cable_error_handler_um_t), intent(inout) :: this
    ! ... other arguments as needed
    call ereport(...)
  end subroutine

end module

When the UM initialises CABLE, we declare an instance of cable_error_handler_um_t and pass it to cable_error_handler_mod_init to initialise the error handling module from the UM. This "injects" the error handler dependency into the error handler module used by CABLE.

[SeanBryan51]

Why wouldn't you have to use the module defining the ereport routine, leading to a compile failure when building the library?

In the above example, the key to this is that error handler is initialised dynamically at runtime and not at compile time.

[Whyborn]

Ah so it would still have some code on the UM/JULES side? I would like to avoid this wherever possible. I haven't actually looked at the ereport routine, but I haven't had great experiences with the UM's error reporting so far. Personally I'd consider it pretty low importance to be able to abort/error in the "UM" way, but I don't know other's opinions on this.