Ctrl+K

Simple CROCO-TOY coupled example

19.3. Simple CROCO-TOY coupled example#

For this first step towards coupling, we will just use the BENGUELA_LR configuration and add coupling with a toy model that mimics a wave model. The toy model is available in the croco/SCRIPTS/SCRIPTS_COUPLING/TOY_IN. It consists of a few fortran routines, that exchange variables with OASIS to mimic a wave or atmosphere model. For a more advanced coupling with actual atmospheric and wave models, you can go to the other sections of the coupling tutorial.

19.3.1. Get necessary files#

First create the configuration, here named BENGUELA_TOY:

mkdir BENGUELA_TOY

Get the useful files for CROCO compilation and settings:

cp ~/croco/croco/OCEAN/cppdefs.h .
cp ~/croco/croco/OCEAN/param.h .
cp ~/croco/croco/OCEAN/jobcomp .
cp ~/croco/croco/OCEAN/croco.in .

Get the TOY model:

cp -r ~/croco/croco/SCRIPTS/SCRIPTS_COUPLING/TOY_IN .

Get the useful input files:

wget "https://data-croco.ifremer.fr/CONFIGS_EXAMPLES/BENGUELA_LR_INPUT_FILES/CROCO_FILES.tar.gz"
tar -zxvf CROCO_FILES.tar.gz

wget "https://data-croco.ifremer.fr/CONFIGS_EXAMPLES/BENGUELA_LR_INPUT_FILES/TOY_FILES.tar.gz
tar -zxvf TOY_FILES.tar.gz

Get some useful scripts:

cp -r ~/croco/croco/SCRIPTS/SCRIPTS_COUPLING/SCRIPTS_TOOLBOX/OASIS_SCRIPTS .

19.3.2. Compile#

Compile OASIS

For running in coupled mode, you need to have OASIS compiled. For OASIS follow the instructions in the Compilation section of the coupling tutorial. We assume here that you have OASIS compiled in ~/oasis/compile_oasis3-mct

Compile CROCO

In cppdefs.h in the “REGIONAL (realistic) Configurations” section:

#define MPI
#define OW_COUPLING
#define MRL_WCI

Note

MPI is mandatory for coupling, even if the run is launched on 1 CPU. Indeed the MPI communicator is used to communicate with OASIS.

Edit all the usual paths, compilers, libraries in jobcomp, and notably OASIS path PRISM_ROOT_DIR:

# set OASIS-MCT (or OASIS3) directories if needed
#
PRISM_ROOT_DIR=~/oasis/compile_oasis3-mct

And compile:

./jobcomp >& compile_coupled.log

If the compilation is successfull you should have the CROCO executable croco.

Compile the TOY model

A script make_toy_compil.sh is provided. Check and eventually edit it (notably the line regarding the environment source ../myenv_mypath.sh, that should be adapt to point towards you environment file where the compilers and libraries are defined). You should also check/edit the Makefile.MACHINE for your machine.

cd TOY_IN
ln -sf Makefile.YOURMACHINE Makefile
./make_toy_compil.sh

If the compilation is successfull you should have the TOY executables toy_wav toy_atm toy_oce

19.3.3. Prepare the configuration files for a 3-day run#

Set up CROCO

Edit the croco.in:

time_stepping: NTIMES   dt[sec]  NDTFAST  NINFO
         72      3600      60      1

You can also change the frequency of outputs:

history: LDEFHIS, NWRT, NRPFHIS / filename
      T      24     0
   CROCO_FILES/croco_his.nc
averages: NTSAVG, NAVG, NRPFAVG / filename
      1      24     0
   CROCO_FILES/croco_avg.nc

And set to True the outputs for waves fields:

wave_history_fields: hrm  frq  action  k_xi  k_eta  eps_b  eps_d Erol eps_r
                        20*T
wave_average_fields: hrm  frq  action  k_xi  k_eta  eps_b  eps_d Erol eps_r
                        20*T
wci_history_fields:  SUP UST2D VST2D UST VST WST AKB AKW KVF CALP KAPS
                        20*T
wci_average_fields:  SUP UST2D VST2D UST VST WST AKB AKW KVF CALP KAPS
                        20*T

Set-up the TOY model

