AMAPstudio

## General

### 1.2 What is the license of Capsis ?

The core of Capsis4 is distributed under the LGPL free license (see the license file in the Capsis distribution). The Capsis4 modules (i.e. the forestry growth models) are distributed with custom licenses, see the license file in each module directory (e.g. capsis4/bin/mountain/). If such a module has no explicit distribution license file, it means it is not freely distributable and it is the property of its author.

## Technical basics

### 2.1 How do I type the commands under Windows ?

You need to open a terminal (also called a console or a shell under Unix).

• You may try Start > Execute and type cmd.
• You may alternatively find the terminal in Start > Programs > Accessories.

While in the terminal, you can change volumes by typing the volume name (e.g. C: or D:) and you can navigate through the directories with the cd (change directory) command.

E.g. to go to the capsis install directory (replace the directory names according to your installation path):

C:
cd \capsis

All ant commands must be typed from the install directory like the following example (to force the recompilation of all sources):

ant clean compile

Note: this command should finish with this message: BUILD SUCCESSFUL.

### 2.2 How do I type the commands under Linux ?

You need to open a terminal (also called a console or a shell).

E.g. under Linux Ubuntu, you may try Application > Accessories > Terminal.

While in the terminal, you can navigate through the directories with the cd (change directory) command.

E.g. to go to the capsis install directory (replace the directory names according to your installation path):

cd /home/coligny/workspace/capsis

All ant commands must be typed from the install directory like the following example (to force the recompilation of all sources):

sh ant clean compile

Note: under Linux, the commands should be prefixed by sh.

Note: this command should finish with this message: BUILD SUCCESSFUL.

### 2.3 How do I type the commands under Mac OS X ?

You need to open a terminal (also called a console or a shell). See Finder > Applications > Utilities > Terminal.

Then, see the Linux topic just above. You will use the same scripts than for Linux and launch them the same way with 'sh'.

cd .../capsis4
sh ant clean compile

## Java installation

### 3.1 Which version of Java must be installed ?

Since 26 July 2016, Capsis needs Java 1.8.x, also called Java 8 (e.g. 1.8.0_102…).

### 3.2 Do I have to install the whole JDK or is the JRE sufficient ?

It depends on your role in Capsis:

• Capsis end-users, who will simply use a(some) module(s) provided by a Capsis modeller partner through an IzPack installer, only need the Java Runtime Environment (JRE, contains no compiler) installed on their machine.
• Capsis modellers, who will get the entire version of Capsis with all the modules included, must install the Java Development Kit (JDK, including the java compiler).

### 3.4 Several vendors provide versions of Java, how can I choose ?

Only the versions of Java by Oracle (owner of Sun Microsystems who invented the language) are supported. On Mac OS X systems, use the Java provided by Oracle or Apple.

### 3.5 Which environment variables must I set to use Capsis ?

For both modellers and end-users, setting the PATH is enough: add the directory of the Java programs at the beginning of the PATH variable. Insert a semi colon “;” to separate from the trailing existing paths (e.g. for windows: C:/Program Files/Java/jdk1.8_102/bin;existing paths).

Note for Windows users: the environment variables may be changed by Configuration Panel > System > Advanced > Environment Variables

Note for Linux Ubuntu users: the PATH may be tuned in the file /etc/environment, e.g. below to be adapted for your machine (use a ':' between the paths), then type 'source /etc/environment'

PATH="/home/coligny/Applications/jdk1.8.0_102/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games"

Note: setting the CLASSPATH is not needed, neither for the end-users nor for the modellers (see the pages about compilation in the Capsis Documentation page).

### 3.6 How can I check if Java is well installed on my machine ?

To test the PATH, you can type java -version from whatever directory in a terminal opened after having set the PATH (for Windows: Start > Find/Execute > cmd > Enter). If you get a correct answer, java was found, your PATH is ok and this is enough to use the IzPack installer version of Capsis. If you have a “program not found” error message, check your java installation and PATH variable setting.

For Capsis modellers, also type javac -version to check if the compiler was found. If not, you may have a Java Runtime Environment in your PATH instead of a Java Development Kit.

An example of checking the jdk installation under a Linux terminal: both answer Java 1.8 → installation is correct

coligny@marvin-13:~$java -version java version "1.8.0_101" Java(TM) SE Runtime Environment (build 1.8.0_101-b13) Java HotSpot(TM) 64-Bit Server VM (build 25.101-b13, mixed mode) coligny@marvin-13:~$ javac -version
javac 1.8.0_101
coligny@marvin-13:~\$


### 3.7 When compiling on my Mac OS X 10.5, I have a 'bad class file... wrong version 51.0, should be 50.0'

