Update time interval error message

[mauzey1]

Resolves #913

This will change the error/warning message printed by the time interval check.

If the user doesn't specify a frequency attribute but the approximate time interval is set through the variable tables, then the following message is printed when an error occurs.

C Traceback:
! In function: cmor_check_interval
! called from: cmor_axis
! 

!!!!!!!!!!!!!!!!!!!!!!!!!
!
! Error: Dataset was defined with an approximate time interval of 30 days, but time axis values 1 and 2 have an interval of 45 days.
! Please adjust the time values in your data to be consistent with the defined approximate time interval.
!
!!!!!!!!!!!!!!!!!!!!!!!!!

If the frequency is specified, then it will look like the following.

C Traceback:
! In function: cmor_check_interval
! called from: cmor_write_var_to_file
! called from: cmor_write
! 

!!!!!!!!!!!!!!!!!!!!!!!!!
!
! Error: Dataset was defined with the frequency 'mon', which has an approximate time interval of 30 days, but time axis values 0 and 1 have an interval of 20 days.
! Please adjust the time values in your data to be consistent with the selected frequency.
!
!!!!!!!!!!!!!!!!!!!!!!!!!

[durack1]

This is great @mauzey1. Just thinking a little about this, we have 3 use cases to account for

• fixed fields (with no time axis, e.g., PCMDI/cmip6-cmor-tables/Tables/CMIP6_fx.json)
• CMIP6* data (also CMIP6Plus, CMIP5, and earlier are not supported; with frequency and approximate interval defined in the table files, e.g., PCMDI/cmip6-cmor-tables/Tables/CMIP6_Amon.json)
• CMIP7 data (with no frequency OR approximate interval defined in the table files, e.g., WCRP-CMIP/cmip7-cmor-tables/tables/CMIP7_atmos.json or CVs e.g., WCRP-CMIP/cmip7-cmor-tables/tables-cvs/cmor-cvs.json)

It also seems like the frequency/approx_interval info that we had collated in PCMDI/cmor/TestTables/CMIP7_CV.json have not been copied across into the CMIP7 prototypes, and to be honest as these are fixed for Earth's calendar, we should just embed this into the CMOR configuration info - do we have some internal info carried around in *.jsons we can append to, this info is at

cmor/TestTables/CMIP7_CV.json

