Welcome to the SURF-SHYFEM User Guide
This user guide provide documentation for the Structured and Unstructured grid Relocatable ocean platform for Forecasting (SURF) (release version 1.00).
Please read the release notes to see what has changed since the previous release.
Note: The documentation is also available in PDF format: surf_shyfem_1.00_beta.pdf.
You can download the new SURF-SHYFEM release from the page https://www.surf-platform.org
SURF is a free and open source software packages distributed under the terms of the GNU General Public License (GPLv3).
Table of Contents
- 1. Introduction
- 2. Work-Flow of SURF-SHYFEM platform
- 3. User Configuration File: Preprocessing sections
- 4. User Configuration File: Postprocessing sections
- 5. Input/Output Model Datasets
- 6. Quick Start Guide
- A. Reference Configuration
- B. Scratch Partition and its directory structures
- C. Linux Root Partition and the installed packages
- D. Bibliography
Work-Flow of SURF-SHYFEM platform
User Configuration File: Preprocessing Sections
User Configuration File: Postprocessing Sections
Input/Output Model Datasets
Quick Start Guide
This chapter describes how you can quickly get started with the SURF platform. We show how to download and install the SURF Virtual Machine and all the SURF packages. We describe how to compile (if needed) the source codes. We present how to execute a case study (template) experiment in the Elba area and view the results. Finally we show how the user-configuration file of a template experiment can be modified in order to execute and analysis new experiments. The template experiment makes it easier to run the model without detailed knowledge of the underlying scientific basis. Only a limited number of default values need to be changed for most applications. A more specific scientific background is required if for example, the user intends to perform experiments with different turbulence or numerical schemes or with alternative settings of model parameters. It is then recommended to read first the SHYFEM Model Description document and relative article.
See also the video tutorials available online here explain the basic features of the SURF platform and designed for beginners who want to learn SURF step by step.
Download and Install SURF Virtual Machine
The SURF platform will be provided as a Virtual Machine (VM). It is packaged and distributed as a ZIP Compressed Archive file (with a .zip extension). The general scheme adopted to manage the versions provides that the releases contain in the name indications of the version in the format:
where VERSION is a number (e.g. surf_vm_1.01.zip for the current version). The instructions below explain how to download, install and configure the SURF VM in Oracle VirtualBox
Navigate to https://www.virtualbox.org/ and click on Downloads button. Choose the
VirtualBox base package(version >=6) corresponding to the host operating system of your computer (i.e. Windows, Mac, Linux). Save the corresponding file on your computer, double-click it to open it, and follow the installation instructions.
In addition to the base package, download also the
Extension Packs. This package provides additional functionality to the base package, such as virtual USB device, remote desktop support, ecc. To install this extension, simply double-click on the package file and follow the installation instructions. Please install the same version extension pack as your installed version of the VirtualBox base package.
Download the current version (v1.01) of the SURF virtual machine from SURF web-page. In the virtual machines is installed the Debian GNU/Linux 8.11 operating system. The Guest Additions have been also installed to optimize the guest operating system for better performance and usability. Extract than the package in your VirtualBox directory which Oracle VM VirtualBox creates in the current system user's home directory (i.e.
/Users/USERNAME/VirtualBox VMs/for Mac user).
Open the VirtualBox software. From the menu, choose Machine > add and navigate to the file
surf.vbox. This file is an XML file that contains settings of the Machine. This will add the Virtual Machine
surfto the list of Virtual Machine
To start the VM surf, you can double-click on its entry in the list in the VirtualBox Manager window or select its entry and press the Start button at the top of the window. A window opens. The VM Login should look like the figure 6.5 . In the login dialogue box enter:
surf as login
surf2019 as an initial password
You are now logged into the VM.
Disk Partitions mounted on the SURF Virtual Machine
The SURF Virtual Machine package contains two VDI (VirtualBox Disk Image) files:
surf.vdicontaining the Debian GNU/Linux operating system (version 10.3)
surf_scratch.vdithought to contain source code files, datasets sample and experiments.
From the guest operating system you can see the list of partitions by typing the following command:
sudo fdisk -l
It is divided into two main partitions:
/dev/sda"mounted" as filesystems to the root directory
/dev/sdb"mounted" in the directory
Optionally you can mount other physical hard disks with VirtualBox (see the VirtualBox Manual for details). VirtualBox has the ability to mount a shared folder between host and guest in order to access files of your host system from within the guest system. There are a few steps involved:
Shut down the virtual OS before you can edit settings.
Select the surf VM in the VirtualBox Manager and click Settings.
Select Shared Folders, and click the Plus button to add a new shared folder. Specify the host folder you want to share.
Select auto-mount and then click OK.
You can now re-start the VM surf. The shared folder is mounted into the /media directory, along with the prefix "sf_".
Changing Configuration on the SURF Virtual Machine
By default, the VM surf is configurated as in table Table 6.1 . You can keep all defaults parameters or if it is not adequate for your application you can change settings. To change the configuration you need to shut down the virtual OS before you can edit settings.
Select the surf VM in the VirtualBox Manager, right-click it and choose Setting.
increase/decrease the number of cores based on your performance desires.
increase/decrease the number of GB of RAM allocated to your VM according to the size of your computational domain.
increase/decrease the video memory and scale factor of your screen
If you want to add more storage space to a VM you can also expande the virtual hard disk. There are a few steps involved:
- With the VM Power off, open a terminal and move to the location of the surf_scratch.vdi file that you want to resize,
- At the terminal prompt, type the command:,
VBoxManage modifyhd surf_scratch.vdi --resize SIZE_MB
- Restart the SURF VM and open the GParted application from the Application Menu
- Select the /dev/sdb partition (an unlocated drive space is now available). Resize to the unalocated area
|Name||Name given the VM||surf|
|Guest OS||Operating system running on this VM||Debian Linux|
|Memory||Amount of memory available to this VM||2 [GB]|
|Cores||Number of CPU cores being used by this VM||2|
|Disk Capacity||Total disk capacity available to this VM||40 [GB]|
|Network Adapters||Number of network adapters available to this VM||1|
|IP Address||IP address assigned to the VM||x|
Download and Install SURF packages
Once logged in, open a new terminal window and go to the directory
The scratch directory follows the directory structure as shown in Fig. B.1. The VM you have installed does not contain the SURF
packages (source codes and static datasets) and you need to download and install them. The SURF packages are
packaged and distributed as a GZIP Compressed Tar Archive file (with a .tar.gz extension). The general scheme
adopted to manage the versions provides that the releases contain in the name indications of the version in
where <VERSION> is a number (e.g. surf_shyfem_1.00.tar.gz for the current version of the surf_shyfem package). The instructions below explain how to install the package in the VM:
Once logged in the VM surf, download the current version of the SURF-SHYFEM (surf_shyfem_1.01.tar.gz) and SURF-DATASETS (surf_datasets_1.01.tar.gz) packages directly from the SURF web-page and save it in the directory
/scratch/surf/surf_install/releases/(for simplicity, we abbreviate this location as
Go to the directory
$SURF_RELEASESand run the installation bash script
install.shfollowed by the package name. For the SURF-SHYFEM packages type:
cd $SURF_RELEASES ; install.sh surf_shyfem_1.01.tar.gz
For the SURF-DATASETS packages type:
cd $SURF_RELEASES ; install.sh surf_datasets_1.01.tar.gz
The installation process will extract the archive in the directory
/scratch/surf/surf_datasets/, respectively, and will create a symbolic link
currentin this directory that points to the extracted folder (for simplicity, we abbreviate this location as
For a detailed description of the directory structure and contents of each package refer to the Appendix B.
Compiling the source code
After the installation of the SURF-SHYFEM package is finished, you need to compile the source codes in order to create the executable files needed to perform specific tasks....
Running the case study: Elba area
As case study we implement the SURF platform in the Elba area in the ...
Post-processing the results
A. Reference Configuration
B. Scratch Partition and its directory structures
C. Linux Root Partition and the installed packages
Umgiesser, G., Melaku Canu, D., Cucco, A., Solidoro, C., (2004). A finite element model for the Venice Lagoon. Development, set up, calibration and validation., J. Marine Syst. 51 (51), 123-145.