ichthyop lagrangian tool for modelling ichthyoplankton

ICHTHYOPLagrangian tool for modelling

ichthyoplankton dynamics

USER GUIDE

Version: 3.0b

Contact: [email protected]

Web site: www.previmer.org/ichthyop

Juillet 2010

COASTAL OBSERVATIONS& FORECASTS

mailto:[email protected]

http://www.previmer.org/ichthyop

TABLE OF CONTENT

1) Introduction........................................................................................................................32) Beta version.......................................................................................................................43) Changes from v2 to v3.......................................................................................................44) Installation..........................................................................................................................5

4.1) Content of the distributed package.............................................................................54.2) First run.......................................................................................................................54.3) Java heap space........................................................................................................5

5) Step 1 : configure...............................................................................................................65.1) New configuration file.................................................................................................65.2) Content of the configuration file..................................................................................7

6) Step 2 : run simulation.......................................................................................................86.1) From the GUI..............................................................................................................86.2) Batch mode.................................................................................................................9

7) Step 3 : visualize results....................................................................................................97.1) Results......................................................................................................................107.2) Set particle color.......................................................................................................10

7.2.1) Default color......................................................................................................107.2.2) Particle size.......................................................................................................107.2.3) Color bar............................................................................................................10

7.3) Make maps using Web Map Service........................................................................107.4) Export trajectories to KMZ format.............................................................................11

8) Step 4 : animation............................................................................................................119) Appendix..........................................................................................................................12

9.1) Install / update the Java Runtime Environment........................................................129.2) Required libraries.....................................................................................................139.3) Get the source code.................................................................................................14

10) Acknowledgments..........................................................................................................14

Document historyAuthor Date Description od document modificationsP.Verley 15/12/2009 Creation of the documentP.Verley 17/06/2010 Document writingP.Verley 09/07/2010 Document update

Ichthyop 3.0b - User guide / 14

1) IntroductionThe ICHTHYOP tool simulates the Lagrangian transport of particles using

oceanographic fields produced by models such as ROMS, MARS1 or OPA-NEMO, for applications in physical oceanography and in marine ecology. Possible applications include:

• Studying transport processes and their effect on fish ichthyoplankton recruitment variability (by defining release zones, recruitment zones and a recruitment criterion).• Simulating egg buoyancy and larvae growth (using salinity and temperature fields).• Tracking virtual drifters and recording their positions in NetCDF files and visualizing the result with GoogleEarth.• Simulating vertical migration (transport at iso-depth layers or diel vertical migration)• Simulating horizontal and vertical dispersion.The tool offers two functioning modes: GUI and BATCH. The first one is a "click and

run" mode. It uses a user-friendly graphic interface for configuring and running the simulation and provides some tools for plotting the transport of virtual eggs and larvae, creating some animations or exporting the trajectories in KMZ format for visualizing them with Google Earth. The second mode is batch processing. It enables to run series of simulations based on different pre-defined sets of parameters from a command line, without any UI for granting full power to computation.

The tool is an open source program, developed with the Java language. The source code is available ([email protected]) and can be modified to suit better one's needs.

