Installing Java

Java is usually already installed in most computers. However, for Capsis, you need a version 1.8.xxx of Java. To check the version of Java on your computer,

• Open a MS-DOS command prompt (on Windows)
• type : java –version

If you don’t have a Java 1.8.xxx on your computer, download a “Java SE Runtime Environnement 8” on your machine, https://java.com/en/download/manual.jsp (for Windows choose an offline version) https://www.oracle.com/java/technologies/javase-jre8-downloads.html (subscription is mandatory on this site)

Installing Capsis

Run the Capsis installer.

You can download it at this link : download capsis

• Double click on the installer file : capsis-Samsara2_4.2.7-22961_setup.jar
• Choose a name and location for your Capsis folder (for example /My documents/Capsis).
• Caution, the path to your Capsis folder must not contain names with space, special characters or accents.
• Remember this location and path, because you’ll need it later.
• For more information, see : http://capsis.cirad.fr/capsis/documentation/installation_guide

Be careful : the Capis version must be compatible with the R package version you install. The last stable version of {martelosim} require version 4.2.7-22961 for Capsis.

To check the version of Capsis on your computer you can go with an explorer into your folder Capsis and open the text file “revision”. Alternatively, when Samsara is running, a message is displayed on the terminal indicating the version.

If you do large simulations, there can be a problem of insufficient RAM (Random Access Memory) allocated to Capsis. If it is the case, you can increase it (within the limit of your machine).

The RAM allocated to Capsis depends on your machine. It is indicated in Megabytes in the text file “memory” in your Capsis folder. Alternatively it is also written in the MS-DOS terminal when you launch Capsis directly :

You can increase it (within the limit of your machine) typing in the terminal the command “setmem” with the nb of Megabytes you want (too large a number can slow calculations):

Installing R and Rstudio

• Link to install R : https://cran.r-project.org/bin/windows/base/

• Link to install RStudio : https://posit.co/download/rstudio-desktop/

Installing the R package {martelosim}

Open R studio or close any project and paste one of the following commands in the console:

If you are a marteloscope instructor

You should install the last stabilized version of the package, copying and pasting the command line:

install.packages(
    'martelosim', 
    repos = c('https://inrae.r-universe.dev', 'https://cloud.r-project.org')
)

If you are a researcher

You can install the current development version with the command line:

if (!require("remotes", quietly = TRUE)) {install.packages("remotes")}
remotes::install_url(
    'https://forge.inrae.fr/lessem/rpackages/martelosim/-/archive/dev/martelosim-dev.zip'
)

Restart R either in closing and reopening RStudio or by copying and pasting the command .rs.restartR()

If you want to check the version of the package on your computer, type the command: packageVersion("martelosim")

Create a directory and an R project to simulate a marteloscope workshop on the marteloscope of your choice

If you don’t have a marteloscope yet, you can use data from the marteloscope of Prelenfrey which are included in the package.

On your windows explorer create a directory where you will store all your marteloscope exercises, and a subdirectory for each marteloscope. Ex: martelosim_Workshops/Prelenfrey

Caution: folder and file names in the path to your files should not include any space or special character. If necessary change the names on your computer.

• Open RStudio

  • File/New project (in the upper left menu bar)

  

  • New Directory

  

  • Martelosim workshop

  

  • Fill out the workshop creation dialog box
    

  

  • Directory name : we suggest that you create a directory named with the marteloscope and the date of your exercise: ex Prelenfrey_2024-11-19. You can create right away a succession of directories to organize your marteloscopes and future workshops. (ex : martelosim_Workshops/Prelenfrey/Prelenfrey_2024-11-19)
  • Create project as subdirectory of : indicate the folder in which you want to store the directory of your exercise : ex martelosim_Workshops/Prelenfrey
  • Marteloscope site name : Repeat the Marteloscope name : ex Prelenfrey
  • Workshop Date : Repeat the workshop date : ex 2026-06-26
  • Capsis path : Click on Browse and develop the pathway up to your Capsis folder and select the file capsis.sh
  • Marteloscope inventory path : Click on Browse and develop the pathway up to your Excel data file. If you are making a test with Prelenfrey, you don’t need to fill this item.(ex: Data_Marteloscope_Prelenfrey_en.xlsx)
  • Create project

