3 Ichthyop console
In this section, the Ichthyop console is described.
3.1 Configuration
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.
3.1.1 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.
3.1.2 Content of 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.
Parameters cannot be added from within the Ichthyop console. Only paramters that are already defined on the XML file can be edited using the console
3.2 Zone definition
In Ichthyop, the user can define zones, either release zones or recruitment zones.
The zones can be edited using the GUI, as shown in Figure 3.1
3.2.1 Adding, removing and renaming zones
The number of zones is managed on the left part of the panel.
New zones can be added by clicking the 
button. When a zone is selected, it can be removed by clicking on the 
button.
The reordering of the zones is achieved by clicking on the 
and 
buttons.
When double-clicking on the name of the zone on the left panel, the user can edit the zone name.
3.2.2 Editing a zone
When a zone is selected, the user can edit different parameters associated with the zone.
First, the user can enable or disable a zone by clicking on the {guilabel}Enabled tick box.
The zones are defined by providing the points coordinates. Points can be added, removed and reordered by using the , , and buttons, respectively. The user can also change the format of the points coordinates by clicking on the radio buttons in the Options bottom panel.
Ichthyop defines two types of zones: one for release (see Section 5.2) problèmeand one for recruitment purposes. This type is chosen by using the Type of zone combo box. For release zones, the user can specify the number of particles that will be released in the zone (only if the user_defined_nparticles parameter is set equal to true, cf Section 5.2). It is done by filling the Number of released particles textbox and pressing ENTER
Each zone is associated with a color, that will be used to its representation in the graphical interface during the preview and the display of the simulation results. This color can be edited by using the 
button.
In the case of 3D simulations, you can specify the depth range to use in the zone. To activate this feature, click on the Activated tick box of the Thickness panel. You can provide the lower and upper depth that must be considered in the given zone (negative values).
In 3D simulations, you can also specify the bathymetric range that you want to include, for instance if you want to release particles only on the ocean shelf (i.e depth less than 200m). This can be done by activating the feature by clicking on the Activated tick box of the Bathymetric mask panel.
3.3 Running
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.
3.4 Visualize results
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.
3.4.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.
3.4.2 Set particle color
The Default color button determines the particle color for visualizing the trajectories.
Particles are plotted as small circles. Particle size determines the diameter of the circle in pixel.
To use a colorbar, 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.
3.4.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.
3.4.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).
3.5 Animation
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.
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.