There are two levels of utilization of this program. At a first level, it can be run as an executable. With this approach there is no need to know anything about Java or programming to successfully run a simulation. Parameters and options can be easily set up in the GUI (Graphical User Interface) or using any text editor. On a second level, some users might want to make some changes in the source code, in order to customize the model. To do so a Java Development Environment is required. A standard development kit (JDK), like the one distributed by Sun, might be sufficient, but we recommend the use of Java development tools with a graphical interface like Netbeans (section #).

The ICHTHYOP tool has been developed in the frame of PREVIMER project. PREVIMER is a pre-operational system aiming to provide a wide range of users, from private individuals to professionals, with short-term forecasts about the coastal environment along the French coastlines bordering the English Channel, the Atlantic Ocean, and the Mediterranean Sea.

Working in partnership with the French Naval Hydrographic and Oceanographic Service (Service Hydrographique et Océanographique de la Marine, SHOM), the French National Weather Service (Météo France), the French public science and technology research institute (Institut de Recherche pour le Développement, IRD), the European Institute of Marine Studies (Institut Universitaire Européen de la Mer, IUEM) and Brest-

1 Model Applications at Regional Scale developed by Ifremer


Iroise Science and Technology Park (Technopôle Brest Iroise), IFREMER (the French Research Institute for Exploitation of the Sea) is supplying the technologies needed to ensure this pertinent information, available daily on Internet, and stored at the Operational Coastal Oceanographic Data Centre.

PREVIMER provides researchers and R&D departments with modeling tools (such as ICHTHYOP) and access to the database, in which the observation data and the modeling results are stored, to undertake environmental studies on new sites.

2) Beta versionYou might have noticed that the version number is 3.0b and not just 3.0. "b" means

BETA.Indeed, for the next couple of months, the application will remain on beta version. It

means the tool has been fully tested by the programmers and it would be now greatly appreciated having you as beta-tester. Please email any feedback, bug report, comment, congratulation, criticism, etc. to [email protected]

Thanks by advance !

3) Changes from v2 to v3The third version of Ichthyop is a brand new application. Most parts of the program have

been re-coded : new user interface ; new modular architecture ; new input / output management ; thorough error management, etc.

There is no compatibility between configuration files from version 2 and 3. Configuration files are now XML files. Nonetheless, all the scenarii of simulation handled by the second version can be reproduced using the third version.

Version 2 used to distinguish SINGLE & SERIAL simulations, with SINGLE simulation that could be configured and run with the GUI and the SERIAL simulation that has to be configured with text editor and run without GUI. The distinction does not exist anymore in version 3. Each configuration can be either SINGLE or SERIAL : it just depends on whether you defined parameters with single values or with series of values. The configuration editor supports series of values for the SERIAL parameters. Moreover, in version 2, calculation and plotting occurred at same time, whereas in version 3, the application computes trajectories (for a single simulation or series of simulation) first and then draws the trajectories by reading particle positions in the NetCDF output file.

Release and recruitment zones are now defined in independent XML files whereas in version 2, they had to be defined in each configuration file.

Third version of the tool also proposed new features :▪ read OPA NEMO output files ;▪ pre-filled configuration files that connect Ichthyop to some MARS dataset servers (OpenDAP technology) for simulations around the Mediterranean sea or the Bay of Biscay.▪ exportation of the results to KMZ format for visualizing trajectories with GoogleEarth.


▪ visualization of the results with several types of maps retrieved with Web Map Services.▪ drift due to sea surface wind

4) Installation

4.1) Content of the distributed package

Download the ichthyop-3.#.zip file. Extract the archive anywhere on your hard disk. You should get the following folders and files within a folder named ichthyop:

▪ ichthyop-3.#.jar - Ichthyop executable file ▪ lib/ - Necessary librairies to run the program ▪ input/ - Basic input file used for the examples▪ readme.txt - information about the application

4.2) First run

Two ways:▪ Open a command line, go to the ichthyop directory and type

java -jar ichthyop-3.#.jar▪ Browse to the ichthyop directory and double click on ichthyop-3.#.jarThe main frame should show up. Let's create a new configuration file. Click on Menu >

Configuration > NewSelect one of the templates in the tree. All of them generate preset configuration files

that are ready to run. Beware that for running the MARS OpenDAP simulations (MANGA or MENOR) you must have a decent internet connection in order to retrieve MARS hydrodynamic datasets form OpenDAP servers. Save the configuration file.

Since the configuration is ready to run, so you do not need to change any parameter in the configuration editor. Go straight to "Step 2 : simulation" and click on the "Preview" button for visualizing the simulated area, then on the "Run simulation" button.

