1.2. Export off-line version of SURFEX

From version 7_2 of Surfex, the configuration and installation environment of off-line Surfex is adapted to this from Meso-nh.
This leads to changes in configuration and installation processes.

First important recommandation: before to run an experiment (pgd, prep or offline), you need to type

export OMP_NUM_THREADS=1


in the terminal where you will run the experiment. It’s even better to put this line in your file $HOME/.bash_profile so that it’s executed each time you open a new terminal.

– INSTALLATION / COMPILATION:
Instructions to install surfex (V8_1 for example) on a linux-PC

  1. Select a directory where installation has to be done: for example $HOME or $HOME/MYDIR, where MYDIR is an existing directory (if not, it has to be created by the user). From now on, it is supposed that the user has defined a MYDIR directory.
    Caution: the directory and all parent directories MUST NOT contain dots (.) in their names.

  2. Download the package and move it into $HOME/MYDIR/open_surfex_v8_1.tar.gz
    (You can also get the package from GIT directly).

  3. Extract files from archive: tar -zxvf open_surfex_v8_1.tar.gz (or gunzip open_surfex_v8_1.tar.gz and then tar xvf open_surfex_v8_1.tar.gz). A directory open_SURFEX_V8_1/ is created in MYDIR and contains all software peaces.

  4. Initialize environment variables needed for surfex:
    Go into src/ directory and run
    ./configure

    Then, execute the profile file for this master version of surfex
    . ../conf/profile_surfex-LXgfortran-SFX-V8-1-1-MPIAUTO-O2-X0

    Caution: the name of your profile can be different! This is just an example, with the default options of compilation. When configure is executed, a profile is printed on the screen. You have to load this profile. For instance, if you choose to compile without MPI (VER_MPI=NOMPI) and with XIOS (VER_XIOS=2) the created profile will be profile_surfex-LXgfortran-SFX-V8-1-1-NOMPI-O2-X2
  1. compile the master version of the code:
    in the src/ directory, run make

    and then make installmaster
    Master executables are created in directory exe.
    If everything goes well until this step, then master surfex has been successfully installed on you computer.

– INSTALLATION OF A PRE-DEFINED EXPERIMENT:

  1. How to install a pre-defined experiment:
    1. in another terminal, in src directory, do export VER_USER=FORC.
    2. run ./configure.
    3. execute the profile file corresponding to this user version of surfex:
      . ../conf/profile_surfex-LXgfortran-SFX-V8-1-1-FORC-MPIAUTO-O2-X0.
    4. run make user and make installuser to create the specific executables in directory exe.
    5. go into MY_RUN/FORCING directory and run prepare_forcing.bash with a name of experiment as argument:
      for example "./prepare_forcing.bash hapex"
      a namelist MY_PARAM.nam will open (vi editor), simply quit (use command :q)
      Some information will then be written on the screen and should look like:
      $SRC_SURFEX="/home/lemoigne/surfex/open_SURFEX_V8_1"
      -- namelist NAM_MY_PARAM read
      > ==========================================
      > PREP_INPUT_EXPERIMENT: YEXPER = HAPEX
      > PREP_INPUT_EXPERIMENT: INI = 1
      > PREP_INPUT_EXPERIMENT: INPTS = 17521
      > PREP_INPUT_EXPERIMENT: JNPTS = 17521
      > PREP_INPUT_EXPERIMENT: ZTSTEPFRC = 1800.
      > PREP_INPUT_EXPERIMENT: YFORCING_FILETYPE = NETCDF
      > ===========================================
      YFILE_FORCIN=../DATA/hapex/HAPEX.DAT.30
      -rw-r--r-- 1 lemoigne mc2 1543644 jui 22 16:51 /home/lemoigne/surfex/open_SURFEX_V8_1/MY_RUN/FORCING/FORCING.nc
      ==============================================
      > input files moved to /home/lemoigne/surfex/open_SURFEX_V8_1/MY_RUN/KTEST/hapex
      ==============================================

  2. once the installation is done, go to $SRC_SURFEX/MY_RUN/KTEST/hapex directory and launch successively:
    1. pgd.exe
    2. prep.exe
    3. offline.exe

  3. to view output 1d, you can use your favorite graphic software (e.g. xmgrace, which is very easy to use for ASCII outputs)

  4. How to rerun a pre-defined experiment with new inputs:

    1. you can define new surface characteristics by modifying file $SRC_SURFEX/MY_RUN/KTEST/hapex/OPTIONS.nam and then run pgd.exe, prep.exe and offline.exe
    2. you can define new initial values for state variables by modifying file $SRC_SURFEX/MY_RUN/KTEST/hapex/OPTIONS.nam and then run prep.exe and offline.exe
    3. you can modify the forcing characteristics
      1. you can rerun $SRC_SURFEX/MY_RUN/FORCING/prepapre_forcing.bash and modify namelist MY_PARAM to select the number of time steps you want to treat (parameter NUMBER_OF_TIME_STEPS_FINAL) the format of the input forcing files (parameter YFORCING_FILETYPE)
      2. then go to $SRC_SURFEX/MY_RUN/KTEST/hapex and rerun pgd.exe, prep.exe and offline.exe

  5. How to create a new experiment:
    1. you need to modify $SRC_SURFEX/src/FORC/my_forcing.f90 to introduce the call to the new program that is going to read your dataset
    2. you need to create a new subroutine named $SRC_SURFEX/src/FORC/my_forc_xxxx.f90 that corresponds to experiment xxxx
    3. then run successively:
      1. in src directory, make user (verify that $VER_USER=FORC and that corresponding profile file has been executed).
      2. in MY_RUN/FORCING directory, prepare_forcing.bash (to create input files related to your experiment)
      3. then go to $SRC_SURFEX/MY_RUN/KTEST/xxxx and run pgd.exe, prep.exe and offline.exe

– COMPILE YOUR OWN SOURCE FOR SURFEX:

  1. choose a name for your own source directory in src/, for example MYSRC.
  2. copy the sources (from OFFLINE or SURFEX directories) that you want to modify onto $SRC_SURFEX/src/MYSRC/
  3. go to $SRC_SURFEX/src/MYSRC and make your modifications
  4. go to $SRC_SURFEX/src/ and launch successively

    export VER_USER=MYSRC

    ./configure

    . ../conf/profile_surfex-LXgfortran-SFX-V8-1-1-MYSRC-MPIAUTO-O2-X0

    make user

    make installuser

    New executable files for MYSRC will be created in exe directory.

Also in this section