USER GUIDE. ICHTHYOP Lagrangian tool for modelling ichthyoplankton dynamics. Version: 3.1

Transcription

1 C O A S T A L O B S E R V A T I O N S & F O R E C A S T S ICHTHYOP Lagrangian tool for modelling ichthyoplankton dynamics USER GUIDE Version: 3.1 Contact: info@previmer.org Web site: Octobre 2012

2 TABLE DES MATIÈRES 1) Introduction...4 2) Changes from previous versions ) 3.0b to ) Version 2. to 3.0b...6 3) Installation ) Content of the distributed package ) First run ) Java heap space...7 4) Step 1 : configure ) New configuration file ) Content of the configuration file...8 5) Step 2 : run simulation ) From the GUI ) Batch mode ) Step 3 : visualize results ) Results ) Set particle color ) Default color ) Particle size ) Color bar ) Make maps using Web Map Service ) Export trajectories to KMZ format ) Step 4 : animation ) Appendix ) Install / update the Java Runtime Environment ) Required libraries ) Get the source code ) Acknowledgments...15 Historique du document Auteur Date Descriptif des modifications P.Verley 15/12/2009 Création du document P.Verley 17/06/2010 Rédaction du document P.Verley 30/10/2012 Mise à jour du document v3.1 Ichthyop User guide Page 2 / 15

3 1) Introduction The ICHTHYOP tool simulates the Lagrangian transport of particles using oceanographic fields produced by models such as ROMS, MARS 1 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 (info@previmer.org) 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 Ichthyop User guide Page 3 / 15

4 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) Changes from previous versions 2.1) 3.0b to 3.1 Bug fixes: Configuration panel - Crashed at displaying a block with no visible parameter. Backtracking - Used to crash for particles reaching the edge of the domain. Backtracking - Did not work in batch neither SERIAL mode. Backtracking - Time spans were incorrectly defined for KMZ export. Backtracking - Multiple release events was not supported. Zone editor - Ensured all floating numbers are dot-separated. Bathymetric mask was always enabled even though the checkbox was not selected. Release particles - Application did not warn the user when attempting to release particles under the bottom or above the surface. Dataset - Application used to throw an 'IOException, two many files opened' when working with many NetCDF input files. OPA NEMO - computation of the vertical velocity was not correct. Now requires fields e3u_ps & e3v_ps. OPA NEMO - Handles different formats for the gdept, gdeptw, e3t, etc. grid variables since it can vary from one configuration to an other. Configuration menu - Save as button did not work. Gregorian calendar - The time converter generated a 24h offset on leap years only. ROMS Dataset - Wrong calculation of the NEW type of vertical coordinate. New features: Coastline behavior - Now there is a parameter to control coastal behavior. Particle might beach, bounce on the coastline as a billiard ball or just standstill. Mars - Handles generalized sigma level (Mars V8). Mars - Handles rotated domains (lon & lat as two dimensional fields). WMS - Broaden the zoom range. Recruitment stain - Look for recruited particles within an area defined by a central point and a radius. NetCDF library updated to last version (4.2 April 2011). It handles NetCDF4. Ichthyop User guide Page 4 / 15

5 Dataset - Added an option to deactivate a thorough and expensive sorting of the NetCDF input files when the files are already chronologically sorted. GETM - Added a new module for integrating GETM hydrodynamics model outputs in Ichthyop. Not validated yet. To be considered as Beta development. ROMS - Accepts separated grid file. Buoyancy - Set particle density as an age function provided in an external CSV file. 2.2) Version 2. to 3.0b The 3.0b 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 3) Installation 3.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 Ichthyop User guide Page 5 / 15

6 lib/ - Necessary librairies to run the program input/ - Basic input file used for the examples readme.txt - information about the application 3.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.#.jar The main frame should show up. Let's create a new configuration file. Click on Menu > Configuration > New Select 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). 3.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.#.jar It means the initial heap size is 512 MB and the maximum heap size is 1024 MB. 4) Step 1 : configure Ichthyop User guide Page 6 / 15

7 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. 4.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. 4.2) Content of the configuration file Ichthyop User guide Page 7 / 15

8 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. Ichthyop User guide Page 8 / 15

9 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. 5) Step 2 : run simulation 5.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. 5.2) Batch mode You may want to run a simulation without any GUI at all to give full power to Ichthyop User guide Page 9 / 15

10 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.xml Application 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. 6) 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. Ichthyop User guide Page 10 / 15

11 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. 6.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. 6.2) Set particle color 6.2.1) Default color The "Default color" button determines the particle color for visualizing the trajectories ) Particle size Particles are plotted as small circles. Particle size determines the diameter of the circle in pixel ) 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. 6.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 Ichthyop User guide Page 11 / 15

12 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. 6.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). 7) 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). Ichthyop User guide Page 12 / 15

13 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. 8) Appendix 8.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 8.3 the source code). The byte code has been generated with JDK 1.6_u37. The program has been tested with the corresponding JRE 1.6_u37. 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_37. [user@local-host ~]$ java -version java version "1.6.0_37" Java(TM) SE Runtime Environment (build 1.6.0_37-b06) Java HotSpot(TM) 64-Bit Server VM (build b01, mixed mode) 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 Ichthyop User guide Page 13 / 15

14 end of the file. if [ -z "${PATH}" ] then PATH="/usr/java/jre1.6.0/bin 2 ; export PATH else PATH="/usr/java/jre1.6.0/bin 1 :$PATH"; export PATH fi 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/bin 1 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 8.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 (.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: JDOM: Timing framework: NetCDF java library: SwingX Web Services: 8.3) Get the source code The project is maintained from the Ifremer FusionForge gateway. The source code of the application is not public so please just and ask for a copy at info@previmer.org We can provide the source code as a NetBeans project, which makes it a lot easier for editing, testing and compiling the application. 9) Acknowledgments 2 Adjust the path to match your own JRE bin directory Ichthyop User guide Page 14 / 15

15 A 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. Version 3.0b 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). This 3.1 release has been developed in the Exploited Marine Ecosystem unit (UMR EME 212), and funded by IRD. Ichthyop User guide Page 15 / 15