Home > User’s guide > 1. How to install the software > 1.2. Export off-line version of SURFEX (from version 7_2)

1.2. Export off-line version of SURFEX (from version 7_2)

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.


Instructions to install surfex on a linux-PC and to run a 1d example.

  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 EXPORT_v7_2_0.gz and move it into $HOME/MYDIR/EXPORT_v7_2_0.tar.gz
    (You can also get the package from SVN directly).
  3. extract files from archive: tar zxvf EXPORT_v7_2_0.gz (or gunzip EXPORT_v7_2_0.gz and then tar xvf EXPORT_v7_2_0.tar) at this stage directory EXPORT_v7_2 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-V7-2-0-MPIAUTO-DEBUG
  5. special case of ubuntu linux distribution:
    if your linux distribution is ubuntu, edit the file: Makefile in src directory, comment lines: ARCHOOK="linuxgfortran", ARCHOOK="linuxmpif90" and ARCHOOK="ifort32" and uncomment lines #ARCHOOK="linuxgfortran_ubuntu", #ARCHOOK="linuxmpif90_ubuntu" and #ARCHOOK="ifort32_ubuntu" for the compilation of DR_HOOK library.
  6. 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.

  7. 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-V7-2-0-FORC-MPIAUTO-DEBUG.
    4. run make user and make installuser to create the scecific 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/EXPORT_v7_2"
      -- 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/EXPORT_v7.2/MY_RUN/FORCING/FORCING.nc
      ==============================================
      > input files moved to /home/lemoigne/surfex/EXPORT_v7_2/MY_RUN/KTEST/hapex
      ==============================================

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

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

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

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

  12. How to compile your own source for surfex
    1. choose a name for your own source directory in src, for example MYSRC. Cp the sources (from OFF_LINE or SURFEX directories) that you want to modify onto $SRC_SURFEX/src/MYSRC
    2. go to $SRC_SURFEX/src/MYSRC and make your modifications
    3. go to $SRC_SURFEX/src and launch successively export VER_USER=MYSRC, ./configure, . ../conf/profile_surfex-LXgfortran-SFX-V7-2-0-MYSRC-MPIAUTO-DEBUG, make user and make installuser. New executable files for MYSRC will be created in exe directory.