The toy model can send either fields from a model file (for instance generated by running a model in forced mode previously), or constant or sinusoidal fields. Check the readme in TOY_IN for more informations.

In every cases, you need to provide a grid to the toy model, here named grid_wav.nc. Here, the toy model will read and exchange variables specified in the TOYNAMELIST.nam from an input file, here named toy_wav.nc.

Get the chosen TOYNAMELIST.nam.wav.ow and rename it:

cp TOY_IN/TOYNAMELIST.nam.wav.ow TOYNAMELIST.nam.wav

You need to edit all the fields denoted into brackets: <...>, as well as the paths towards the input files in TOYNAMELIST.nam.wav:

&NAM_OASIS NB_TIME_STEPS=12,
            DELTA_T=21600,
            GRID_FILENAME='grid_wav.nc' /

&NAM_FCT_SEND CTYPE_FCT='FILES',
               CNAME_FILE='toy_wav.nc',
               VALUE=1 /

&NAM_RECV_FIELDS NB_RECV_FIELDS=3,
                  CRCVFIELDS(1)='TOY__SSH',
                  CRCVFIELDS(2)='TOY_UOCE',
                  CRCVFIELDS(3)='TOY_VOCE' /

&NAM_SEND_FIELDS NB_SEND_FIELDS=3,
                  CSNDFIELDS(1)='TOY_T0M1',
                  CSNDFIELDS(2)='TOY___HS',
                  CSNDFIELDS(3)='TOY__DIR' /

In the current example, the toy model is set to run 12 time steps of 21600s.

Also, prepare the toy input files. To do so you can use the script provided in OASIS_SCRIPTS/create_oasis_toy_files.sh:

./OASIS_SCRIPTS/create_oasis_toy_files.sh TOY_FILES/ww3_20050101_20050131.nc toy_wav.nc ww3 1,12

You should now have toy_wav.nc and grid_wav.nc files.

19.3.4. Prepare OASIS files#

Edit OASIS namelist, namcouple, which specifies which fields will be coupled, and at which frequency, etc.

A basis of namcouple files can be found in the croco/SCRIPTS/SCRIPTS_COUPLING/OASIS_IN directory. Copy the relevant namcouple:

cp ~/croco/croco/SCRIPTS/SCRIPTS_COUPLING/OASIS_IN/namcouple.base.ow.toywav namcouple

In this namcouple, you have to edit all the fields denoted into brackets <...>. Let’s browse the namcouple file. It has several sections:

  • A first section with general settings:

    • the number of fields to exchange (in our case 6: 3 from the ocean to

      the wave model (SSH, UOCE, VOCE), and 3 from the wave to the ocean model (HS, T0M1, DIR))

    • the number and names of model executables: here names must be of 6 characters exactly,

      so you need to move your model executable names to these 6-character names:

      mv croco crocox
cp TOY_IN/toy_wav toywav
    • the duration of the run in seconds: you need to change <runtime>

      to your actual duration (3days * 24h * 3600s): 259200

    • the debug level (see detailed explanation in the comments in the namcouple file)

  • A second section, with the informations on exchanged fields. A typical

    sub-section for one exchanged field looks like:

    CROCO_SSH TOY__SSH 1 <cpldt> 1 oce.nc EXPORTED
<ocenx> <oceny> <wavnx> <wavny> ocnt toyt LAG=<ocedt>
R  0  R  0
SCRIPR
DISTWGT LR SCALAR LATLON 1 4
    • line 1: field in sending model, field in target model, unused,

      coupling period, number of transformations (here 1 interpolation), restart file, field status

    • line 2: nb of pts for sending model grid (without halo) first dim,

      and second dim, for target grid first dim, and second dim, sending model grid name, target model grid name, lag = time step of sending model

    • line 3: sending model grid periodical (P) or regional (R), and nb of overlapping

      points, target model grid periodical (P) or regional (R), and number of overlapping points

    • line 4: list of transformations performed (here only grid interpolation SCRIPR

      keyword, see OASIS documentation for more informations)

    • line 5: parameters for each transformation (here distributed weight interpolation,

      see OASIS documentation for more informations)

    You need to edit all the fields denoted into brackets: <...>:

    <cpldt> -> 21600

    the coupling frequency in seconds for each field you will exchange

    <ocenx> -> 41

    the number of points in xi direction for CROCO (see param.h)

    <oceny> -> 42

    the number of points in eta direction for CROCO (see param.h)

    <wavnx> -> 41

    the number of points in x direction for the TOY model (see grid_wav.nc file)

    <wavny> -> 42

    the number of points in y direction for the TOY model (see grid_wav.nc file)

    <ocedt> -> 3600

    the CROCO time step

    <wavdt> -> 21600

    the TOY model time step (see TOYNAMELIST.nam)

