How To

In this page you can find a list of typical use-cases supported by SURF-NEMO. Before starting to explore the available options, if you haven't done so already, we recommend you to first follow the Getting Started section before starting to customize your experiment.

Select and Download Input Data Products

Click here to expand...

When you run your first experiment, you manually downloaded and used local input data. Luckily, you don't have to do that every time you run a simulation with SURF.

By correctly configuring SURF, the input data will be automatically downloaded for you from the internet, using the official server APIs such as the Copernicus Marine Toolbox or the CDSAPI service. The only requirement is for you to have a stable and relatively fast internet connection.

Note that some data providers require you to have a personal account in order to download data from their servers (see table below). For those services, after creating an account you will have to upload you personal credentials into the SURF configuration file.

The currently supported input data products in SURF are:

Provider	Type	Account required?	Config section	Product ID	Type
CMEMS - Copernicus Marine Data Store	Ocean	Yes (CMEMS)	🔗	CMEMS_GLOBAL_MULTIYEAR_PHY_001_030	Reanalysis, Global
				CMEMS_GLOBAL_ANALYSISFORECAST_PHY_001_024	Analysis and Forecast, Global
				CMEMS_MEDSEA_MULTIYEAR_PHY_006_004	Reanalysis, Mediterranean Sea
				CMEMS_MEDSEA_ANALYSISFORECAST_PHY_006_013	Analysis and Forecast, Mediterranean Sea
				CMEMS_BLKSEA_MULTIYEAR_PHY_007_004	Reanalysis, Black Sea
				CMEMS_BLKSEA_ANALYSISFORECAST_PHY_007_001	Analysis and Forecast, Black Sea
ECMWF - Climate Data Store	Atmosphere	Yes (CDS)	🔗	ECMWF_ERA5_REANALYSIS	Reanalysis, Global
NOAA - Global Forecast System	Atmosphere	No	🔗	NCEP_GFS_FORECAST	Analysis and Forecast, Global
GEBCO	Bathymetry	No	🔗	GEBCO 2024	Global
GSHHG	Coastline	No	🔗	GSHHG h	Global
TPXO	Tide	No	🔗	TPXO8	Global

ECMWF Credentials

Configuring your credentials to download ECMWF data can be a little tricky. For this reason, here is a more detailed step-by-step guide:

Log in on the (CDS) website
Browse to the how-to-api page. Here, if you are still logged in, you will be able to see your personal access token
Copy your personal access token and paste it under the 🔗Surface Boundary Conditions section of your configuration file (it's a parameter called Password)
Additionally, in order to automatically download data from the CDS you must manually agree to the Terms of Use. To do so, browse to the product download page, scroll down until you encounter the Terms of Use section and click on the "Agree" button.
That's it, you can now launch your experiment and SURF will automatically download ECMWF data for you!

Select the Simulation Domain

Click here to expand...

To change the simulation domain, you need to adapt the JSON configuration file section 🔗Nested Grid and Land-Sea Mask Settings. There, you can directly choose the domain coordinates, the grid resolution, distribution of vertical levels, and the land-sea masking dataset.

Select the Simulation Time Period

Click here to expand...

To change the simulation time period, you need to adapt the JSON configuration file section 🔗Simulation Period and Time Step Parameters. There, you can directly choose the start and end date of the simulation.

Spin-up Days

You shouldn't be surprised if the actual start date of your simulation does not correspond to the start_date you have chosen in the configuration file.

That's because SURF automatically offsets the start date by a certain number of days, called the spin-up period:

actual_start_date = start_date - n_days_spinup

The purpose of the spin-up period is to allow the model to adjust dynamically to the external forcing and reach a steady state (see Trotta et al. 2016). By default, the spin-up time is set to 3 days. As an advanced option, the spin-up period can be disabled or modified in the Expert JSON configuration file section 🔗Simulation Period and Time Step Parameters

Run an Operational Forecast

Click here to expand...

To run an operational forecast, you have to:

Set the simulation start date to null under the JSON configuration file section 🔗Simulation Period and Time Step Parameters. This way, SURF will automatically start the simulation from the current date (excluding spin-up days which are in the past).
Select analysis and forecast input products, both for the atmosphere and the ocean (see the available products above).

Customize the Output Figures

Click here to expand...

With SURF, you have the possibility to customize the output visualization. To do so, you can modify the JSON configuration file section 🔗Postprocessing to select the desired visualization parameters.

Image Generation for Multiple Days

By default, SURF generates images only for the final simulation day. If you want to generate images for all simulation days, you can set the Plot Only Final Date flag to false in the JSON configuration file section 🔗Postprocessing.

Resume an Existing Experiment

Click here to expand...

It may happen sometimes that you have started an experiment, made some progress but had to interrupt it. For example, due to a network error or missing credentials.

In this case, instead of starting again from scratch, you can simply set the overwrite flag to false in the 🔗Session Settings when running the experiment. This way, SURF will mount the existing experiment directory and resume from the last checkpoint.

Mask Part of the Domain with Land Points

Click here to expand...

Sometimes, you may not be interested in part of the domain. For example, when part of your domain has no direct connection with your study area, it might be a good idea to mask it. To do so, you can use the JSON configuration file section 🔗Modify Bathymetry section, to modify the land points mask. This way, you will be able to any number of zero-bathymetry (=land) rectangular patches to your domain.

To mask your domain, you can choose for example to:

Add a constant value to the surface elevation for the entire nested region (e.g., adjusting the water level for an inland body of water like the Caspian Sea)
Set maximum and minimum depth values (e.g., enforcing a minimum depth of 5 meters or a maximum depth of less than the actual depth)
Define land/sea grid points based on the input coastline
Set maximum and minimum depths in specific sub-regions (e.g., to mask a particular area)

Caveat: You have to be careful to not add too many land patches, as this may significantly affect the circulation patterns in your domain.

Masked domain.

Modify the Source Code and Create a Custom Image

Click here to expand...

💡 Advanced

In some cases, it may be useful to directly modify the source code inside the container, to accomodate some advanced use cases.

To do so, you have to start an interactive session with SURF:

1	`surf_nemo [...] --interactive`

Once inside the container, you can make your modifications using the installed editors or your favorite IDE. Be careful, if you close the container, all your changes will be lost!

The trick to persist your modifications is to export the container as a new image. First, open another Terminal and find the container ID:

1	`docker ps`

Then, take a snapshot of the container state and export it as a new image:

1	`docker commit [CONTAINER_ID] [NEW_IMAGE_NAME]`

You can now safely close the container. You will be able to launch your modified image with the SURF CLI by adding the --image flag:

1	`surf_nemo [...] --image [NEW_IMAGE_NAME]`

Recompile NEMO

Click here to expand...

💡 Advanced

In case you want to make some low-level modifications or change the NEMO code, you have the possibility to recompile NEMO from scratch, using an automatic compilation script.

To do so, you have to follow the instruction of the Modify the source code and create a custom image section.

Once you are inside the container, you can make your modifications and recompile NEMO using the recompilation script as follows:

1 2	`cd /model ./nemo.sh`