Skip to content

Getting Started with SURF-SHYFEM

This guide provides instructions for downloading, installing, and running SURF-SHYFEM in a virtual machine (VM) environment. It complements the video tutorials available on the SURF website and the instructions provided in the SURF-NEMO manual.

Get the Surf Virtual Machine

  1. Download VirtalBox following the SURF-NEMO manual
  2. Download the SURF VM from the SURF webpage.

  3. Refer to the SURF-NEMO manual to correctly setup the VM. Some additional notes:

    • The login username and passwords are surf and surf2020 respectively.
    • If you use a AZERTY keyboard, you should type the password as if you were using a QWERTY keyboard (i.e. don't press shift when entering the numbers). You'll be able to switch to AZERTY once inside the VM, from the system settings.
    • To run the Madagascar test case, you must resize the virtual machine. To do that: shut down the virtual machine, go to the folder containing the .vdi file and type in a Terminal:
      VBoxManage modifyhd surf_scratch.vdi --resize 60000
      Then start the virtual machine, go to administration → GParted → devsdb and resize.
    • You may need to modify the VM storage unit. By default, it points to /Users/Franz/VirtualBox VMs/Surf/VBoxGuestAdditions.iso. You should redirect it to the VBoxGuestAdditions.iso disk image available from your VirtualBox installation (e.g. usr/share/VirtualBox/VBoxGuestAdditions.iso for linux systems).

Installing SHYFEM

  1. Start the virtual machine.

  2. To download surf_dataset and surf_shyfem zip files, open a Terminal and type:

    cd /scratch/surf/surf_install/releases/
    echo "Downloading SURF-Datasets..."
    echo "Downloading SURF-SHYFEM..."

  3. From the same location, install the datasets and SHYFEM: surf_dataset_1.01 surf_shyfem
    These commands install the surf static datasets and SURF-Shyfem under /scratch/surf/surf_datasets/ and /scratch/surf/surf_shyfem/, respectively.

  4. Once done, you must grant execution permissions to script files:

    chmod -R a+x /scratch/surf/surf_shyfem/surf_shyfem_1.00/

Run the Surf-SHYFEM Testcase (Madagascar coastal area)

  1. Download the testcase input datasets from the SURF webpage:

    cd /scratch/surf/indata_offline/
    tar -zxvf madagascar_20210402_indata.tar.gz

  2. Create the experiment directory and move the data in it:

    mkdir -p /scratch/surf/experiments/mdg_etoofs/data/indata/
    cp -r /scratch/surf/indata_offline/madagascar_20210402_indata/madagascar_20210402/* /scratch/surf/experiments/mdg_etoofs/data/indata/

  3. Activate virtual environment:

    conda activate surf_shyfem

  4. You're all set.

Unstructured grid generation

The first step to the execution of a downscaling experiment is the creation of the unstructured grid in the downscaled domain (please refer to the video tutorials for a comprehensive introduction on the subject).

  1. Generate the grid with the embedded tool (based on Gmsh):

    cd /scratch/surf/surf_shyfem/current/grid-tool/
    python @ci osm @cb 49.4682 -12.0557 49.3572 -12.1062 49.2196 -12.1272 49.1467 -12.3619 49.3724 -12.4503 49.5137 -12.3577 @ob 49.5652,-11.9743 49.7047,-12.1988

    • The commas are only in the @ob section. The syntax is:
       python @ci osm @cb lon1 lat1 lon2 lat2 ... @ob lon1,lat1 lon2,lat2 ...
    • Coordinates must be written in decimal notation
    • Both @cb and @ob coordinates must be in an anticlockwise sense
  2. Follow on-screen prompts to set the grid parameters (for their description please refer to the video tutorials):

    Insert L_open: 0.05
    Insert L_coast: 0.01
    Insert Delta_open: 0.015
    Insert Delta_coast: 0.002
    You can play a bit with the grid parameters and bounding coordinates, but at first we advise to stick with these values to get the first experiment done.

  3. Move the grid to the correct directory and rename it:

    mkdir /scratch/madagascar
    cp /scratch/surf/surf_shyfem/current/grid-tool/output/* /scratch/madagascar
    mv /scratch/madagascar/new.grd /scratch/madagascar/madagascar_final.grd 
    Manually edit /scratch/madagascar/madagascar_final.grd to remove the first blank line.

Run the downscaling experiment

  1. Create a new folder in the directory /scratch/from_GUI/ and let's call it mdg_etoofs (this is the Experiment ID), and copy to it the input configuration files:

    mkdir /scratch/from_GUI/mdg_etoofs
    cp /scratch/surf/surf_shyfem/surf_shyfem_1.00/input_param* /scratch/from_GUI/mdg_etoofs/

  2. Copy the surf_shyfem source code to the experiment directory:

    ln -s /scratch/surf/surf_shyfem/current/* /scratch/surf/experiments/mdg_etoofs

  3. Run the experiment:

    cd /scratch/surf/surf_shyfem/current/scripts; python mdg_etoofs

Known issues

  • File "/scratch/surf/experiments/mdg_etoofs_ext/code/ocean/scripts/bathyI nterp/", line 28, in inBox
    idNodes = self.nodes[:, 1].astype(int)
    IndexError: too many indices for array: array is 1-dimensional, but
    2 were indexed
    You have to remove the first blank line from the file new.grd.

  • ```bash
     warning : nodes in element *** are in clockwise sense
    Apply ```/scratch/surf/surf_shyfem/current/shyfem/fembin/exgrd -a``` to your input `new.grd` file. If it does not work, change the order of nodes in the `new.grd` file by hand.
  • ```bash
    FileNotFoundError: [Errno 2] No such file or directory: b'/scratch/surf/experiments/mdg_prova1/data/indata/ocean/20210402_d'
    Manually insert in `/scratch/surf/experiments/{experiment_name}/indata/` the input data for ocean atmosphere and observations needed for your experiment.
  • ```bash
    STOP error stop adjust_levels: hlv too low
    Select correctly the levels in `input_param_basic.json`. Your modeled ocean is not deep enough.
  • STOP error stop (<something about boundaries>)
    Did you correctly select the path in boundariesPath of input_param_basic.json files?

  • STOP error stop iff_init
    If the simulation breaks when reading the initial conditions files, check if there is a blank line somewhere. E.g., for uvin.dat, there may be one before “v-velocity”. You cannot remove it, since SURF will create the file again when launching the simulation. A workaround (ninja skills required) is to manually stop (ctrl+Z) the execution right after the creation of the problematic file (say uvin.dat), manually remove the blank line that is causing the error and then resume the process execution (fg %[job ID])

  • mv: cannot stat '': No such file or directory
    Good question. There should be a previous error, so you should look above in the error traceback to fix it.

        fatal:PlotManagerPreDraw: error in plot pre-draw
    There is a failure in the final plots generation. This is expected, since the postprocessing tools are not yet stable. If the files and have been produced, the experiment has correctly concluded.