Lines 119 to 152 in 4e7f1f3

	"frequency":{
	"1hr":{
	"approx_interval":0.041666666666666664,
	"description":"sampled hourly"
	},
	"1hrCM":{
	"approx_interval":0.041666666666666664,
	"description":"monthly-mean diurnal cycle resolving each day into 1-hour means"
	},
	"3hr":{
	"approx_interval":0.125,
	"description":"3 hourly samples"
	},
	"6hr":{
	"approx_interval":0.25,
	"description":"6 hourly samples"
	},
	"day":{
	"approx_interval":1.0,
	"description":"daily mean samples"
	},
	"dec":{
	"approx_interval":3650.0,
	"description":"decadal mean samples"
	},
	"fx":"fixed (time invariant) field",
	"mon":{
	"approx_interval":30.0,
	"description":"monthly mean samples"
	},
	"yr":{
	"approx_interval":365.0,
	"description":"annual mean samples"
	}

The behaviour from CMOR 3.14.1 onwards requires the user to provide a frequency argument in the user_input.json, no matter what data is being written. This will mean for the CMIP6* cases, we'll need to check the user_input.json frequency and the CMIP6 table file frequency.

So following the examples above, can we augment with even more explicit error messages, as below please (I have trimmed out some empty lines etc, just for brevity in this issue (please leave them in the error block - makes it easier and less clustered to read):

Case CMIP6*
If a user doesn't specify a frequency attribute, but tables include a frequency and an approximate interval, the following message is printed when an error occurs.

C Traceback:
! In function: cmor_check_interval
! called from: cmor_axis
!!!!!!!!!!!!!!!!!!!!!!!!!
! Error:
No required `frequency` attribute provided in `../pathToUserFile/user_input.json`. Table file `../pathToTableFile/CMIP6_Amon.json` includes frequency: <frequency>, and approximate interval: <approximateInterval>.
The dataset was defined with an approximate time interval of 30 days, but the time axis values 1 and 2 have an interval of 45 days.
! Please adjust the time axis/values in your data to be consistent with the defined frequency and approximate time interval.
!!!!!!!!!!!!!!!!!!!!!!!!!

Case CMIP7
If the frequency is specified, then it will look like the following.

C Traceback:
! In function: cmor_check_interval
! called from: cmor_write_var_to_file
! called from: cmor_write
!!!!!!!!!!!!!!!!!!!!!!!!!
! Error:
Required `frequency` attribute provided in `../pathToUserFile/user_input.json` with value <frequency>. Table file `../pathToTableFile/CMIP7_atmos.json` excludes frequency: <frequency>, and approximate interval: <approximateInterval>.
The dataset was defined with an approximate time interval of 30 days, but the time axis values 0 and 1 have an interval of 20 days.
! Please adjust the time axis/values in your data to be consistent with the defined frequency and approximate time interval.
!!!!!!!!!!!!!!!!!!!!!!!!!

Do we need an example for the fixed/fx no time axis example? If yes, let me know and I will think this up too

@taylor13 ping

[mauzey1]

@durack1 I'm seeing three changes being asked for in #915 (comment). I have them listed below with some accompanying questions.

1. Make frequency a required attribute of all datasets written by CMOR.
   • Should the frequency attribute be required even if the dataset doesn't have a time axis?
2. Have frequency values and their corresponding time interval values be part of CMOR's default configuration.
   • We do have supported calendar types hard-coded into CMOR so I can see doing something similar with frequencies and their intervals. Can these values be overridden by the frequencies and intervals found in the CV or tables?
3. Modify time interval check error messages to include user input file and variable table file paths.
   • For the CMIP6 case, wouldn't the lack of frequency attribute in the user input be captured as an error due to the attribute being required?

[mauzey1]

@durack1 I have updated this pull request with changes to the error/warning message structure. Below are some examples.

An example when the user doesn't specify a frequency but the interval information comes from the variable table. The error occurs when the time axis is defined.

C Traceback:
! In function: cmor_check_interval
! called from: cmor_axis
! 

!!!!!!!!!!!!!!!!!!!!!!!!!
!
! Error: No frequency attribute provided in dataset configuration.
! Expected interval between time axis values: 30 days
! Actual interval between time axis values 1 and 2: 45 days (50.0% difference)
! Input JSON: Test/CMOR_input_example.json
! Table JSON: CMIP6_Amon.json
! 
! Please add a 'frequency' attribute to your input JSON 
! or use a variable definition that has a 'frequency' value,
! and ensure time values are consistent with that frequency.
!
!!!!!!!!!!!!!!!!!!!!!!!!!

Here's when the error occurs when passing the time values via cmor_write. The frequency is acquired from the table entry.

C Traceback:
! In function: cmor_check_interval
! called from: cmor_write_var_to_file
! called from: cmor_write
! 

!!!!!!!!!!!!!!!!!!!!!!!!!
!
! Error: Time interval mismatch detected for frequency: 'mon'
! Expected interval between time axis values: 30 days
! Actual interval between time axis values 0 and 1: 20 days (33.3% difference)
! Input JSON: Test/CMOR_input_example.json
! Table JSON: CMIP6_Amon.json
! 
! Please adjust the time values in your data to be consistent with frequency 'mon',
! or update the frequency attribute if your data has a different temporal resolution.
!
!!!!!!!!!!!!!!!!!!!!!!!!!

If the user doesn't provide a frequency when using CMIP7 tables, which don't have frequencies for their variable entries. There are now frequencies built into CMOR that users can select.

C Traceback:
! In function: cmor_variable
! 

!!!!!!!!!!!!!!!!!!!!!!!!!
!
! Error: Starting with CMOR version 3.14.1, the 'frequency' attribute is required
! for all variables with a time axis.
! Input JSON: test_no_frequency_cmip7.json
! Table JSON: CMIP7_atmos.json
! Please add 'frequency' to your input JSON file, or use a variable definition that has a 'frequency' value.
! Valid frequencies: 1hr, 3hr, 6hr, day, mon, yr, dec, fx (see CMIP documentation).
!
!!!!!!!!!!!!!!!!!!!!!!!!!

If the user provides a frequency that differs from the table's variable entry frequency, CMOR will warn the user of the mismatch and prioritize the table's frequency.

C Traceback:
In function: cmor_variable
! 

!!!!!!!!!!!!!!!!!!!!!!!!!
!
! Warning: Frequency mismatch detected.
! Input JSON frequency: 'day' (from test_freq_mismatch_cmip6.json)
! Table frequency: 'mon' (from CMIP6_Amon.json)
! For CMIP6 tables, the frequency in your input JSON must match the table frequency.
! Please update your input JSON to use frequency='mon'.
!
!!!!!!!!!!!!!!!!!!!!!!!!!

Minor bug fix:
Fixed an out-of-bounds memory access when iref == CMOR_MAX_ELEMENTS in the section below.

cmor/Src/cmor_variables.c

Lines 1090 to 1095 in 9beeee2

	if (iref >= CMOR_MAX_ELEMENTS) {
	refvar = cmor_tables[CMOR_TABLE].formula[iref - CMOR_MAX_ELEMENTS];
	} else {
	refvar = cmor_tables[CMOR_TABLE].vars[iref];
	}