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.

You can download the new SURF-SHYFEM release from the page https://www.surf-platform.org

Introduction

...

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:

surf_vm_VERSION.zip

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.

/docs/assets/img/VM_install_VitualBoxsite_v2.png
Downloads VirtualBox base package.

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

/docs/assets/img/VM_install_VirtualBoxExtentionPacks.png
Downloads VirtualBox Extension Packs.

  • 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).

    unzip surf_1.01.zip
/docs/assets/img/VM_install_downlVMsurf.png
Downloads SURF Virtual Machine.

  • 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 surf to the list of Virtual Machine

/docs/assets/img/VM_install_openVMsurf.png
Add SURF-VM in VirtualBox.

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

/docs/assets/img/VM_install_login.png
Start SURF-VM.

Disk Partitions mounted on the SURF Virtual Machine

The SURF Virtual Machine package contains two VDI (VirtualBox Disk Image) files:

  • surf.vdi containing the Debian GNU/Linux operating system (version 10.3)

  • surf_scratch.vdi thought 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:

  • the disk /dev/sda "mounted" as filesystems to the root directory /

  • the disk /dev/sdb "mounted" in the directory /scratch.

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_".

/docs/assets/img/VM_install_sharefolder.png
Mount shared folders.

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

/docs/assets/img/VM_install4.png
Change VM configurations.

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
/docs/assets/img/VM_install5.png
Enlarge the virtual disk.
  • 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
/docs/assets/img/VM_install5.png
Enlarge the virtual disk.
Table 6.1 Virtual Machine Summary Fields.
Parameter Description Values
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 /scratch. 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 the format:

packageName_<VERSION>.tar.gz

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 $SURF_RELEASES).

  • Go to the directory $SURF_RELEASES and run the installation bash script install.sh followed 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_shyfem/ and /scratch/surf/surf_datasets/, respectively, and will create a symbolic link current in this directory that points to the extracted folder (for simplicity, we abbreviate this location as $SURF_SHYFEM, $SURF_DATASETS, respectively).

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

...

D. Bibliography

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