Compiler output (extract):

[javac] bad class file:
...
[javac] class file has wrong version 51.0, should be 50.0
[javac] Please remove or make sure it appears in the correct
subdirectory of the classpath. 

Just do the following

# cd /System/Library/Frameworks/JavaVM.framework/Versions
# rm -f CurrentJDK
# ln -sf 1.8 CurrentJDK 

and it should take care of the problem.

Alternative option:

Use the Finder to go to Applications > Utilities and launch Java Preferences. Ensure that Java 1.8 is at the top of the list.

### 3.8 Capsis user interface is strange on 4k (high dpi) screens

Change the properties of the java program to tell the system to manage the problem.

## Capsis installation

### 4.1 How do I run the installer ? (jar version installer)

Run the installer by double clicking on it, then follow the instructions.

In case the installer does not start, make sure the correct version of java is installed on your computer and try to open the jar file with java.

// Run the jar installer from a terminal
cd .../directoryContainingTheInstaller/

java -jar instalerName.jar

### 4.2 The Capsis archive has been built under Linux, how can I unzip it under Windows ? (zip version installer)

The archive is a tar.gz, it can be unzipped under Linux with gnozip or FileRoller and under Windows with PowerArchiver.

### 4.3 Where must I install Capsis (zip version installer)

The Capsis archive contains a single directory named capsis4/ itself containing the whole platform. When unzipping, this directory can be located where you like in your file system. If you plan to develop under Capsis, locate the archive in your working directory (ex: c:/…/users/coligny/java/). For a simple use, Capsis can be installed anywhere.

## How to use Capsis

### 5.1 Ok, I've installed it, How does it work ?

Read the step by step tutorial to check the main features.

### 5.2 What models are available in my version of Capsis ?

The installers (zip or jar) distributed on Internet only contain the components under free license. This concerns the Capsis kernel, its pilots (graphical user interface, script mode), all the platform extensions and the applicative libraries. Concerning the modules, only some of them are distributed and not always with a free license (depending on the author's choice). Many are still under development. If you are interested by an undistributed module, contact directly the author by mail (see the project page).

### 5.3 I need more memory for my simulations, how can I do ?

The maximum amount of memory Capsis can require from the operating system during simulation is a variable. This variable has a default value depending on the machine architecture.

Use the setmem tool to change the default value to a bigger or lower value (in mega bytes) if needed.

Once setmem has been run, the given value will be used until the next change with setmem.

Capsis shows the current value for memory at launch time in the terminal.

// e.g. setmem under Windows: ask for 4Gb
> setmem 4096
Capsis will run with 4096 mega bytes available

// Restore default value
> setmem
Capsis memory reset to capsis.bat default value

// e.g. setmem under Linux: ask for 2Gb
> sh setmem.sh 2048
Capsis will run with 2048 mega bytes available

// Check the result
> sh capsis.sh -v
64 bits architecture - max memory: 2048 mega bytes
Capsis 4.2.2-5281


Notes

• setmem writes the value in a file called memory
• If the value is too small or too big, capsis may not start correctly.
• If the value is wrong (extra spaces or letters…), capsis will not start at all.

### 5.4 How can I open a viewer or a graphical output on a given step ?

Click (left) on a given step in the project manager, then double click in the lateral Selector on the chosen viewer. The viewer opens and synchronizes with the selected step (at every moment with the last selected step, named current step). Graphical outputs can be opened in the same way. A double-click on a new step of the project triggers synchronization on this step for the linked viewers and graphical outputs. Ctrl-clicking on a colored step closes all the associated tools (ex: curves are removed of graphics, viewers are closed…).

### 5.5 How to use a viewer simultaneously on two steps ?

Select a step, then choose a viewer in the Selector. Do it again on another step.

### 5.6 The project Manager (or the Selector, or the main Toolbar) have disappeared, how to make them come back ?

In the View menu, check the corresponding options.

### 5.7 Where is the log file ?

Capsis writes some messages into a log file. This file is named capsis.log and is located in capsis4/var/.

You may open it from the user interface with Tool > Log file.

You may also open it with a simple text editor (Textpad, SciTE…).

### 5.8 How can I launch my JUnit test ?

To write JUnit tests, see the related documentation.

To launch the test: capsis4/test/src/douglas/DouglasTest, type the following from capsis4/

ant runtest -Dtest=douglas/DouglasTest

Then to check the results:

firefox test/report/index.html

### 5.9 How can I ensure my tests are run periodically ?

Capsis tests (in test/src/) are compiled and run at each commit on the Capsis SVN server by a developer or a modeller. You must ensure the test compiles and runs in your local copy, then add it and commit it to svn.