As soon as the run is completed, Ichthyop automatically goes to "Step 3 : mapping". Depending on whether your computer is connected to Internet, the application will try to retrieve some background maps from Web Map Services or, on the contrary will leave a grey background. In the first case, click on button "Make maps" for generating the pictures. When the maps creation is over, the application takes you to "Step 4 : animation" where you visualize the trajectories of the particles. In the second case you can export the results to KMZ format for visualizing with GoogleEarth. Click on "Export to KMZ" button, then browse to the ichthyop/output/ folder and open the kmz file with GoogleEarth (it has to be installed on your computer).

4.3) Java heap space

The command "java -jar ichthyop-3.#.jar" or the double click calls the JVM with default


Java settings. Quite often, for big simulations (a lot of particles, long runs, etc.) the application might crash and be quite rude with you: "Exception in thread "main" java.lang.OutOfMemoryError: Java heap space". It means Java did not allocate enough heap memory to the JVM. You should be able to avoid this problem with the command:

java -Xms512m -Xmx1024m -jar ichthyop-3.#.jarIt means the initial heap size is 512 MB and the maximum heap size is 1024 MB.

5) Step 1 : configure

Figure 1: Step 1, configure

Here you will find the usual "File menu" functions : create a new configuration file, open an existing one, close it or save and save as the configuration file.

5.1) New configuration file

Figure 2: Step 1, create a new configuration file


The application comes with some preset examples of configuration files (the templates). Select one of the templates, change the name of the configuration if the suggested name does not suit you and click on the Create button.

5.2) Content of the configuration file

Figure 3: Step 1, edit the configuration file

The configuration file is organized in several categories and each category contains several blocks of parameters.

When the configuration file is created out of a template, it is ready to use and you do not need to change any parameter for running the simulation. Little by little you can explore the configuration file, starting with the "Main" blocks and change some parameters to see what is happening. On a second time you can start playing with the advanced parameters that activate and control the behaviors of the particles.

Main blocks:▪ Time - Set the simulation time options, such as the beginning of the simulation, the duration of transport, the time step, etc.▪ Output - Options that control the record of the particle tracks in a NetCDF output file.


▪ Dataset - Management of the hydrodynamic dataset.▪ Release - Determine how and where the particles should be released.Advanced blocks:▪ Transport - Parameters for controlling the advection process, the dispersion, the vertical migration, the wind drift, etc.▪ Release - Additional ways for releasing particles, from zones, with position recorded in a text file or in a NetDCF file, etc.▪ Biology - Control the biological processes such as growth or cold water sensitivity, etc.Each block is fully described and commented in the block information area. As well, you

will find a description and the necessary explanations for each parameter in the parameter information area.

Do not forget to save the configuration file before going to the next step.

6) Step 2 : run simulation

6.1) From the GUI

Figure 4: Step 2, simulation

You may want to preview the simulated area. Click on the "Preview" button. The main interest in previewing the area is that the application will check if the simulation is correctly set up. Here "correctly" does not mean you made a relevant parametrization in terms of physics or biology, but at least the application had found all the parameters required for starting the simulation. More specifically, Ichthyop will attempt to read the geographical variables (longitude, latitude and depth) from the dataset in order to draw the area. It should also display the release and the recruitment zones if they have been defined and activated in the configuration file. Make sure what you see is what you expect, and go back to "Step 1: configure" in case not.

When the preview is satisfactory, click on "Run simulation" for starting the simulation. The progress bar will give an estimation of the remaining time for the simulation to complete. You can interrupt (but not pause) the simulation anytime by a click on "Stop simulation".

Depending the capabilities of your computer, the number of released particles, how many actions are implemented, etc. the simulation might requires a large amount of the available dynamic memory and the application might look like it is frozen. Wait until the


simulation run to completion. Refer to section "Java Heap Space" if the application crashes because of memory problem.

6.2) Batch mode

You may want to run a simulation without any GUI at all to give full power to computation. First, set up the configuration as usual with the configuration editor. Then save the file, close the application, open a command line, browse to the ichthyop/ directory and type:

