18.3. Simple CROCO-TOY coupled example

For this first step towards coupling, we will just use the BENGUELA_LR configuration and add coupling to 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.

  1. First copy the BENGUELA_LR configuration that you have already run in forced mode:

    cp -r ~/CONFIGS/BENGUELA_LR ~/CONFIGS/BENGUELA_LR_cpl
    
  2. For running in coupled mode, you first need to compile OASIS, and then re-compile CROCO in coupled mode, and compile the TOY model. Follow the instructions in the Compilation section of the coupling tutorial.

  3. 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 will need to provide a grid to the toy model, here named grid_wav.nc. The toy model will read and exchange variables specified in the TOYNAMELIST.nam from an input file, here named toy_wav.nc. First edit the TOYNAMELIST.nam file: exchanged field names and number of time steps In the current example, the toy model is set to run 72 time steps of 3600s.

    For this tutorial, we will thus use the toy_wav.nc and grid_wav.nc files provided. You should have the following executable, namelist, and input files to use the TOY model:

    • toy_model

    • TOYNAMELIST.nam

    • grid_wav.nc

    • toy_wav.nc

  4. Set up CROCO:

    Edit the croco.in to run over the same duration:

    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
    
  5. Edit OASIS namelist, namcouple, to specify which fields will be coupled. 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 ~/CONFIGS/BENGUELA_LR_cpl/namcouple
    

    In this namcouple, you will 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 7: 3 from the ocean to the wave model (SSH, UOCE, VOCE), and 4 from the wave to the ocean model (HS, T0M1, SDIR, CDIR))

      • 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
      mv toy_model toyexe
      
      • 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:

      SRMSSHV0 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>

    the coupling frequency in seconds for each field you will exchange

    <ocenx>

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

    <oceny>

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

    <wavnx>

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

    <wavny>

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

    <ocedt>

    the CROCO time step

    <wavdt>

    the TOY model time step (see TOYNAMELIST.nam)

  6. Finally, 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. In our case 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:

    # Copy the useful script
    cp ~/croco/croco/SCRIPTS/SCRIPTS_COUPLING/SCRIPTS_TOOLBOX/ROUTINES/OASIS_SCRIPTS/create_oasis_restart_from_calm_conditions.sh ~/CONFIGS/BENGUELA_LR_cpl/.
    
    # 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
    ./create_oasis_restart_from_calm_conditions.sh grid_wav.nc wav.nc toy "TOY_T0M1 TOY___HS TOY_CDIR TOY_SDIR"
    
    # launch the creation of restart file for OASIS for CROCO model:
    ./create_oasis_restart_from_calm_conditions.sh CROCO_FILES/croco_grd.nc oce.nc croco "SRMSSHV0 SRMVOCE0 SRMUOCE0"
    

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

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

    mpirun -np 2 toyexe : -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
    toyexe.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???????)
    CPL.o??????? # log file for the batch job
    

    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 if you can see small differences of the surface currents for example if you do a difference of coupled and non-coupled CROCO outputs).

  8. 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