Coupling directory

Contents of directory

A typical run directory, ~/umui_jobs/<runid>, will contain the following files

$ ls 
CNTLALL		FCM_BLD_COMMAND    IOSCNTL   SCRIPT    USR_FILE_OVRDS
CNTLATM		FCM_UMATMOS_CFG    JOBSHEET  SHARED    USR_MACH_OVRDS
CNTLGEN		FCM_UMRECON_CFG    MAIN_SCR  SIZES     USR_PATHS_OVRDS
COMP_SWITCHES	FCM_UMSCRIPTS_CFG  PPCNTL    STASHC
EXTR_SCR	INITFILEENV	   PRESM_A   SUBMIT
EXT_SCRIPT_LOG	INITHIS		   RECONA    UMSUBMIT

After running the coupling script you should have a run directory, ~/umui_jobs/<senior runid>_<junior runid>/, which looks like this

$ ls
CNTLALL		 FCM_UMATMOS2_CFG   IOSCNTL   SCRIPT	USR_FILE_OVRDS
CNTLALL2	 FCM_UMATMOS_CFG    IOSCNTL2  SHARED	USR_FILE_OVRDS2
CNTLATM		 FCM_UMRECON2_CFG   MAIN_SCR  SHARED2	USR_MACH_OVRDS
CNTLATM2	 FCM_UMRECON_CFG    PPCNTL    SIZES	USR_MACH_OVRDS2
CNTLGEN		 FCM_UMSCRIPTS_CFG  PPCNTL2   SIZES2	USR_PATHS_OVRDS
CNTLGEN2	 INITFILEENV	    PRESM_A   STASHC	USR_PATHS_OVRDS2
COMP_SWITCHES	 INITFILEENV2	    PRESM_A2  STASHC2
EXTR_SCR	 INITHIS	    RECONA    SUBMIT
FCM_BLD_COMMAND  INITHIS2	    RECONA2   UMSUBMIT

There is one version of COMP_SWITCHES, EXTR_SCR, FCM_BLD_COMMAND, FCM_UMSCRIPTS_CFG, MAIN_SCR, SCRIPT, SUBMIT and UMSUBMIT, and two versions of all the other files - the first for the senior UM and the second version for the junior UM.

Executable scripts: adding UMATMOS2 and UMRECON2 and other changes

In a standard run directory, if you do an `ls -l', you'll see that there are four executable scripts

COMP_SWITCHES: not really a script, it exports the variables EXTR_UMATMOS, COMP_UMSCRIPTS etc, which indicate which operations should be carried out
MAIN_SCR: runs EXTR_SCR followed by UMSUBMIT (see items below)
EXTR_SCR: extracts and creates the code using the FCM_* files
UMSUBMIT: this
1. copies the contents of this directory to your HPC account in ~/umui_runs/<runid>-<time stamp>
2. runs SUBMIT script on HPC, which creates
  - umuisubmit_compile: compiles code and creates the executables
  - umuisubmit_rcf: runs reconfiguration
  - umuisubmit_run: runs the main run
  - stage_1_submit: runs umuisubmit_compile and submits stage_2_submit
  - stage_2_submit: runs umuisubmit_rcf and submits umuisubmit_run
3. submits stage_1_submit to HPC, which starts the compilation and leads to the other stages

The UMUI creates all the files in the run directory and then runs the command

$ ./MAIN_SCR

which runs your job, so you may not have had reason to look at this directory before.

The one script not mentioned above is SCRIPT, which is pasted into both umuisubmit_rcf and umuisubmit_run. This specifies many of the environment variables used by the code and runs UMScr_TopLevel which is the entry point for the submission scripts found in /projects/um1/vn8.6/ibm/scripts - which submits your executables to the HPC.

The coupleJobs.scr scripts modifies all of these scripts, except UMSUBMIT. In EXTR_SCR, MAIN_SCR and SUBMIT there are some loops over the sub-models of the UM, such as UMATMOS and UMRECON, which allow executables for each component to be created. To create a second atmosphere executable and a second reconfiguration the strings UMATMOS2 and UMRECON2 have been added into these loops. And COMP_SWITCHES has needed the variables EXTR_UMATMOS2, COMP_UMATMOS2 and COMP_UMRECON2 adding.

SCRIPT has required a whole host of second version variables adding, so that the senior and junior UM can have their own environment variables. If the senior job was not previously coupled, some OASIS arguments also need adding. And some of the code from the junior version of SCRIPT for setting up the ancillary code needs adding (see Ancillary setup files for more on this).

In addition to adding UMATMOS2 and UMRECON2 into the sub-models loop for SUBMIT, something of a bodge has also been added to include an extra reconfiguration stage. Like the senior UM, the junior UM requires a reconfiguration stage. The creation of an extra stage_*_submit script and a umuisubmit_rcf could be done properly in the same way the other stage_*_submit and umuisubmit_* are created. However, modifying SUBMIT to do this would be quite complicated and involved and it's simpler to bodge some changes to the existing stage_*_submit and umuisubmit_* files. Code is added to the bottom of SUBMIT which

creates umuisubmit_rcf2 from umuisubmit_rcf, changing some of the arguments
create stage_3_submit from stage_2_submit, but the junior reconfiguration is done in place of the senior reconfiguration.
stage_2_submit is modified so that its final submission is stage_3_submit - not umuisubmit_run, as before.
An enviroment variable to provide an output file for the junior UM is added to umuisubmit_run

Build scripts (FCM_* files)

The EXTR_SCR script uses the FCM* files to build the code. Only one version of FCM_BLD_COMMAND is required, and it requires a few modifications

adding UMATMOS2 and UMRECON2 into its submodel loop
some code to change the name of the executables which are produced - really just to make sure that the reconfiguration and main executables for both UMs are called the same thing
a couple of changes to environment variables

There is also only one version FCM_UMSCRIPTS_CFG, and no changes are made to this.

The bulk of FCM_UMATMOS_CFG and FCM_UMRECON_CFG are copies of the same file in the senior UM run directory, while similarly FCM_UMATMOS2_CFG and FCM_UMRECON2_CFG are copies of FCM_UMATMOS_CFG and FCM_UMRECON_CFG from the junior UM run directory. The changes are:

If the runs didn't include code to include OASIS before, this code needs adding.
Code is added to included branches to the code. More detail on the Branches page.

The FCM_* script also use the USR_* files ...

INITFILEENV

INITFILEENV is unchanged from the version in the senior run directory. INITFILEENV2 needs a lot of changes from the version in the junior run directory, because we the junior UM can't use the run variables intended for the senior UM - especially if the senior and junior UM are of different resolutions.

The changes for INITFILEENV2 are largely just adding `2' or `_2' to the environment variables. More information on the Environment variables page.

Namelists and other files

The remaining files are almost all namelists, and they're all input files for the UM. The versions without a 2 at the end of the filename are largely just copies from the senior run directory, while the versions with a 2 come from the junior run directory. The other changes are