Capsis hosts forestry models. These are generally empirical models: growth and yield models (plantation) or dynamics models (forests with possibly regeneration and mortality). They can be individual based or not, spatialized or not. The time step can be different for each model. The data structure and main processes of each model are unknown from Capsis. Capsis will only ask in time for model initialisation and evolution until a chosen limit.

We suggest you to discuss the integration of your model in Capsis, we will try to answer quickly. We will make sure together it is the right tool for you before you start. Anyway, this contact will be helpful for further assistance.

The Capsis charter states that the modeller is responsible for the integration of his model. To do the job, you will have to use some proposed development tools like editors, compilers and versioning programs. The main point is that you need to know the Java language (Capsis is developed in Java).

The easiest way is to come and meet the developper team in Montpellier. We periodically organise short training sessions and starting stages to accompany the incoming Capsis modellers.

If you are far from France, you may try to do it by yourself with the help of the Capsis developpers by mail, with the documentations on the Capsis web site (particularly the present documentation) and possibly with the help of a local Java developper in your own institution.

Each incoming modeller must accept the Capsis charter to join the Capsis community.

By accepting the charter, you can get access to the complete version of Capsis with all the source codes of all the models of all Capsis members. In return, all the other members will have access to your source codes.

All members must take care of the intellectual property of the others and can NOT distribute the complete version to someone outside the Capsis community. To distribute your model to your own partners, see how to build a specific installer with Capsis and your model only.

The source codes are shared by all the members of the Capsis community through a versioning system (Subversion / SVN). The SVN server contains the most up to date versions of all the files. Everyone has a working copy on his computer to work on them. When things are ok (at least compilation ok), each modeller can commit to the server its addings / modifications. From time to time, he can update his local copy to get the last developments by the Capsis developers and other modellers.

To get a login, see how to get a complete local copy and run your first compilation, see the SVN documentation.

Each growth model is integrated as a matching module in Capsis.

First you have to choose a package name (i.e. java package: no punctuation, all lowercase, not too long and explicit) and a Prefix (few letters, starts with an uppercase letter) for your module. A directory named like the module will contain all the source and resource files of your module (.java classes, translation files, etc.). The prefix will be used to name all your java classes, it should be unique.

For Instance : package mountain, prefix Mount

In this document, the package name will be replaced by <package> and the prefix by the letter x.

For instance, <package>.model.xModel corresponds to the full class name of a module. For mountain : mountain.model.MountModel.

Capsis is provided with ant included, without additional installation. Ant is a tool to automatize tasks like compilation and packaging. We provide an ant file (build.xml) with useful commands inside. One of them copies the template module with a new name and prefix.

You can use the create-module command of Ant to generate a copy of the template module. For that you have to type the following command from the capsis4/ directory.

On Linux/macOS:

sh ant create-module -Dname=packagename -Dprefix=Prefix -Dauthor=Author -Dinstitute=Institute

On Windows:

ant create-module -Dname=packagename -Dprefix=Prefix -Dauthor=Author -Dinstitute=Institute

Note: in the command line upper, Author and Institute must be replaced by your name and the name of your institute without blanks. You may use this syntax if needed: -Dauthor=F._de_Coligny. The '_' will be replaced by blanks.

If you encounter problems to type the commands in a terminal, check this help.

It is possible using the duplicate-module command of Ant to duplicate an existing module in order to create a new module having a new package name, a new module name and a new prefix.

See: How to duplicate a module

Choose a module which is similar to your module and copy the source file (*.java) of this module.

Then for each source file:

• Change the package name (1st line) : ex: package mountain.model
• Change the prefix
  • All classes should be renamed with the correct prefix
  • All references in the source codes should be updated to match the new names

Warning: Copying an existing module with a file manager may copy also directories named .svn/. These directories were created when the original module was added under the SVN versioning system. The copied .svn/ directories must be carefuly deleted from the new module (they refer to other class names and would cause trouble). They will be recreated when the new module is later added under SVN.

Add or edit the translation files in the module directory, usually xLabels_fr.properties and xLabels_en.properties (x is the package prefix). These files contain a line for each label to be translated: key = value. The keys have a conventional name based on the className requiring the translation. As the className prefixes changed, all the keys must be renamed with the new prefix.

Create or edit the file idcard.properties in the module directory. The following information should be updated in english.

Name = Mountain
Version = 2.1
Author = Benoit Courbaud
Institute = Cemagref
Type = MADD
Prefix = Mount
Package = mountain
MainClass = mountain.model.MountModel
BundleBaseName = mountain.MountLabels
Description = A Distance-Dependent Tree Model concerning mountain species (Spruce).

Note: The model name, version, author, institute, type and description are just for information (free fields). They should be provided and accurate because they will be shown to the users of Capsis.

The prefix, package, main class and bundle base name fields are administrative data, they will be interpreted by Capsis for module detection and are case sensitive. Check the uppercase / lowercase letters in these fields if the module is not detected by Capsis.

Reminder: package names are all lowercase, ClassName and Prefix start with an uppercase.

Add a line for the new module in the case it has been created by copying by hand an existing module (see section 2.3). The name to be specified is the package name all in lowercase letters.

If the new module has been created using the create-module (see section 2.1) or the duplicate-module (see section 2.2) commands of Ant, then there is nothing to do: the line for the new module has been added automatically to the capsis4/etc/capsis.models file.

Force a general recompilation with the following command (from the Capsis install directory).

On Linux/macOS:

sh ant clean compile

On Windows:

ant clean compile

If it does not end by BUILD SUCCESSFUL, correct the compilation errors until complete success.

When the compilation is correct, launch Capsis and try your module skeleton (should be detected by Capsis with the new name and work the same way than the template or copied module).

The new files and directories must be added to the SVN repository (svn add).

Use your svn client to add all new files and directories, then commit.

See How to add a new model in Capsis (part 2.)