CROCO-WW3-WRF
-------------

In your ${CHOME} repository you should have already filled in ``myenv_mypath.sh``.

To prepare the run you need to modify the files ``myjob.sh`` and ``mynamelist.sh``.

* In ``myjob.sh`` , you will have to fill in information about dates, job sequence:
  ::

      # Real job duration in sec (converted to MACHINE format in submit job)
      export TIMEJOB=1800

      #-------------------------------------------------------------------------------
      # Run date settings
      #-------------------------------------------------------------------------------
      # Your run can be divided into several jobs (e.g.: 1 year run into 12 jobs of 1 month)

      # Start date of the first Job
      export YEAR_BEGIN_JOB=2005
      export MONTH_BEGIN_JOB=1
      export DAY_BEGIN_JOB=1

      # Duration of each Job
      export JOB_DUR_MTH=1
      export JOB_DUR_DAY=0

      # How many jobs do you want to launch?
      export NBJOB=1           

      # Do we start from a restart?
      export RESTART_FLAG="FALSE"

  Along with the number of cpu you will use for each model
  ::
    
      # nb of CPUs for each model
      export NP_OCEX=2
      export NP_OCEY=2
      export NP_ATM=14
      export NP_WAV=4

* In ``mynamelist.sh``, first specify the run type, and the name of the experiment:
  ::

      # Run type (o/a/w, w.Afrc, oa, 2o1a, owa, owa.full...)
      #  - Will select the models to use reading letters o/w/a/toywav/toyoce/toyatm 
      #  - Will select the executables, and some options (see in the following sections)
      #  - In coupled mode corresponds to the suffix of the OASIS_IN/namcouple.base.$RUNtype to use
      export RUNtype=owa
      export MOD=`echo $RUNtype | cut -d . -f 1`
       
      #  Name of the experiment you are about to launch (max 30. CHAR)
      export CEXPER=BENGUELA_example_${RUNtype}

  Then, there is a section indicating where the run will be executed and where 
  the outputs and restarts will be stored:
  ::

      #-------------------------------------------------------------------------------
      # RUN_DIR
      #-------------------------------------------------------------------------------
      
      export EXEDIR_ROOT="$CWORK/rundir/${CEXPER}_execute"
      export OUTPUTDIR_ROOT="$CWORK/rundir/${CEXPER}_outputs"
      export RESTDIR_ROOT="$CWORK/rundir/${CEXPER}_restarts"
      
      export  JOBDIR_ROOT=${CHOME}/jobs_${CEXPER}

  Then, there are sections for the different components.

  For the coupler settings:
  ::

      #-------------------------------------------------------------------------------
      # CPL
      #-------------------------------------------------------------------------------
      
      # Namelist
      #---------
      # Note: namelist example files are provided in OASIS_IN/
      # if you want to use a pre-built weight file for grid interpolations, point to 
      # e.g. namcouple.base.oa.smtho2a 
      export namcouplename=namcouple.base.${RUNtype}
      
      # Coupling frequency
      #-------------------
      export CPL_FREQ=21600
      
      # Restart files for OASIS
      #------------------------
      # If TRUE: create OASIS restart files from pre-existing atm/oce/wav outputs.
      # If FALSE: create OASIS restart files from calm conditions (need to read at least the grid for each model)
      export CPL_restart="FALSE"
      export oce_rst_file="${OCE_FILES_DIR}/croco_grd.nc"
      export oce_rst_timeind=-1 # time index (-1 is last) in the file to extract as restart
      export atm_rst_file="${ATM_FILES_DIR}/wrfinput_dXX_2005_01_01_00" # the domain dXX will be automatically replaced
      export atm_rst_timeind=-1 # time index (-1 is last) in the file to extract as restart
      export wav_rst_file="${WAV_FILES_DIR}/ww3.200501.nc"
      export wav_rst_timeind=-1 # time index (-1 is last) in the file to extract as restart
      
  You should check the coupling frequency, the restart flag and path towards 
  model files to use to create oasis restart files.

  For CROCO settings, first indicate if you request CROCO compilation:
  ::

      #-------------------------------------------------------------------------------
      # OCE
      #-------------------------------------------------------------------------------

      # Where to find or put the croco execuatble
      export OCE_EXE_DIR=${CHOME}/CROCO_IN
      
      # Online Compilation
      #-------------------
      #!!!!!!! IMPORTANT NOTE !!!!!!!
      # If activated, creates croco executable depending on this namelist. 
      #   - In param.h it modifies the grid size, the number of procs in x and y direction with those given in myjob.sh
      #   - In cppdefs.h it modifies the following options with informations given below
      #       MPI, OA_COUPLING, OW_COUPLING, MRL_WCI, 
      #       XIOS, LOGFILE, MPI_NOLAND,
      #       AGRIF, AGRIF_2WAY, 
      #       BULK_FLUX, ONLINE, AROME, ARPEGE, ERA_ECMWF
      #       FRC_BRY, CLIMATOLOGY
      #       TIDES, PSOURCE, PSOURCE_NCFILE, PSOURCE_NCFILE_TS
      # Other changes of parameterizations, numerical schemes, etc should be made "by hand" in CROCO_IN/cppdefs.h.base
      #!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
      export ONLINE_COMP=1

  Then, edit model time steps:
  ::

      # Time steps
      #-----------
      export DT_OCE=3600
      export NDTFAST=60

  Then several options for zooms, wave coupling are provided.
  They are generally automatically set-up depending on the ``RUNtype`` defined 
  at the beginning.

  Then, edit the options regarding the forcing files:
  ::

      # Forcings
      #---------
      export ini_ext='ini_SODA' # ini extension file (ini_SODA,...)
      export bdy_ext='bry_SODA' # bry extension file (clm_SODA,bry_SODA,...)
      
      # flag for surface forcing should be true except in the case of atm coupling
      if [[ $MOD =~ .*a.* ]] ; then
          export surfrc_flag="FALSE"
      else
          export surfrc_flag="TRUE"
      fi
      export interponline=0 # switch (1=on, 0=off) for online surface interpolation. Only works with MONTHLY input files!
      export frc_ext='blk_ERA5' # surface forcing extension(blk_ERA5, frc_ERA5,...). If interponline=1 precise the type (ERA_ECMWF or AROME,  [CFSR by default], names as cppkey name in croco)
      
      export tide_flag="FALSE" # the forcing extension must be blk_??? otherwise tide forcing overwrites it 
      export river_flag="FALSE"

  Finally edit CROCO output settings:
  ::

      # Output settings
      #----------------
      #!!! WARNING: when XIOS is activated the following values (for the model) are not taken into account
      export oce_his_sec=86400     # history output interval (in number of second) 
      export oce_avg_sec=86400     # average output interval (in number of second) 

  Then continue with the atmospheric model section:
  ::

      #-------------------------------------------------------------------------------
      # ATM
      #-------------------------------------------------------------------------------
      
      # Where to find the atm exectuable
      if [[ $RUNtype =~ .*a.* && ( $RUNtype =~ .*o.* || $RUNtype =~ .*w.* ) ]] ; then
          export ATM_EXE_DIR=${ATM}/exe_coupled
      else
          export ATM_EXE_DIR=${ATM}/exe_uncoupled
      fi

  First the paths for the executable are defined.
  Those are generally set-up with the ``RUNtype`` but can be changed if necessary.
  
  Then choose the namelist file, and namelist options: model time step, forcing 
  files informations, 
  Cd formulation (coupling with waves requires isftcflx=5), domains informations. 

  .. note:: 
        Other changes in the WRF namelist should be made "by hand" in the 
        ``WRF_IN/namelist.input.base.complete``. 
        Only settings into  <...> in the namelist are automatically changed by 
        the scripts 

  ::
      
      # Namelist
      #---------
      #!!!!!!! IMPORTANT NOTE !!!!!!!
      # Changes of parameterizations, numerical schemes, etc in atmnamelist
      # should be made "by hand" in the WRF_IN/namelist.input.base.complete file
      # Only settings into <...> in WRF_IN/namelist.input.base.complete are automatically
      # filled in by the present mynamelist settings
      #!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
      export atmnamelist=namelist.input.base.complete
      
      # Time steps
      #-----------
      export DT_ATM=150
      
      # Boundaries 
      #-----------
      export interval_seconds=21600 # interval ( in sec ) of the lateral input
      export auxinput4_interval=360 # interval ( in min ) of bottom input
      export nbmetsoil=4
      export nbmetlevel=38
      
      # Physics
      #--------
       # Cd formulation (default = 0, wave cpl needs = 5)
      if [[ $RUNtype =~ .*aw.* || $RUNtype =~ .*owa.* ]] ; then
          export isftcflx=5
      else
          export isftcflx=1
      fi
      
      # Domains
      #--------
      export NB_dom=1 # Number of coupled domains
      export wrfcpldom='d01' # which WRF domain to couple
      export nestfeedback="TRUE" # 1 way (FALSE) or 2 Way (TRUE) nesting
      export onlinecplmask="TRUE" # Erase existing CPLMASK and build default mask (depending on the nb of atm and oce domains)

  Then a section when using moving nest is available. It is important to note 
  that to use the moving nest WRF has to be compiled with the moving nest option. 
  In addition, in coupled mode, the moving nest can be used, but only the parent 
  static model can be coupled through OASIS.
  A dedicated ``Registry.EM`` is available in ``WRF_IN`` to compile WRF with 
  moving nest + coupling so that the moving nest receive surface updates from 
  the parent static domain, that is coupled to the ocean or wave model.  
  The following section is used only if the moving nest is activated 
  ``ATM_CASE="MOVING_NEST"``. In other case keep ``ATM_CASE="DEFAULT"``, 
  and ignore the rest of the section. 
  ::
 
      # Moving nest 
      #------------
      export ATM_CASE="DEFAULT"  # no moving nest: DEFAULT or with: MOVING_NEST
      # if ATM_CASE=DEFAULT, the following is not used
      export num_mv_nest=1 # number of moving nests
      # if several nest, the following variables need to have the format "1st_nest 2nd_nest"
      export ref_coef="3" # refinement coef for nest
      export ew_size="283" # nest size in east-west dim ([multiple of ref_coef] + 1)
      export ns_size="295" # nest size in north-south dim ([multiple of ref_coef] + 1)
      export i_prt_strt="580" # where nest is starting in parent's grid x-dim 
      export j_prt_strt="59" # where nest is starting in parent's grid y-dim
      # Tracking parameters
      export vortex_interval=5 # When to update vortex position
      export max_vortex_speed=40 # Used to compute the search radius for the new vortex center position
      export corral_dist=8 # The closest distance between child and parend boundary (in parent grid cell)
      export track_level=50000 # The pressure level (in Pa) where the vortex is tracked
      export time_to_move=0 # The time (in minutes) until the nest is moved (at the beginning)
     
  Then a section when using nudging (assimilation) is available. If not using 
  nudging, ignore this section. 
  ::
 
      # Nudging (assimilation) options
      #-------------------------------
      export switch_fdda=0 # To activate fdda nudging
      export nudgedom="1" # select which kind of nudging you want (1=grid-nudging, 2=spectral nudging) for each domain. Example for spectral nudging over parent only "2 0"
      export nudge_coef="0.0003" # nudge coef. Need to be the same size than nudge
      export nudge_interval_m="360" # time interval (in min) between analysis times 
      export nudge_end_h="144" # time (in hours) to stop nudging after start of forecast

  Finally, set the ouptut settings:
  ::
      
      # Output settings
      #----------------
      #!!! WARNING: when XIOS is activated the following values (for the model) are not taken into account
      export atm_his_h=6                          # output interval (h)
      export atm_his_frames=1000 # $((31*24))     # nb of outputs per file
      export atm_diag_int_m=$((${atm_his_h}*60))  # diag output interval (m)
      export atm_diag_frames=1000                 # nb of diag outputs per file
      # file for specifying different than default output variables: OPTIONAL, leave empty if not used
      export atm_iofields='myoutfields.txt'

  Then continue with the wave model section:
  ::

      #-------------------------------------------------------------------------------
      # WAV
      #-------------------------------------------------------------------------------
      
      # Where to find the wav executable
      if [[ $RUNtype =~ .*owa.* ]] ; then
          export WAV_EXE_DIR=${WAV}/exe_owa
      elif [[ $RUNtype =~ .*ow.* ]] ; then
          export WAV_EXE_DIR=${WAV}/exe_ow
      elif [[ $RUNtype =~ .*aw.* ]] ; then
          export WAV_EXE_DIR=${WAV}/exe_aw
      else
          export WAV_EXE_DIR=${WAV}/exe_frc
      fi
      
      # Namelist
      #---------
      # Chosing the ww3_shel.inp.base.SHELL_EXT (see options in WW3_IN)
      if [[ $RUNtype =~ .*toy.* ]] ; then
          export SHELL_EXT=$MOD
      else
          export SHELL_EXT=$RUNtype
      fi

  First the paths for the executable are defined, and the ww3_shel namelist to use is defined. 
  Those are generally set-up with the ``RUNtupe`` but can be changed if necessary. 

  Then edit the ww3 time steps and grid settings (these will be updated in ww3_grid.inp):
  ::
      
      # Time steps
      #-----------
      export DT_WAV=3600     # TMAX = 3*TCFL
      export DT_WW_PRO=1200  # TCFL = 0.8 x dx/(g/fmin4pi) with fmin=0.0373 => 3-4 % of dx
      export DT_WW_REF=1800  # TMAX / 2
      export DT_WW_SRC=10    # TSRC = usually 10s  (could be between 5s and 60s)
      
      # Grid size
      #----------
      export wavnx=41 ; export wavny=42
      
      # Parameter
      #---------- 
      export hmin=75; # e.g. minimum water depth in CROCO (will be used to delimit coastline in WW3)
      
  Then, choose the forcing to use for ww3:
  ::

      # Forcing files
      #--------------
      # forcin: forcing file(s) PREFIX list (input file are supposed to be in the form: PREFIX_Y????M??.nc)
      # forcww3: name of ww3_prnc.inp extension, e.g current or wind/era5, see in WW3_IN directory
      if [[ $RUNtype =~ .*owa.* ]]; then
          export forcin=()
          export forcww3=()
      elif [[ $RUNtype =~ .*Afrc.* || $RUNtype =~ .*ow.* ]] ; then
          export forcin=(ERA5_wind)
          export forcww3=(wind.era5)
      elif [[ $RUNtype =~ .*Ofrc.* ]] ; then
          export forcin=(CROCO_current CROCO_level)
          export forcww3=(current level)
      elif [[ $RUNtype =~ .*frc.* ]] ; then
          export forcin=(ERA5_wind CROCO_current CROCO_level)
          export forcww3=(wind.era5 current level)
      fi
      
  As well as the boundary data (can be left empty):
  ::

      # Boundary files
      #---------------
      # prefix for boundary files (leave empty is none), there are supposed to be in WAV_FILES_DIR
      export bouncin=
  
  Finally, set output settings:
  ::
    
      # Output settings
      #----------------
      export wav_int=21600  # output interval (s)
      export wav_pnt=0  # point output interval. Put 0 if no point output
      export point_output_list=${WAV_FILES_DIR}/my_point_output_test.txt # file where to find list of point (format: lon lat name) to output spectrum
      export wav_trck=0     # track output interval. Put 0 if no track output  
      export flagout="TRUE" # Keep (TRUE) or not (FALSE) the ww3 output binary files (e.g. out_grd.ww3)

* Now that you have completed the necessary files, you are ready to run your 
  simulation. To do so, simply do
  ::

      ./submitjob.sh