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 duration of the run in seconds: you need to change
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?
filesThe 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