9. Running the model#

To run the model, you need to have completed pre-processing (for realistic cases) and compilation phases. In your working directory you need to have:

For an idealized simulation (e.g. test cases):

croco # model executable
croco.in # namelist file (available for each test case croco source directory: TEST_CASES)

For a realistic simulation:

croco # model executable
croco.in # namelist file (available in croco source directory: OCEAN)

# in CROCO_FILES:
croco_grd.nc # grid file
croco_bdy.nc or croco_clm.nc # lateral boundary condition file
croco_frc.nc or croco_blk.nc # surface forcing file
croco_ini.nc # initial condition file

9.1. Edit croco.in#

You first need to set all time, I/O, and different parameters in the CROCO namelist file: croco.in.

CROCO namelist file croco.in is set by default for the BENGUELA_LR case. So you should have nothing to change.

The detail of all croco.in sections can be found here: croco.in

However you can check some settings:

Time stepping:
```
time_stepping: NTIMES   dt[sec]  NDTFAST  NINFO
               720      3600      60      1
```
NTIMES: number of time steps dt[sec]: baroclinic time step NDTFAST: number of barotropic time steps in one baroclinic time step)

Note

Your time steps should be set according to the stability constraints:
- Barotropic mode
  
  \[\frac{\Delta t}{\Delta x} \sqrt{ g H } \le 0.89\]
  
  Note that considering an Arakawa C-grid divides the theoretical stability limit by a factor of 2.
  
  So for instance for a maximum depth of 5000 m and a resolution of 30 km:
  
  \[ \begin{align}\begin{aligned}\Delta t \le \frac{0.89 \Delta x}{2 . \sqrt{g H} }\\\Delta t \le 60 s\end{aligned}\end{align} \]
- 3D advection
  
  With 60 barotropic time steps in one baroclinic time step, this results in a baroclinic time step of:
  
  \[\Delta t \le 3600 s\]
  
  You can check that this time step does not violate your CFL condition for your advection scheme. Typical CFL values for with Croco time-stepping algorithm are
  
  Advection scheme
  
  Max Courant number
  
  C2
  
  1.587
  
  UP3
  
  0.871
  
  SPLINES
  
  0.916
  
  C4
  
  1.15
  
  UP5
  
  0.89
  
  C6
  
  1.00
  
  In the present BENGUELA_LR case, we use UP3:
  
  \[ \begin{align}\begin{aligned}\frac{\Delta t}{\Delta x} . V_{max} \le 0.871\\V_{max} \le 0.871 \frac{30000}{3600}\\V_{max} \le 7.25 m/s\end{aligned}\end{align} \]
  
  which is a very large allowed maximum horizontal velocity.

Advection scheme	Max Courant number
C2	1.587
UP3	0.871
SPLINES	0.916
C4	1.15
UP5	0.89
C6	1.00

Vertical coordinate parameters:

Warning

These parameters should be set accordingly to pre-processing.

S-coord: THETA_S,   THETA_B,    Hc (m)
         7.0d0     2.0d0      200.0d0

By default no reference time is used, and time is referred to the beginning of the simulation only using NTIMES. If you want to define the start and stop of the model by dates, you first need to edit cppdefs.h, define this key, and recompile the model:
```
#define USE_CALENDAR
```
Then edit croco.in input file:
```
start_date:
2000-01-01 00:00:00

end_date:
2000-02-01 00:00:00

output_time_steps: DT_HIS(H), DT_AVG(H), DT_RST(H)
                    1.0       6       48
```
Warning

this replaces NTIMES definition which is implicitly calculated.

As we are running a climatological simulation, this is not very relevant (as the model is cycled on a idealized 360-days period). This is more useful for interannual simulations.

Check the paths to your input files (they should be properly set by default):

grid:  filename
    CROCO_FILES/croco_grd.nc
forcing: filename
    CROCO_FILES/croco_frc.nc
bulk_forcing: filename
    CROCO_FILES/croco_blk.nc
climatology: filename
    CROCO_FILES/croco_clm.nc
boundary: filename
    CROCO_FILES/croco_bry.nc

Indicate if you are starting from an initial or restart file and its path:
```
initial: NRREC  filename
          1
    CROCO_FILES/croco_ini.nc
```
NRREC: Switch to indicate start or re-start from a previous solution. NRREC is the time index of the initial or restart NetCDF file assigned for initialization.
- If NRREC=1 you are starting from an initial file.
- If NRREC=X with X a positive number, you are starting from the Xth time record in the restart file.
- If NRREC is negative (say NRREC=-1), the model will start from the most recent time record. That is, the initialization record is assigned internally.
Indicate the frequency of restart files, and their paths:
```
restart:          NRST, NRPFRST / filename
                   720    -1
    CROCO_FILES/croco_rst.nc
```
NRST: frequency of restarts in number of time steps

