== Catering for MEDUSA coupling via OASIS3-MCT ==


'''Background'''

We need to cater for MEDUSA coupling at NEMO vn3.6 via the existing NEMO OASIS3-MCT interface and the Met Office UM code. 

This work is initially primarily for the purposes of the UKESM project, however ultimately it is considered that the MEDUSA coupling interface would become a generally available option to any configuration which chooses to employ it. 


'''Development'''

The MEDUSA code itself is held in a development branch, created and maintained at NOC named, at time of writing, [log:branches/NERC/dev_r5518_NOC_MEDUSA_Stable dev_r5518_NOC_MEDUSA_Stable]
 
This code potentially provides output fields to a coupler and receives input fields from a coupler to allow it to couple with an atmosphere model featuring dust and vegetation schemes. 

Currently the specific coupling fields are expected to be:

* Output:
   * CO2 Flux (MEDUSA field f_co2flux2d)
   * DMS  (MEDUSA field dms_surf2d)

* Input:
   * CO2 partial pressure (MEDUSA field f_pco2a. This is expected to come from the atmosphere and in the case of the UM specifically from the "TRIFFID" scheme)
   * Dust (MEDUSA field dust.  This is expected to come from the atmosphere and in the case of the UM specifically from some special code which is as yet undeveloped!)


The code development needs to be compatible with the MO GO6 ocean model configuration. This configuration currently features approximately 11 separate code branches which makes further development of additional code 
potentially problematic in terms of a high risk of code conflicts.

It also needs to be compatible with the MO GC3 coupled model configuration which adds a further 4 NEMO branches.

While the bulk of the MEDUSA code is self contained under the TOP_SRC directory and thus less prone to causing conflicts, the coupling interface code is 
a very high risk in terms of conflicts since it needs to modify sbccpl.F90 and perhaps other high level coupling routines. 

Oddly we find that the conflicts we see from the MEDUSA coupling interface developments are with code contained in the GO6 definition and not with the coupling specific code added by the extra GC3 branches. 
Specifically, we find that [log:branches/UKMO/dev_r5518_coupling_GSI7_GSI8_landice_bitcomp dev_r5518_coupling_GSI7_GSI8_landice_bitcomp] is a major source of clashes. There is no way to rework the MEDUSA
interface to avoid this because this branch, although only part of the GO6 configuration, actually features changes relating to coupled models (for reasons of avoiding code clashes!) particularly w.r.t. the magic numbers used for coupled field indexing. 

Discussing with Tim Graham, he's happy for the MEDUSA interface to be added to the GO6 definition (i.e. to [log:branches/UKMO/dev_r5518_coupling_GSI7_GSI8_landice_bitcomp dev_r5518_coupling_GSI7_GSI8_landice_bitcomp] or a variant of that branch) provided we can disable the MEDUSA code to allow that branch to continue to be compatible with all existing non MEDUSA configurations.

That should be do-able. It seems we'll have to control the relevant code with key_medusa, which is not ideal, unless we can introduce dummy modules containing dummy variable declarations which would allow us to 
control things within sbccpl.F90, etc purely with run time logicals.  

Initially I start on the basis of controlling things with CPP keys. 

* Created new NEMO vn3.6 branch:  [log:branches/UKMO/dev_r5518_GSI7_GSI8_landice_bitcomp_medusa dev_r5518_GSI7_GSI8_landice_bitcomp_medusa]
* Merged in  [log:branches/UKMO/dev_r5518_coupling_GSI7_GSI8_landice_bitcomp dev_r5518_coupling_GSI7_GSI8_landice_bitcomp] at revision 6659
* Added MEDUSA-specific coupling interface changes to sbccpl.F90 (revisions 6659-6670 inclusive). NOTE: These are not finalised in any sense since we have no UM/coupler source for the incoming dust, the incoming f_pco2a field is not defined as a 2D field in MEDUSA, merely as a single value scalar and the f_co2flux2d probably has nowhere to go in the UM while bugs remain to be fixed in the UM TRIFFID scheme. 
* So the only field we might reasonably couple and expect to deal with realistically at the moment is the MEDUSA->UM DMS field.    

'''Testing'''

* Compilation: Using a copy of u-ad903 we have successful compilation. BUT to achieve this I have to take a copy of Julien's [log:branches/NERC/dev_r5518_NOC_MEDUSA_Stable dev_r5518_NOC_MEDUSA_Stable] and make modifications to ensure that various necessary fields are made publicly  available in order to allow them to be referenced in the main NEMO code. The method of doing this is to move the declaration of the necessary fields to the top of the appropriate module definition. This is not necessarily ideal since there are numerous similar variables not required for coupling which remain defined within subroutines in the modules. It may be that an alternative approach is to define the coupling fields within sbccpl or cpl_oasis and then have those referenced by the MEDUSA code. This approach may also allow us to dispense with CPP keys in the main NEMO code but does have the overhead of needing MEDUSA to copy the fields to and from their ultimate target and source arrays.