VISIR-2 is a numerical model realised by the CMCC Foundation.

• Usage
  • Requirements
  • Quick run
  • Detailed Run Information

Usage

Requirements

to top

The only required software to run VISIR-2 is the Conda environment and package manager.

A single Conda environment file, visir-venv.yaml, is included with the source code. It lists all necessary dependencies for running VISIR-2.

The initial step involves installing the virtual environment, via:

conda env create -f visir-venv.yaml

Then activate it, in every new console session:

conda activate visir-venv

If you run VISIR-2 from a console, you must ensure that the absolute path to your local repository copy is added as an environment variable. This can be achieved as follows:

On Unix systems:

export PYTHONPATH=$(pwd)  

or

export PYTHONPATH=/path/to/VISIR-2

On Windows systems:

set PYTHONPATH=%CD%       

or

set PYTHONPATH=C:\path\to\VISIR-2

To upgrade an existing installation, recreate the environment rather than updating it in place:

conda env remove -n visir-venv
conda env create -f visir-venv.yaml

An offline copy of the user manual ships with every release, at Docs/Manual/VISIR-2_userManual.html inside the source distribution.

Quick run

to top

The fastest way to see VISIR-2 running is to start from a ready-made bundle of input data and namelists.

1. Download the required input data and namelists from https://doi.org/10.5281/zenodo.23018319

2. Expand the zip and install its contents into your VISIR-2 folder

3. Activate the Conda environment and set PYTHONPATH to the repository root (see Requirements), then run the MAIN_*.py file of each module, in this order:

    conda activate visir-venv
    export PYTHONPATH=$(pwd)
    python _a_Grafi/MAIN_Grafi.py
    python _b_Campi/MAIN_Campi.py
    python _d_Tracce/MAIN_Tracce.py
    python _e_Visualizzazioni/MAIN_Visualizzazioni.py
   

4. Explore the output in the __product folder:

   • Voyageplans
   • Metrics
   • Maps
   • Profile plots

To run VISIR-2 on your own domain and your own input data instead, follow the Detailed Run Information section below.

Detailed Run Information

to top

Please refer to this tutorial:

Here’s a textual version of what the video tutorial above shows. For VISIR-2 runs in customized regions and using own environmental and vessel information, do the following:

1. To download the required input data, your approach will depend on whether you want a) to reproduce the results of the peer-reviewed paper or b) run the model with a new configuration. Here is how you can do it:

   • For a) download raw data to reproduce the paper’s results from https://doi.org/10.5281/zenodo.10674079

   • For b) download:

     • bathymetry (recommended source: GEBCO, 2D netcdf for user-defined areas)
     • marine fields: with waves as a minimum (recommended choice: Copernicus Marine Service fields)
     • shoreline (e.g from Natural Earth¹) used for visualisation purposes.

2. Execute:

   1. Duplicate the template file located in the __namelist/_a_Grafi subfolder (both .yaml and .yml file formats are supported). Each namelist includes inline documentation of the meaning and available options for each key. Note: the original template_*.yaml files in the __namelist subfolders must be left untouched and the filename must not include the template string.

   2. Fill the duplicated namelist file by following the provided inline instructions. Note: all valued variables in the template must be also filled in its copy.

   3. Run MAIN_Grafi.py

3. As step 2 but for _b_Campi. Note: It is recommended to use a single file containing all time steps of the environmental field of interest, rather than separate files for each time step. Please refer to _b_Campi/readEnvFields.py (get_readNetCDF function) for guidance.

4. Do not manually run _c_Pesi. Rather, do as step 2 but for _d_Tracce. If dealing with harbour codes in the corresponding namelist, launching MAIN_search_harbours_DB.py in the GUI module is recommended.

5. As step 2 but for _e_Visualizzazioni

6. Explore the output:

   • Voyageplans
   • Metrics
   • Maps
   • Profile plots

Non-interactive runs: every MAIN_*.py accepts a –job/-j <namelist> argument, so the steps above can be scripted without the interactive job picker. For example:

python _a_Grafi/MAIN_Grafi.py --job Tyrrhenian
python _d_Tracce/MAIN_Tracce.py --job alboran_cuwi

Omitting the flag falls back to the legacy interactive picker. Pass -h to any of them for its argument summary.

The Navi and GUI modules are driven differently: MAIN_vesselModels_identify.py reads the variables set at the top of the script itself, and MAIN_search_harbours_DB.py simply opens the harbour-search interface.

Two launching modes are therefore available, demonstrated below using the _a_Grafi module:

• Interactive mode (launches a namelist picker interface):

python _a_Grafi/MAIN_Grafi.py

• Direct submission (specifies a parameter file directly):

python _a_Grafi/MAIN_Grafi.py --job <namelist>

To inspect the supported arguments:

python _a_Grafi/MAIN_Grafi.py -h

---

¹ GSHHG v2.3.7 (discontinued since 2025) was used to produce the results included in previous VISIR-2 releases (v1-v5). Starting from the v6 release, data from Natural Earth is used instead.