Home >> Documentation >> Getting started with Osmose 3: install and run

Getting started with Osmose 3: install and run

Object-oriented Simulator of Marine ecOSystem Exploitation

(This document is a draft and we keep udating it)

Introduction

OSMOSE is a computer program whose purpose is to simulate fish populations and their interactions with their biotic and abiotic environment. It is a spatial, multispecies and individual-based model which assumes size-based opportunistic predation based on spatio-temporal co-occurrence and size adequacy between a predator and its prey. It represents fish individuals grouped into schools, which are characterized by their size, weight, age, taxonomy and geographical location, and which undergo major processes of fish life cycle (growth, explicit predation, natural and starvation mortalities, reproduction and migration) and fishing mortalities (Shin and Cury 2001, 2004).
OSMOSE is distributed as Java code which is governed by the CeCILL-B license under French law and abiding by the rules of distribution of free software.  You can  use, modify and/ or redistribute the software under the terms of the CeCILL-B license as circulated by CEA, CNRS and INRIA at the following URL http://www.cecill.info

Required sofwares

OSMOSE is a Java application. In order to compile and run a Java application you need at least a JDK (Java Development Kit). Using an IDE (Integrated Development Environment) such as Netbeans is strongly recommended as it makes life much easier when it comes to explore or modify the source code.

Install / update the Java Development Kit

The program has been developed with the Java language. Java is an object-oriented language initially developed by Sun Microsystems that is now supported by Oracle. 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.
  • JDK: Java 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).
  • SDK: Software Development Kit. Synonym of JDK.

In order to run the program, only a JRE has to be installed on the local machine, which is the case on most computer nowadays. 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.7.0.

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

Nonetheless a complete JDK is necessary in order to modify the source code and get a new byte code.

The latest JDK can be downloaded here.

Just follow the instruction.

Install Netbeans

Even though the JDK is sufficient in itself to compile and then run the OSMOSE application, it is much more convenient to work with a full IDE as it provides all the basic functions and tools a developer needs for programming with Java. Netbeans and Eclipse are the most common IDE when it comes to Java. Here we will examplify the installation and the use of Netbeans, as this IDE is designed in Java and for Java, but most of the steps could be easily reproduced with any other IDE.

You can download Netbeans here.

As you go through the installation process, you will be asked whether you want to install the JUnit library. You may accept or not, it does not matter here.

Install JDK and Netbeans together

Oracle allows you to install directly JDK and Netbeans through the same installation wizard. In the event neither JDK nor Netbeans is installed on your computer, it might a convienient intallation option:
http://www.oracle.com/technetwork/java/javase/downloads and look for JDK + Netbeans bundle.

Just follow the instruction.

Check JDK and Netbeans installation

If you can open Netbeans, it means the installation of both JDK and Netbeans has been successful as Netbeans is a Java application.

Then check Menu > Tools > Java Platform

The Java Platform Manager opens and you should see JDK 1.7 (Default) as your default platform name.

Required skills

Java

Osmose is a complex multi-species eco-systemic model, written in Java, with no Graphical User Interface (GUI). It is not an all-inclusive piece of software that only requires a few mouse clicks to get instantaneous results. We purposefully decided to give up on the GUI firstly because this is troublesome and pricy to maintain and most importantly because we want the user to look at the source code (no black box) and get their hands dirty.

Knowing the basics in Java will greatly help in understanding how the model works and allow you to be very efficient when it comes to debug your configuration. Many tutorials are available online. For French reader, openclassrooms.com is a good option. As for  books, there are plenty of options as well. One of the most popular might be Thinking in Java by Bruce Eckel.

Spreadsheet

In order to handle efficiently the input and output files (CSV format), good knowledge of any Spreadsheet software is a must.

R

You will need R for using the osmose2R package developed by Ricardo Oliveros-Ramos and Laure Velez and for calibrating OSMOSE with the evolutionary algorithm (EA) developed by Ricardo O.-R. Both the osmose2R package and the EA will come with their own documentation.

NetCDF

Osmose manipulates NetCDF files for inputting the plankton biomass and generates some NetCDF output files as well. You must understand what a NetCDF file is and how to visualize it.

First run

To have OSMOSE running on your computer, there is three main steps to follow: get Osmose source code ; get Osmose default configuration ; run Osmose default configuration.

Get Osmose source code

Go to the downloads page and download the latest Osmose source code (e.g. osmose-v3.zip). Save the ZIP file on your computer and unzip it. On your computer, in the new unzipped folder, you should see the following files and folders:

  • filePath.txt the file that indicates where is the OSMOSE input directory
  • lib/ folder contains the required libraries
  • src/ contains the source code
  • nbproject/ is the Netbeans configuration folder
  • build.xml, a Netbeans configuration file

This folder is organized as a Netbeans project. Open Netbeans, menu File > Open Project... Browse for the unzipped folder and click on "Open Project" bouton.

You can expand the 'Osmose stable 3' project on the Projects tab on the upper left part of the Netbeans main window to see the source code hierarchy and the libraries. You can also close the Start Page on the Netbeans main panel.

Get Osmose default configuration

The OSMOSE application needs a set of configuration file (i.e. some input parameters) for running a simulation. We created a default configuration, called 'osm' based in the Benguela ecosystem. Go to the downloads page and download the default OSM configuration (e.g. config-osm-v3.zip). Save the ZIP file on your computer and unzip it. On your computer, in the new unzipped folder, you should see the following files and folders:

  • osm_all-parameters.csv
  • osm_param-fishing.csv
  • osm_param-grid.csv
  • osm_param-init-pop.csv
  • osm_param-ltl.csv
  • osm_param-movement.csv
  • osm_param-mpa.csv
  • osm_param-natural-mortality.csv
  • osm_param-output.csv
  • osm_param-predation.csv
  • osm_param-reproduction.csv
  • osm_param-species.csv
  • osm_param-starvation.csv
  • osm_ltlbiomass_integrated.nc
  • grid-mask.csv
  • fishing /
  • maps /

A complete description of the configuration file and the input parameters is provided here.

Run OSM default configuration

From Netbeans.

First of all, open Osmose project, as explained in previous section 'Get Osmose source code'. Netbeans Menu > File > Open Project... Browse to the Osmose source code folder and click on "Open Project" bouton.

Click on the Files tab next to the Projects tab on the upper left part of the Netbeans main window.

Edit the file filePath.txt You should have the following line uncommented:

C:/user/philippe/osmose/config-osm-v3/osm_all-parameters.csv (carefull with underscores and hyphens)

Change it so that it indicates the location of the folder where you retrieved the default configuration 'osm' .

Three ways to run the application:

  1. switch back to the Projects window, right click on the osmose-trunk project > Run
  2. click on the green arrow 'Run project (osmose-trunk)' in the menu bar
  3. Menu > Run > Run project (osmose-trunk)

You should see the following logs in the Ouput console:

When the simulation is completed, you should have an output/ folder in the osm configuration folder with a set of indicators. A full description of the outputs is provided here.

Getting further

Read the description of the input parameters here.

Read the description of the output parameters here (the document does not exist yet).

Category: