• Usage
  • Requirements
  • Quick run

Usage

Requirements

to top

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

Two Conda environment files are included with the source code. These files list all necessary dependencies for running VISIR-2. You can use Conda to create the environments and automatically install the required packages.

There is a general environment for most modules, visir-venv.yaml, and one, visir_vis-venv.yaml, for running both the GUI and the _e_Visualizzazioni modules (see. Suite Structure)

The initial step involves installing the virtual environment ¹, via:

conda env create -f visir-venv.yaml

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=<VISIR_path>

On Windows systems:

set PYTHONPATH=<VISIR_path>

Quick run

to top

Please refer to this tutorial:

Here’s a textual version of what the video tutorial above shows. After familiarising yourself with the VISIR-2 suite’s structure, please do the following steps:

1. To download the required input data, your approach will depend on whether you want a) to reproduce the results from the peer-reviewed paper or b) run VISIR in a new domain. 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.) Note: the original template_*.yaml files in the __namelist subfolders must be left untouched.

   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 _e_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

---

¹ For installation on Apple Silicon processors, an issue with Python 3.7 can be resolved using the following workaround

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