1  Getting started

In this section, download and install instructions are provided.

1.1 Prerequisites

1.1.1 Java

In order to run Ichthyop, Java (>= 11) needs to be installed. To make sure that Java is installed and that you have the right version, type:

java --version

If you see an error, then you need to install Java. If the version is less than 11, you need to reinstall it.

If needed, see Chapter 7 for the Java install instructions.

1.1.2 NetCDF4

The Java library that manages input/output of files in Ichthyop requires the external NetCDF C library, which can be installed as follows:

1.1.2.1 Mac Os X

Open a Terminal and type:

sudo port install netcdf4

1.1.2.2 Linux

Open a Terminal and type:

sudo apt-get install netcdf4

1.1.2.3 Windows

Download the pre-built libraries from Unidata website

Caution

During the install process, make sure that the location of the library is added to the PATH

1.1.3 Conda environmenmt

There is also the possibility to use Conda environments in order to install Maven, OpenJDK and NetCDF4 easily. Instructions can be found on https://github.com/ichthyop/ichthyop-conda

1.2 Downloading Ichthyop

The Ichthyop tool is available on GitHub. There are two ways to use Ichthyop:

• Use executable files (.jar files) (preferably for beginners)
• Use source files (preferably for advanced users and developers)

1.2.1 Using executable files

Ichthyop executable files can be downloaded here. Download the latest ichthyop-X.Y.Z-jar-with-dependencies.jar file (replacing X.Y.Z by the version number). Older versions are also available if necessary.

1.2.2 From source

To get the source code, type in a Terminal (Unix/MacOs) or Git Bash prompt (Windows):

git clone https://github.com/ichthyop/ichthyop.git

The code can then be compiled either using IDE (NetBeans, VSCode) or using the following command line:

mvn package

The executable will be generated in the target folder.

Warning

To use the command line, Maven needs to be installed (see instructions on https://maven.apache.org/install.html)

1.3 Downloading input hydrodynamic files

To run Ichthyop hydrodynamic files with (at least) water velocity fields are required. Demo files generated by several hydrodynamic models can be downloaded here. Put these files into the ichthyop/input folder.

1.4 Running Ichthyop

1.4.1 Clicking on file (Windows)

Open the Ichthyop folder and double click on the ichthyop-X.Y.Z-jar-with-dependencies.jar file, where X.Y.Z is the Ichthyop version. The Ichthyop console should open up

1.4.2 From command line (Unix/Mac Os X)

Open a command line prompt (Terminal or CMD prompt) and navigate to the Ichthyop folder using cd.

Then, type:

java -jar ichthyop-X.Y.Z-jar-with-dependencies.jar

with X.Y.Z the Ichthyop version.

This will prompt the Java console. In order to run Ichthyop without the console, you need to specify a supplementary argument, which is the XML configuration file (see Chapter 3)

java -jar ichthyop-X.Y.Z-jar-with-dependencies.jar cfg-roms3d.xml

1.4.3 Starting from a generic configuration

Since Ichthyop 3.5, it is strongly recommended to use the generic configuration as a template. It proposes all the possible parameters and datasets. In the future, only this template will be maintained.

To create a configuration file from the generic configuration, use the graphical interface as described in Section 2.1.1. Choose the generic template. Depending on the test case study, you will need to update the Beginning of simulation and Transport duration parameters, and the following Table 1.1

Table 1.1: Beginning of simulation and Transport duration parameters to define for each test case study

Dataset	Beginning	Lon	Lat
OPA NEMO	year 2001 month 10 day 20 at 00:00	53	-11.5
ROMS 2D/3D	year 1900 month 05 day 02 at 12:00	17	-33
MARS 2D/3D	year 2010 month 05 day 13 at 12:00	-5.5	48.4
MERCATOR 3D	year 2026 month 04 day 01 at 10:00	35.66	-21.75
SYMPHONIE	year 1998 month 03 day 11 at 01:00	-1	37