java -jar ichthyop-3.#.jar /path/to/your/configuration/file.xmlApplication messages are reported back to the command line and in the ichthyop-log.txt

file. Refer to section "Java Heap Space" if the application crashes because of memory problem.

7) Step 3 : visualize results

Figure 5: Step 3, mapping

When the simulation is completed, the application automatically opens the current


Ichthyop output file for visualizing the results. If your computer is connected to Internet, you should see the map being centered above the simulated area. Otherwise, it only displays a Grey background.

You may want to skip that step or keep it for later. In that case, just click on "Close NetCDF" and go to any other steps or exit the application. Any time, you can go back to this step: click on "Open NetCDF" and select the Ichthyop output file you wish to visualize. When the NetCDF file is opened, the application brings you back to the exact point where it was when the simulation just completed.

The application offers two ways for visualizing the results : draw the particle trajectories with a Web Map Service or export the particle trajectories in a KMZ file that can be opened with Google Earth. Both functions are completely independent one from another.

7.1) Results

Ichthyop archives the particle trajectories in NetCDF format, a machine-independent data formats for sharing array-oriented scientific data. The NetDCF file is recorded in the output folder (set in the Output section of the configuration file) and the file name contains the date and time of creation of the file.

Default contents of the NetCDF output file: time of the simulation, longitude, latitude, and depth at particle position, and mortality status.

7.2) Set particle color

7.2.1) Default color

The "Default color" button determines the particle color for visualizing the trajectories.

7.2.2) Particle size

Particles are plotted as small circles. Particle size determines the diameter of the circle in pixel.

7.2.3) Color bar

Select in the Combo box a variable archived in the Ichthyop output file you wish to visualize as a tri-color range. The "Auto range" button will scan the values of the variable and suggest the following range : [mean - 2 * standard deviation; mean + 2 * standard deviation]. Do not forget to click on "Apply settings" for validating the changes of the color bar.

For taking off the color bar, select the "None" item in the Combo box and click on "Apply settings". A click on "Default color" button should also deactivate the color bar.

7.3) Make maps using Web Map Service

According to Wikipedia, a Web Map Service (WMS) is a standard protocol for serving georeferenced map images over the Internet.


Ichthyop provides three different WMS for displaying the ocean bathymetry and the cost line as a background of the particle trajectories.

Maps can be intuitively zoomed in and out with the mouse wheel and re-centered doing a mere drag and drop.

Depending on the quality of the Internet connection and how busy is the Web Map Server, the display of the background tiles might take a while or even not work at all. In that case, try again with a distinct WMS and change the zoom scale.

When the settings of the map looks satisfactory, click on "Make maps" button. Ichthyop will create a folder that has exactly the same name than the simulation NetCDF output file (without the .nc extension) in the output directory. Then maps are recorded in this folder as PNG pictures.

Again, depending on the computer capabilities and the number of particles, the map creation might require a large amount of the available dynamic memory and the application looks like it is frozen. Wait for the application to complete this step. Refer to section "Java Heap Space" if the application crashes because of memory problem.

7.4) Export trajectories to KMZ format

By default, Ichthyop records the particle trajectories in NetCDF format. It is perfectly adapted for archiving and sharing scientific data since it is a machine independent and array-oriented format. But it is not much handy for visualizing results.

Click on "Export to KMZ" button for recording the particle trajectories into a KMZ file. The file is recorded in the same directory than the Ichthyop output file, with the same name and the ".kmz" extension. KMZ format is the standard file format for visualizing georeferenced information with GoogleEarth.

Color settings (default color or color bar) and particle size will also be stored in the KMZ file.

When the export has performed, browse to the output folder and click on the KMZ file for launching GoogleEarth (assuming the program is installed on your computer).

8) Step 4 : animation


Figure 6: Step 4, animation

When the maps creation is completed, the application automatically opens the current simulation output folder for animating the maps (PNG pictures).