The R studio interface opens

martelosim project

• The dialogue box creates a folder for your exercise (ex: Prelenfrey_2026-06-26) In this folder, you find
  • The R project for the exercise (ex: Prelenfrey_2026-06-26.Rproj)
  • Subfolders : scripts, data, martelages, reports
• RStudio opens your project (ex: Prelenfrey_2026-06-26.Rproj).

Run the script 01_start.R

This script prepares the files describing your marteloscope initial conditions. You have to run it once each time you prepare a new exercise.

If R studio has not opened script_01_start.R, go in the RStudio bottom right window. Select the tab Files, open the directory scripts and double click on the file scripts/01_start.R

The script is composed of lines of comments in green starting by a sharp #; and blocks of codes in black with text variables in green surrounded by quotation marks “” and logical variables in blue. You can check the values of text and logical variables that have been set by default or if necessary you can modify them.

To run a block of code, click above the block and select the tab “run”. Alternatively, you can click above or at the beginning of a line of code or above a block and type Ctrl Enter.

• martelosim::martelosim_options() displays the information you entered previously in the dialog box. You can check them and correct them if necessary.

• martelosim::new_inventory() creates an inventory for this project, in the subdirectory “data” of your exercise and checks its name :
  • inv_site
    • inv_site = “new” creates an empty inventory to fill.
    • inv_site = “copy” copies an inventory file to the present project. The file path is specified in inv_file.
    • inv_site = Prelenfrey will copy the example file of Prelenfrey stored in the package.
  • The option lang = getOption("mart_lang") : the language (English or French) will correspond to what you have indicated previously in the create marteloscope box.
  • If the option open = TRUE, then the Excel file is open and you can check the Prelenfrey data file. You have to close the Excel file before continuing running the R code.

• martelosim::build_samsa2_files()
  • Creates the files of initial conditions used by the simulator Samsara2 and store them in the subdirectory data. These files will be used by the simulator Samsara2 to make simulations.
  • Creates in the folder markings, the default marking file markings/Prelenfrey_2024-11-19_Marking_Free_Growth.xlsx which can be used on the field to enter marking data for the marking group Free_Growth. Have a look at the results produced on the Console : it will give you indications about the files that were created and potential default values that were used if some information is lacking in the Excel data file.
  • Creates in the folder markings, the default silviculture file markings/Prelenfrey_2024-11-19_Silviculture_Free_Growth.xlsx which is used for the “expert” mode of silviculture parameter. It can be used on the field to detail silvicultural interventions that will be performed during the simulation for the marking group Free_Growth. More details are provided in the dedicated section (see Define the silvicultural interventions performed during the simulation).

• martelosim::prepare_samsara() complements field data if your marteloscope is not rectangular or if you have not measured the regeneration on the field.
  • the option create_periphery = TRUE means that virtual trees will be created in a rectangular plot around the marteloscope to manage border conditions for light calculations
  • The option create_virtual_saplings = TRUE means that virtual saplings in balance with the adult tree stand and ground light conditions are created.

• martelosim::martelo_maps() creates a pdf file with maps to help you locate interesting trees on the field. These maps are stored in the folder reports. (ex: reports/Prelenfrey_Maps.pdf).

• navigateToFile(« script 02_test.R ») opens the script used for the next step (alternatively, you can also open it directly by double clicking on it on the right panel).

Run the script 02_test.R

This script runs marteloscope marking exercise with a random marking in order to test the whole process.

• martelosim::random_marking() creates a virtual marking file in the subdirectory markings where trees have been selected randomly. It makes a marking file similar to a field marking file. In our example: markings/Prelenfrey_2024-11-19_Marking_Random.xlsx
• MarkingGroups <- c("Random") means you are working with marking made by the virtual marking group called Random

