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. Beforehand, let us clarify some of the acronyms regarding the Java technologies.

JVM: Java Virtual Machine. It is a set of software programs that interprets the Java byte code.

JRE: Java Runtime Environment. It is a kit distributed by Sun to execute Java programs. A JRE provides a JVM and some basic Java libraries.

JDK or SDK: Java (or Software) Development Kit bound to the programmer. It provides a JRE, a compiler, useful programs, examples and the source of the API (Application Programming Interface: some standard libraries).

It is strongly recommended to download a JDK, in order to both compile and run the model. Builds for different platforms can be found here.

(nc-inst)=

1.1.2 NetCDF4

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

Mac Os X

To install the library on a Mac Os system, open a Terminal and type:

sudo port install netcdf4

Linux

To install the library on a Linux system, open a Terminal and type:

sudo apt-get install netcdf4

Windows

To install the library on a Windows system, download the pre-built libraries ib 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 also is 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 model is available on GitHub. There is two ways to recover Ichthyop:

  • Using executable files (.jar files).
  • From source files.

1.2.1 Using executables

Ichthyop users can download Ichthyop executables here. Choose a version, and download the {samp}ichthyop-X.Y.Z-jar-with-dependencies.jar file (replacing {samp}X.Y.Z by the version number).

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 hydrodynamical files

To run Ichthyop templates, sample hydrodynamical files are required (input folder). They were previously part of the GitHub repository but have been migrated to Zenodo. They can be downloaded here.

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. You should see the Ichthyop console.

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.

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