You may want to skip that step or keep it for later. In that case, just go to any other steps or exit the application. Any time, you can go back to this step, click on "Open maps" and select the simulation output folder that contains the PNG pictures you wish to visualize. When the folder is opened, the application brings you back to the exact point where it was when the map creation just completed.

Set the number of frames per second of the animation with the spinner.You can also create an animated GIF. The file is recorded in the same directory than the

Ichthyop output file, with the same name and the ".gif" extension.

9) Appendix

9.1) Install / update the Java Runtime Environment

The program has been developed with the Java language. Java is an object-oriented language developed by Sun Microsystems. The compilation of the source code provides byte code. The portability of the byte code might be the main advantage of Java. An interpreter of the byte code is necessary to run the program: the Java Virtual Machine (JVM). 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.

SDK: 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).


JDK: Java Development Kit. Former name for the SDK.In order to run the program, a JRE has to be installed on the local machine. A complete

SDK is not necessary unless you want to modify the source code and get a new byte code (see section 9.3 the source code). The byte code has been generated with SDK 1.6.0. The program has been tested with the corresponding JRE 1.6.0.

To check if Java is installed on your computer, and to get its version, Open a shell terminal (Linux and Mac users) or a command-line interpreter (Windows user. Menu Start > Execute > CMD.exe) and type: “java -version”. As an example, this is what the shell should return for Java version 1.6.0.

[user@local-host ~]$ java -versionjava version "1.6.0"Java(TM) SE Runtime Environment (build 1.6.0-b105)Java HotSpot(TM) Client VM (build 1.6.0-b105, mixed mode, sharing)

The latest JRE can be downloaded here. Follow the installation instructions.For Linux users, once the JRE installation is completed, you might have to update the

PATH variable. Open a new shell.▪ For a Bash shell. Edit .bashrc with any text editor and add the following lines at the end of the file.

if [ -z "${PATH}" ]then PATH="/usr/java/jre1.6.0/bin2”; export PATHelse PATH="/usr/java/jre1.6.0/bin1:$PATH"; export PATHfi

▪ For a csh shell. Edit .cshrc with any text editor and add the following lines at the end of the file.

set PATH=${PATH}:/usr/java/jre1.6.0/bin1

Save the modification and close the text editor. Then type in the terminal:[user@local-host ~]$ source .bashrc

or[user@local-host ~]$source .cshrc

You can now check if Java is properly installed and is recognized by the system by typing in the shell:

[user@local-host ~]$ java -version

9.2) Required libraries

Libraries are external programs necessary to run the application. The program uses them as tools to implement its own methods. All the libraries used in this application are distributed under the GNU Lesser General Public license.

In the lib folder of the distributed pack, you will only find the necessary Java archive

2 Adjust the path to match your own JRE bin directory


http://www.java.com/en/download/manual.jsp

(.jar) files to run the program. Please find below the list of the websites where complete distribution of the libraries can be found.

Swing application framework: https://appframework.dev.java.net/JDOM: http://www.jdom.orgTiming framework: https://timingframework.dev.java.net/NetCDF java library: http://www.unidata.ucar.edu/software/netcdf-java/SwingX Web Services: https://swingx-ws.dev.java.net/

9.3) Get the source code

The project is maintained from the Ifremer GForge gateway. The source code of the application is not public so please just email and ask for a copy at [email protected]

We can provide the source code as a NetBeans project, which makes it a lot easier for editing, testing and compiling the application.

10) AcknowledgmentsA first version of this program, released in June 2006, has been principally developed by

Christian Mullon and Philippe Verley. Funding was mainly from the Institut de Recherche pour le Développement (IRD) and the University of Cape Town (UCT), as part of Eco-up.

This release is part of PREVIMER project. The program benefited from a collaboration between people from the Laboratoire de Physique des Océans (LPO), from the Institut de Recherche pour le Développement and Ifremer (the French public institute for marine research).


https://timingframework.dev.java.net/

http://www.jdom.org/

https://appframework.dev.java.net/

ichthyop lagrangian tool for modelling ichthyoplankton

Documents