• write_samsara_cmd() creates the file data Prelenfrey_CommandFile.txt in the data folder. This command file plans all the simulation steps for Samsara2.

• marking_groups = MarkingGroups means that the simulation will be made for the groups named in the MarkingGroup vector

• thinning_time = 10 means that a thinning will be applied every 10 years. The first one will be the field marking, the newt ones will be made using the Multicriteria_Thinner of Samsara2 mimicking the same kind of marking strategy than the field marking.

• evolution_time = 20 means that the simulation will cover 20 years.

• silviculture = "auto" means that the parameters of the Muticriteria_Thinner will be automatically deduced from the field marking. Alternative is silviculture = "expert", which requires to fill the silviculture file (see Define the silvicultural interventions performed during the simulation).

• run_samsara() runs the simulations for the the random marking and stores result files in the folder data/Output. It takes approximately 1 minutes for a 20 year evolution simulation.

• martelo_report() writes a PDF report for the marking group and stores it in the “reports” folder. In our example: “reports/Prelenfrey_2024-11-19_Random_Report.pdf”. The option:

  • marking_groups = MarkingGroups means that the report will be made for the groups named in the MarkingGroup vector.
  • dendrometry = TRUE, etc… means that the report will include pages for all these topics.
  • multi = TRUE means that you want a multiple report whereas multi = FALSE means you want individual reports for each group

The scripts 03_workshop.R is for a real marking exercise, not needed if you just want to test the package on a virtual marteloscope with a random marking.

Testing the package on your own marteloscope

Objectives:

• Check that the data in your marteloscope is correctly formatted
• Check that the process is running correctly on your marteloscope
• Test the production and storage of a field marking data file on tablets
• Test the transfer of data between tablets and computer
• Test the whole process of simulation based on a field marking

- `marking_groups = MarkingGroups` means that the simulation will be made for the groups named in the MarkingGroup vector.
- `thinning_time = 10` means that a thinning will be applied every 10 years. The first one will be the field marking, the newt ones will be made using the Multicriteria_Thinner of Samsara2 mimicking the same kind of marking strategy than the field marking.
- `evolution_time = 20` means that the simulation will cover 20 years.
- `silviculture = "auto"` means that the parameters of the Muticriteria_Thinner will be automatically deduced from the field marking. Alternative is `silviculture = "expert"`, which requires to fill the silviculture file (see `Define the silvicultural interventions performed during the simulation`).

Preparing your computer and your tablets before the workshop

On your computer:

• Create a directory for your field exercise (ex: martelosim_Workshops/MyMarteloscope/MyMarteloscope_YYYY-MM-DD)
• Run the script 01_start.R to prepare the initial state files required for the simulations.
• Run the script 02_test.R to check that everything is working with a random marking

On your tablets: Transfer from your computer to the tablets the empty marking file YourMarteloscopeName_YYYY-MM-DD_Marking_Free_Growth.xlsx and change the names replacing Free_Growth by the name of each tablet Alternatively, prepare your tablets with the I+Trainer software.

Import marking files, make the simulations and produce the reports

At the beginning try not to have too many groups in the field: the more groups there are, the more manipulations there are to do.

• Be very careful that every group save correctly their marking file on their tablet. If you use the I+ trainer, be especially cautious that the csv result file is saved correctly using : Save results on the device -> Save final results on the SD card, create PDF and restart the application
• Transfer the marking files from the tablets to your computer.
• Run the script 03_workshop.R to make the simulations and produce the pdf reports.

Be careful that file names are correct and that you have written all the group names in the vector MarkingGroups.

• Visualize the pdf simulation report of each group and transfer it back to the group’s tablet.
• To share and discuss the results, if you can gather in a room, the best is to project simulation reports using a video-projector. Alternatively, you can print the reports using a portable printer or simply transfer them back to the tablets.
• After the exercise, you can transfer the reports of all groups to all the participants by email.

The transfer of files between tablets and computer is a bit of a pain but is doable. If you are well prepared, the whole process should take about 30 minutes.