Script Mode

Script Mode

Introduction

In Capsis, there are 2 user modes:

interactive mode: to work in a graphical environment with menus and dialogs
script mode: to execute particular scripts written in java or groovy which describe long and repetitive simulations. The results of these simulations are saved in files to be reevaluated later in Capsis or with other analysis or statistical tools (such as R).

To use the script mode with a particular module, the module should implement particular classes. Then scripts can be written in Java or in Groovy.

Adapting the module classes

We consider the module « maddmodule » with the prefix “Madd”.

We need to adapt 2 classes in the maddmodule/model/ directory.

InitialParameters class

The 'InitialParameters' object contains the module parameters (i.e. model configuration: names of the files to be loaded, values for the model parameters…) and is responsible for creating the initial scene in the project (returned by getInitScene ()).

A constructor may be implemented to offer a convenient way to set the initial values.

An example of creation of a MaddInitialParamaters instance with a constructor taking an inventory fileName:

InitialParameters ip = new MaddInitialParameters (model, 
    "/home/coligny/java/capsis4/data/MaddModel/CORRUAZ AVANT MARTELAGE94.inv");

EvolutionParameters class

The 'EvolutionParameters' object describes the parameters needed to run an evolution stage. Commonly, it is a target date (a year…) to be reached by the evolution stage. We usually add a constructor to set directly at construction time the needed limit parameter(s):

public MaddEvolutionParameters (int age) throws Exception {
    this.age = age;
}

To use it:

EvolutionParameters ep = new MaddEvolutionParameters (50);

Build a script

Script are commonly written in the myscripts directory.

If you have questions about the script structure, see the Script structure considerations.

A simple script

package maddmodule.myscripts;
 
import maddmodule.model.MaddEvolutionParameters;
import maddmodule.model.MaddInitialParameters;
import capsis.app.C4Script;
import capsis.kernel.Engine;
import capsis.kernel.Step;
 
 
/**	A Capsis script, type 1 (preferred):  
 * 	(a) extends nothing particular, 
 * 	(b) with a main method (can be launched directly with java), 
 * 	(c) uses an instance of C4Script. 
 * 
 * 	Two ways to launch it:	
 * 	(1) sh capsis.sh -p script maddmodule.myscripts.SimpleScript 
 * 	(2) java -cp class:ext/* maddmodule.myscripts.SimpleScript 
 * 
 * 	@author F. de Coligny - 16.9.2010
 */
public class SimpleScript {
 
	public static void main(String[] args) throws Exception {
 
		C4Script s = new C4Script("maddmodule");
 
		MaddInitialParameters i = new MaddInitialParameters (s.getDataDir() + "/maddmodel/A.inv");
 
		// init
		s.init(i);
 
		// evolution
		Step result = s.evolve(new MaddEvolutionParameters (200)); 
 
		// save
		Engine.getInstance ().processSaveAsProject (s.getProject(), 
					s.getRootDir() + "/tmp/TEST.PRJ");
 
	}
 
}

Simple scripts can use the C4Script class:

The C4Script takes the model package name (e.g. maddmodule, lerfob.fagacees) as parameter in its constructor.
The script is initialised with the init method.
The evolution stages are done with the evolve method.
At the end, we save the project in order to be able to reload it in Capsis later. Often we will use instead an export to an output file that will be the result of the script (see below LubExportAdult at the end of Script2).

A more complex example

package luberon;
 
import jeeb.lib.util.Log;
import jeeb.lib.util.StatusDispatcher;
import luberon.extension.ioformat.LubExportAdult;
import luberon.model.LubModel;
import luberon.script.LubEvolutionParameters;
import luberon.script.LubInitParam;
import capsis.extension.memorizer.FrequencyMemorizer;
import capsis.kernel.Engine;
import capsis.kernel.EvolutionParameters;
import capsis.kernel.GScene;
import capsis.kernel.GenericExtensionStarter;
import capsis.kernel.InitialParameters;
import capsis.kernel.Step;
import capsis.script.C4Script;
import capsis.extension.intervener.DHAThinnerStarter;
import capsis.extension.intervener.DHAThinner;
 
public class Script02  {
 
	public void run () throws Exception {
		StatusDispatcher.print ("Script02 - running...");
 
		// 1. Load model
		C4Script sc = new C4Script("luberon");
		LubModel model = (LubModel) sc.getModel();
 
		// 2. InitialParameters creation
		Log.println("luberon" , "Start");
 
		InitialParameters ip = new LubInitParam (model,
				1,
				true,
				50.0,
				LubInitParam.PollenDispersal.TWO_CELL_NEIGHBORHOOD,
				sc.getDataDir() + "luberon/ESEB2009/LuberonInventESEB_E1_R0.inv"
				);
 
 
		// 3. Init project with a particular frequency memorizer
		FrequencyMemorizer m = new FrequencyMemorizer ();
		m.setFrequency(1);
		sc.init(ip, m);
 
		// 4. Evolution 
		EvolutionParameters ep = new LubEvolutionParameters (1885, false);
		Step step = sc.evolve (ep);
 
		// 5. Intervention : cutting the G0
		Intervener thinner = new DHAThinner(DHAThinner.AGE, 49, 500);
                step = sc.runIntervener(thinner, step);
 
                // 6. Evolution after intervention
		EvolutionParameters ep = new LubEvolutionParameters (1910, false);
		Step step = sc.evolve (step, ep);
 
		// 7. Export data
		StatusDispatcher.print ("Exporting Stand...");
		GScene stand = step.getScene();
		GenericExtensionStarter starter = new GenericExtensionStarter();
		starter.setStand(stand);
		LubExportAdult adultExporter = new LubExportAdult(starter);
		adultExporter.save(sc.getRootDir() + "/tmp/G0.txt");
 
		// 8. For example : save the whole project
		Engine.getInstance ().processSaveAsProject (sc.getProject(), sc.getRootDir() + "/tmp/script02.prj");
 
		StatusDispatcher.print ("Script02 - done");
 
	}
 
 
    public static void main (String [] args)  {
 
    	Script02 s = new Script02();
		try {
			s.run();
		} catch (Exception e) {
			e.printStackTrace();
		}
 
 
	}
 
}

Intervention are initialised and called with the following code:

Intervener thinner = new DHAThinner(DHAThinner.AGE, 50, 500);
step = sc.runIntervener(thinner, step);

The method returns the resulting step. To do a new evolution, we need to specify the starting step :

// Evolution after intervention
EvolutionParameters ep = new LubEvolutionParameters (1910, false);
Step step = sc.evolve (step, ep);

Launching the script

For a script in maddmodule/myscripts/SimpleScript, we need to type in the Capsis directory:

Under Linux or MacOS:

sh capsis.sh -p script maddmodule.myscripts.SimpleScript

Under Windows:

capsis -p script maddmodule.myscripts.SimpleScript

Table of Contents