Change coupling region - nick-klingaman/mckpp GitHub Wiki

Changing the coupling region

You will need to change the coupling region if you want to add or remove ocean coupling at one or more ocean gridpoints. This may be because:

  • You want to test the sensitivity of Your Favorite Thing to atmosphere-ocean interactions in a particular region.
  • You want to prescribe sea-surface temperatures to the atmosphere in a region, and therefore need to remove coupling.
  • You change the prescribed sea-ice climatology, which requires changing the coupling region (more on this below).
  • You want to run at a different resolution and need to generate a new coupling ancillary file.

Background

To determine where to couple the ocean and atmosphere, MC-KPP uses two ancillary files:

  1. A land-fraction ancillary file, which determines which points are ocean and which are land. Typically, we treat all points with non-zero ocean fraction as ocean points. This file is not discussed further here.
  2. A coupling-weight ancillary file, which determines which ocean points are coupled and which are not. Note that MC-KPP ignores the value of the coupling-weight over land points, because land points cannot be coupled.

MC-KPP returns an SST to the atmospheric model at all ocean gridpoints, regardless of whether they are coupled. The value of the coupling weight determines which SST MC-KPP returns to the atmosphere:

  • At gridpoints at which the coupling weight is exactly 0.0, MC-KPP returns the prescribed climatological SST, which the user provides via an ancillary file, or the SST from the initial condition, if the corresponding namelist options are enabled.
  • At gridpoints at which the coupling weight is exactly 1.0, MC-KPP returns its predicted SST.
  • At gridpoints at which the coupling weight is between 0.0 and 1.0, MC-KPP returns a linearly weighted combination of the predicted and climatological SST. The value of the coupling weight determines the weight given to the predicted (coupled) SST (hence the name).

If the user does not provide a coupling-weight ancillary file, all ocean gridpoints are assumed to be coupled.

Standard practice

For climate experiments, the standard practice is to couple at all ocean gridpoints that are not:

  • Covered by sea-ice for a critical fraction of the year in an observed sea-ice climatology, defined to be ten days per year of full coverage (or the equivalent in partial coverage, e.g. 50% covered for 20 days). We typically use the Reynolds sea-ice climatology from the AMIP dataset. We do not couple over these points because KPP does not include an interactive sea-ice model.
  • Part of one of the following inland seas: Caspian Sea, Lake Baikal, Lake Victoria, Red Sea, Persian Gulf, Black Sea, Great Lakes.
  • Flanked on both sides (in either the x or y direction) by uncoupled gridpoints, after the masks above are applied.

After removing those uncoupled gridpoints, the oceanic boundaries between coupled and uncoupled regions (i.e., not the coastlines, but the places where coupled and uncoupled ocean meet) are smoothed, so that the coupling weight progresses linearly from 1.0 to 0.0 over a distance of approximately 8 degrees: 5 points at N96, 12 points at N216 and 30 points at N512. As this smoothing has to be applied in x and y directions, a repeating discontinuity sweep is applied to ensure that the coupling weight is smooth.

The python script kpp_cplwght_seaice.py demonstrates these steps and can be used as a template to create your own coupling weight file.

Creating a coupling weight file

To alter the coupled region, you will need to produce a new coupling weight ancillary, with the dimensions and variables named as described in the MC-KPP documentation . Exactly how you create this file will depend on the nature of your region:

  • If you wish to couple at all ocean points within a rectangular region, you can start from the kpp_cplwght_seaice.py script and modify it accordingly.
  • If you wish to couple over several rectangles, you can run the script several times, once for each rectangle, and add the resulting coupling weights (as long as the rectangles do not overlap).
  • If you wish to remove coupling within a rectangular region, you can generate a coupling-weight file for the region you wish to remove (as though you were going to couple within it), then subtract this from the standard near-global coupling-weight ancillary file to generate your coupling-weight file.
  • If your region is non-rectangular, you will be largely on your own, but you can still use the kpp_cplwght_seaice.py script as a guide (e.g., for smoothing at the boundaries and removing inland basins).

The kpp_cplwght_seaice.py script requires the MetUM land-fraction file (in netCDF) and a sea-ice climatology. Both of these must be at the same horizontal resolution as MC-KPP.

When you run the kpp_cplwght_seaice.py script, it will output the values of four parameters that you will need when editing your MetUM-GOML Rose suite: ifirst, ilast, jfirst and jlast. These are the first and last longitude and latitude points, respectively, in the coupled region.

Altering the MC-KPP horizontal domain

If your new coupling region fits entirely inside the standard near-global coupling region (i.e., you are not extending the near-global coupling region to the north or south), then you do not need to follow this step. You may still wish to follow it to reduce the memory MC-KPP requires, particularly if you are running at a high horizontal resolution (higher than N216).

If you need to change the horizontal domain, you should follow these instructions . The kpp_cplwght_seaice.py script will output the values of the various MC-KPP parameters that you need for those instructions, if you use that script.

Running with your new coupling-weight file

To include your new coupling-weight ancillary file and adjust the coupling domain, you will need to edit coupled -> namelist -> KPP Namelist -> Coupling Controls:

  • cplwght_file: Add the path to your coupling weight file on the HPC.
  • l_cplwght: Ensure this is set to TRUE.
  • ifirst, ilast, jfirst and jlast: Use the values provided by the kpp_cplwght_seaice.py script, if you used it. If you did not use it, you will need to insert the indices of the first and last coupled points, in x (longitude) and y (latitude) respectively, on the atmospheric grid. Note that these are the indices, not the values in degrees. Also note that MC-KPP is written in Fortran, so these indices are 1-based. Finally, note that these are the indices on the atmospheric grid, not the KPP horizontal domain. In other words, you must specify the indices corresponding to the smallest and largest longitudes (in degrees east) and the southernmost and northernmost latitudes, respectively, at which MC-KPP is coupled to the atmosphere. If your coupling region is not rectangular (e.g., it has a ragged edge along the sea ice), these indices should be the maximum extent of the domain (i.e., the smallest or largest values in any row or column).