Range checks cable parameters (#287)

# CABLE

## Description

Fixes #225 

Add 2 flags to range checks

```
check%ranges (0, 1, 2) - When to do the range checks NO_CHECK, ON_TIMESTEP, ON_WRITE
check%exit (.true., .false.) - Whether to exit the program if range checks are done, and out of range - the other option is to provide a warning
```

- Checks are being done in the following stages
   1. Parameters of `soil` and `veg` before running the spinloop
2. Parameters when creating the NetCDF output file (some of them clash
with `soil` and `veg` but code can be refactored in the future to
account for that)
   3. Landuse variables I/O
   4. Variables in creating restart file
   5. Variables at every timestep
- Redesign `cable_output` with introducing `generate_out_write_acc`, and
`check_and_write`
- Change the range checks to be done in `cable_write` during
`cable_output`.
- Make `output_inclusion_type` dependencies clear between group output
and individual values

Tested with experiments in `bench_example` for `main` vs current commit.

<!-- readthedocs-preview cable start -->
----
📚 Documentation preview 📚:
https://cable--287.org.readthedocs.build/en/287/

<!-- readthedocs-preview cable end -->

documentation/docs/user_guide/inputs/cable_nml.md

@@ -50,7 +50,8 @@ applications. The following are annotated examples of cable.nml:
 | output%balances                  | logical            | .TRUE. .FALSE.                                             | .FALSE.                          | Output energy and water balances when .TRUE..                                                           |
 | output%grid                      | character(len=7)   | 'default' 'land' 'mask' 'ALMA'                             | 'default'                        | Output grid convention. `'land'` outputs land-only points, `'mask'` outputs masked spatial grids. `'ALMA'` uses the Assistance for Land-surface Modelling Activities convention. `'default'` uses the whichever convention the input meteorological file is using. |
 | output%averaging                 | character(len=7)   | 'all' 'daily' 'monthly' 'user6'                            | 'all'                            | Output averaging.                                                                                       |
-| check%ranges                     | logical            | .TRUE. .FALSE.                                             | uninitialised                    | Check input and output variables against valid ranges.                                                  |
+| check%ranges                     | integer            |  0 (`NO_CHECK`), 1 (`ON_TIMESTEP`), 2 (`ON_WRITE`)         | uninitialised                    | Check input and output variables at certain timesteps against valid ranges.                             |
+| check%exit                       | logical            | .TRUE. .FALSE.                                             | .FALSE.                          | Behaviour on failed range checks. If true , write to console and exit the program, else write to logfile as warning |
 | check%energy_bal                 | logical            | .TRUE. .FALSE.                                             | uninitialised                    | Check the energy balance.                                                                               |
 | check%mass_bal                   | logical            | .TRUE. .FALSE.                                             | uninttialised                    | Check the water/mass balance.                                                                           |
 | verbose                          | logical            | .TRUE. .FALSE.                                             | uninitialised                    | Write details of every grid cell initialisation and parameters to log.                                  |
@@ -160,7 +161,8 @@ applications. The following are annotated examples of cable.nml:
    output%veg       = .TRUE.  ! vegetation states
    output%params    = .TRUE.  ! input parameters used to produce run
    output%balances  = .TRUE.  ! energy and water balances
-   check%ranges     = .FALSE.  ! variable ranges, input and output
+   check%ranges     = 1  ! Range-checks on every timestep
+   check%exit = .TRUE.  ! Exit the program if range checks fail
    check%energy_bal = .TRUE.  ! energy balance
    check%mass_bal   = .TRUE.  ! water/mass balance
    verbose = .TRUE. ! write details of every grid cell init and params to log?

src/offline/cable_abort.F90

@@ -18,9 +18,9 @@
 !
 ! ==============================================================================
 
-
 MODULE cable_abort_module
 
+  USE cable_IO_vars_module, ONLY: check, logn
   IMPLICIT NONE
 
 CONTAINS
@@ -60,13 +60,12 @@ MODULE cable_abort_module
   !
   !==============================================================================
 
-
-  SUBROUTINE abort( message )
+  SUBROUTINE abort(message)
 
     ! Input arguments
     CHARACTER(LEN=*), INTENT(IN) :: message
 
-    WRITE(*, *) message
+    WRITE (*, *) message
     STOP 1
 
   END SUBROUTINE abort
@@ -109,17 +108,16 @@ END SUBROUTINE abort
   !
   !==============================================================================
 
-
-  SUBROUTINE nc_abort( ok, message )
+  SUBROUTINE nc_abort(ok, message)
 
     USE netcdf
 
     ! Input arguments
     CHARACTER(LEN=*), INTENT(IN) :: message
     INTEGER, INTENT(IN) :: ok
 
-    WRITE(*,*) message ! error from subroutine
-    WRITE(*,*) NF90_STRERROR(ok) ! netcdf error details
+    WRITE (*, *) message ! error from subroutine
+    WRITE (*, *) NF90_STRERROR(ok) ! netcdf error details
 
     STOP
 
@@ -140,60 +138,56 @@ END SUBROUTINE nc_abort
   !
   !==============================================================================
 
-
-
-  SUBROUTINE range_abort(message,ktau,met,value,var_range,                       &
-       i,xx,yy)
+  SUBROUTINE range_abort(vname, ktau, met, value, var_range, i, xx, yy)
 
     USE cable_def_types_mod, ONLY: met_type
-    USE cable_IO_vars_module, ONLY: latitude,longitude,landpt,lat_all,lon_all
+    USE cable_IO_vars_module, ONLY: latitude, longitude, &
+                                    landpt, lat_all, lon_all
 
     ! Input arguments
-    CHARACTER(LEN=*), INTENT(IN) :: message
+    CHARACTER(LEN=*), INTENT(IN) :: vname
 
-    INTEGER, INTENT(IN) ::                                                      &
-         ktau, & ! time step
-         i       ! landpt number of erroneous grid square
+    INTEGER, INTENT(IN) :: &
+      ktau, & ! time step
+      i       ! tile number along mp
 
-    INTEGER,INTENT(IN),OPTIONAL ::                                              &
-         xx, & ! coordinates of erroneous grid square
-         yy    ! coordinates of erroneous grid square
+    REAL, INTENT(IN) :: &
+      xx, & ! coordinates of erroneous grid square
+      yy    ! coordinates of erroneous grid square
 
+    TYPE(met_type), INTENT(IN) :: met  ! met data
 
-    TYPE(met_type),INTENT(IN) :: met  ! met data
+    REAL(4), INTENT(IN) :: value ! value deemed to be out of range
 
-    REAL,INTENT(IN) :: value ! value deemed to be out of range
+    REAL, INTENT(IN) :: var_range(2) ! appropriate var range
 
-    REAL,DIMENSION(2),INTENT(IN) :: var_range ! appropriate var range
+    INTEGER :: iunit
 
-    WRITE(*,*) "in SUBR range_abort"
-    WRITE(*,*) message ! error from subroutine
+    IF (check%exit) THEN
+      iunit = 6
+    ELSE
+      iunit = logn ! warning
+    END IF
 
-    IF( PRESENT(yy) ) THEN ! i.e. using rectangular land/sea grid
+    WRITE (iunit, *) "in SUBR range_abort: Out of range"
+    WRITE (iunit, *) "for var ", vname ! error from subroutine
 
-       WRITE(*,*) 'Site lat, lon:',lat_all(xx,yy),lon_all(xx,yy)
-       WRITE(*,*) 'Output timestep',ktau,                                       &
-            ', or ', met%hod(landpt(i)%cstart),' hod, ',                  &
-            INT( met%doy( landpt(i)%cstart) ),'doy, ',                   &
-            INT( met%year(landpt(i)%cstart) )
+    ! patch(i)%latitude, patch(i)%longitude
+    WRITE (iunit, *) 'Site lat, lon:', xx, yy
+    WRITE (iunit, *) 'Output timestep', ktau, &
+      ', or ', met%hod(i), ' hod, ', &
+      INT(met%doy(i)), 'doy, ', &
+      INT(met%year(i))
 
-    ELSE ! i.e. using compressed land only grid
+    WRITE (iunit, *) 'Specified acceptable range (cable_checks.f90):', &
+      var_range(1), 'to', var_range(2)
 
-       WRITE(*,*) 'Site lat, lon:', latitude(i), longitude(i)
-       WRITE(*,*) 'Output timestep', ktau,                                       &
-            ', or ', met%hod( landpt(i)%cstart ), ' hod, ',               &
-            INT( met%doy( landpt(i)%cstart) ),'doy, ',                    &
-            INT( met%year( landpt(i)%cstart) )
+    WRITE (iunit, *) 'Value:', value
 
+    IF (check%exit) THEN
+      STOP
     END IF
 
-    WRITE(*,*) 'Specified acceptable range (checks.f90):', var_range(1),        &
-         'to',var_range(2)
-
-    WRITE(*,*) 'Value:',value
-
-    STOP
-
   END SUBROUTINE range_abort
 
   !==============================================================================