Then, you need to prepare restart files for the coupler (in addition to model initial/restart files). To do so, two scripts are provided in the Coupling tools to start from calm conditions or previously existing files. Here, we will start from calm conditions. Note that this script uses the nco library, so that you should have it installed/loaded to run the script.

First, launch the creation of restart file for OASIS for the toy model:

  • first argument: grid name

  • second argument: restart file name

  • third argument: type of model

  • fourth argument: list of variables to initialize to 0

./OASIS_SCRIPTS/create_oasis_restart_from_calm_conditions.sh grid_wav.nc wav.nc toy "TOY_T0M1 TOY___HS TOY__DIR"

Then, do the same for the restart file for OASIS for CROCO model:

./OASIS_SCRIPTS/create_oasis_restart_from_calm_conditions.sh CROCO_FILES/croco_grd.nc oce.nc croco "CROCO_SSH CROCO_EOCE CROCO_NOCE"

You should now have in your configuration directory wav.nc and oce.nc, which are the OASIS restart files.

19.3.5. Run the models#

You are now ready to run CROCO in coupled mode with the toy model:

mpirun -np 2 toywav : -np 4 crocox

Or edit and launch a job to run the coupled models.

If the run went well, you should have in your configuration directory the following files:

grids.nc # grid file for OASIS (created automatically)
areas.nc # areas of cells used by some OASIS interpolations (created automatically)
masks.nc # masks file for OASIS (created automatically)
rmp_ocnt_to_toyt_DISTWGT.nc
rmp_toyt_to_ocnt_DISTWGT.nc
rmp_ocnu_to_toyt_DISTWGT.nc
rmp_ocnv_to_toyt_DISTWGT.nc # weight files for OASIS interpolation (one for each grid interpolation)
nout.000000 # OASIS log file
toywav.timers_0000 # OASIS log file for time statistics
crocox.timers_0000 # OASIS log file for time statistics
debug.root.01 # OASIS log file for the master processor for model #1 (toy in our case)
debug.root.02 # OASIS log file for the master processor for model #2 (CROCO in our case)
debug.notroot.01 # OASIS log file for other processors for model #1 (toy in our case)
debug.notroot.02 # OASIS log file for other processors for model #2 (CROCO in our case)
OUTPUT_TOY.txt # log file for the toy
croco.log # log file for CROCO (if you have define the LOGFILE cpp-key, otherwise croco log output is in CPL.o???????)

Note

If you have problems running the coupled model, you need to check:

  • The dimensions of the grids in all grid files (models grid files and OASIS grids and masks files)

  • The debug.root.0? files

  • The model log files (e.g. croco.log)

You can then check your new CROCO outputs in CROCO_FILES (you can see that you have the additional wave fields outputs (e.g. hrm) and you should see small differences of the surface currents for example if you do a difference of coupled and non-coupled CROCO outputs).

If you want then to use actual coupling with an atmospheric or wave model, and run production simulation in coupled mode, follow the next steps of the Coupling tutorial. It uses the full Coupling toolbox provided in croco_tools/Coupling_tools and croco/SCRIPTS/SCRIPTS_COUPLING. It will help you create a dedicated architecture for coupled runs, and it will provide you a set of scripts for running coupled simulation without managing all the files one by one. Basically, the Coupling toolbox will manage:

  • CROCO compilation if requested

  • Copying the model executables to your configuration directory

  • Getting models input files

  • Preparing OASIS restart files

  • Editing namelists, that is replacing automatically all the fields into

    brackets <...> in the different namelist files (for all models and for OASIS)

  • Launching the run

  • Putting output files in a dedicated output directory

  • Putting restart files for a future run in a dedicated restart directory

  • Eventually launching the next job if requested

Contents