NRPFRST=-1: overwrite old restarts at each restart time,

NRPFRST=0: store all restarts in one file,

NRPFRST=X with X a positive number: store X restarts in one file
Indicate if you want history (e.g. instantaneous) and/or averaged output files, their output frequency, and path:
```
history: LDEFHIS, NWRT, NRPFHIS / filename
            T      72     0
    CROCO_FILES/croco_his.nc
averages: NTSAVG, NAVG, NRPFAVG / filename
            1      72     0
    CROCO_FILES/croco_avg.nc
```
LDEFHIS: T or F: do you want history files

NWRT: frequency of output in number of time steps

NRPFHIS is the way outputs will be stored:
- NRPFHIS=-1: overwrite old history outputs at each output time,
- NRPFHIS=0: store all history outputs in one file,
- NRPFHIS=X with X a positive number: store X history outputs in one file
NTSAVG: starting time step for the accumulation of output time-averaged data

NAVG: frequency of averaged outputs in number of time steps

NRPFAVG: same as for history files

Choose which variables to output (T or F flag):

primary_history_fields: zeta UBAR VBAR  U  V   wrtT(1:NT)
                          T    T   T   T  T    30*T
auxiliary_history_fields:   rho Omega  W  Akv  Akt  Aks Visc3d Diff3d  HBL HBBL Bostr Wstr Ustr Vstr Shfl Swfl rsw rlw lat sen  HEL
                             F   F     T   F    T    F    F     F       T   T    T     T    T    T    T    T   10*T
gls_history_fields:   TKE  GLS  Lscale
                       T     T    T

primary_averages: zeta UBAR VBAR  U  V   wrtT(1:NT)
                   T    T    T    T  T   30*T
auxiliary_averages: rho Omega  W  Akv  Akt  Aks  Visc3d Diff3d HBL HBBL Bostr Wstr Ustr Vstr Shfl Swfl rsw rlw lat sen HEL
                     F   T     T   F    T    F     F     F      T   T    T     T   T    T     T    T   10*T
gls_averages:   TKE  GLS  Lscale
                 T     T    T

Other parameters in croco.in file will be explored in the next tutorials.

9.2. Run the model#

To run the BENGUELA_LR simulation in serial mode (1 CPU), just do:
```
./croco croco.in
```
Where croco is your executable compiled with all your chosen options and parameterizations and croco.in is your namelist file for croco.
To run the BENGUELA_LR simulation in parallel (if you have compiled CROCO with #define MPI):
- By using classical launch command (on individual computers):
```
mpirun -np NPROCS croco croco.in
```
where NPROCS is the number of CPUs you want to allocate. mpirun -np NPROCS is a typical mpi command, but it may be adjusted to your MPI compiler and machine settings.
- OR by using a batch script (e.g. PBS) to launch the model (in clusters), examples are provided:
```
cp ~/croco/croco/SCRIPTS/example_job_croco_mpi.pbs .
```
  Edit example_job_croco_mpi.pbs according to your MPI settings in param.h and to your machine MPI command, and launch the run:
```
qsub example_job_croco_mpi.pbs
```
  Warning
  
  NPROCS needs to be consistent to what you indicated in param.h during compilation

If your run is successful you should obtain the following files:

croco_rst.nc # restart file
croco_his.nc # instantaneous output file
croco_avg.nc # averaged output file
croco.log    #if you have defined the LOGFILE key in cppdefs.h : # define LOGFILE

croco.log contains the standard output of your run (informations on your settings, input files, evolution of the time stepping). croco.log is also useful when your run blows up to search for the error.

You can explore your model outputs (croco_his.nc, croco_avg.nc) using different frameworks (ncview, ferret, etc). In the croco_tools, a matlab interface is offered to explore your data: croco_gui, as well as a Python interface croco_pyvisu. These are explored in other tutorials.

Have a quick look at the results:
```
ncview croco_his.nc
```
Test: some questions:
- What is the size of the grid (see param.h)?
- What is the spatial resolution in both horizontal directions?
- How many vertical levels do you have?
- How are the vertical levels distributed (look for the cpp key NEW_SCOORD)?
- What are the initial dynamical conditions (see both cppdefs.h and croco.in)?
- What do the air-sea exchanges look like?

9.3. Tips in case of BLOW UP or ERROR#

Check your time steps
Eventually increase NDTFAST and/or decrease the baroclinic time step
Check the location of your boundaries (in particular if your blow up point is located close to them): it should not be placed on a too strong topographic gradient, or coastline particular shape (it is usually better to have a boundary normally crossing the coastline)
Check the thickness and value of the sponge

Running the model

Contents

9. Running the model#

9.1. Edit croco.in#

9.2. Run the model#

9.3. Tips in case of BLOW UP or ERROR#