Back to Documentation

Tutorial 1: Getting started

This tutorial aims at

  • presenting the main concepts of OpenMOLE,
  • giving example of codes illustrating these concepts
  • and finally running a workflow locally!

The prototype

A prototype is a kind of typed variable. It is composed of a name and a type among (non exhaustive list):

  • Integer
  • Double
  • BigInteger
  • BigDecimal
  • String
  • File
  • ...

A value can be assigned to a prototype.
A prototype navigates from task to task in the workflow (see the next section).

Prototype definition examples:

import org.openmole.core.implementation.data.*

proto1 = new Prototype("proto1", Integer)
proto2 = new Prototype("proto2", BigDecimal)
proto3 = new Prototype("proto3", File)

The task

A task is the smallest element that can be constructed but also the most important. It contains what is really run (a shell command, an executable, a script, ...). A task can:

  • receive inputs,
  • send outputs,
  • execute a piece of running instruction.

The tasks are derivated from a generic task, which enables to achieve these basic actions. Then a collection of tasks have been extended (and can easily be extended!) as plugins to manage specific stuff. For instance the GroovyTask enables to run Groovy code, the SystemExecTask enables to run external executable.
See the list of task plugins

Example of the declaration of a GroovyTask taking a prototype as input and sending an other which equals twice the input:

import org.openmole.core.implementation.data.*
import org.openmole.plugin.task.groovy.*

proto1 = new Prototype("proto1", Integer)
proto2 = new Prototype("proto2", Integer)

myGroovyTask = new GroovyTask("myGroovyTask")
myGroovyTask.addInput(proto1)
myGroovyTask.addOutput(proto2)
myGroovyTask.setCode("proto2 = proto1 * 2")

The Capsule

A Capsule represents a structure, which can:

  • be connected to other Capsules by means of transitions (see next section)
  • encapsulate a Task

Task capsule definition examples:

import org.openmole.plugin.task.groovy.*
import org.openmole.core.implementation.capsule.*

myGroovyTask = new GroovyTask("myGroovyTask")
myGroovyTaskCapsule = new Capsule(myGroovyTask)

The transition

A transition describes the precedence relationship between two capsules. The variables migrate from a TaskCapsule to another through the transitions. 

import org.openmole.core.implementation.data.*
import org.openmole.core.implementation.transition.*
import org.openmole.core.implementation.capsule.*
import org.openmole.plugin.task.groovy.*

proto1 = new Prototype("proto1", Integer)

myFirstTask = new GroovyTask("myFirstTask")
myFirstTask.addInput(proto1)
myFirstTask.addOutput(proto1)
myFirstTask.setCode("proto1 = proto1 * 2")

mySecondTask = new GroovyTask("mySecondTask")
mySecondTask.addInput(proto1)
mySecondTask.setCode("proto1 = proto1 * proto1")

myFirstCapsule = new Capsule(myFirstTask)
mySecondCapsule = new Capsule(mySecondTask)

new Transition(myFirstCapsule,mySecondCapsule)

The exploration sampling

An exploration sampler is a description of how to explore a space of parameters. Different strategies exist to achieve this (see the sampling plugin list).
A plan is defined by means of a collection of factors. A factor represents a prototype that varies in an certain range of values. These ranges are represented by Domain objects (see the domain plugin list).

An example of specific but popular plan: the complete plan:

import org.openmole.core.implementation.data.*
import org.openmole.plugin.domain.range.*
import org.openmole.core.implementation.sampling.*
import org.openmole.plugin.sampling.complete.*

proto1 = new Prototype("proto1", Integer)
proto2 = new Prototype("proto2", Double)

factor1 = new Factor(proto1, new IntegerRange("0","10","2"))
factor2 = new Factor(proto2, new DoubleRange("0.0","1.0","0.1"))

sampling = new CompleteSampling(factor1,factor2)

The exploration task and the exploration transition

A particular Task (the exploration Task) combined with a particular transition (the exploration transition), offers to explore space of parameters, which have been previously defined in an exploration plan (as described in the previous section). The Task at the end of an exploration transition will be executed for each explored value of space of parameters and eventually in parallel on a grid (see further tutorials).

An example of groovy task that will be executed for any combination of values of the sampler:

import org.openmole.plugin.domain.range.*
import org.openmole.plugin.sampling.complete.*
import org.openmole.plugin.task.groovy.*
import org.openmole.core.implementation.data.*
import org.openmole.core.implementation.sampling.*
import org.openmole.core.implementation.task.*
import org.openmole.core.implementation.capsule.*
import org.openmole.core.implementation.transition.*

proto1 = new Prototype("proto1", Integer)
proto2 = new Prototype("proto2", Integer)
out = new Prototype("out", Integer)

factor1 = new Factor(proto1, new IntegerRange("0","10","2"))
factor2 = new Factor(proto2, new IntegerRange("10","20"))
sampling = new CompleteSampling(factor1,factor2)

explorationTask = new ExplorationTask("explorationSpaceTask",sampling)
explorationCapsule = new ExplorationCapsule(explorationTask)

mySecondTask = new GroovyTask("mySecondTask")
mySecondTask.addInput(proto1)
mySecondTask.addInput(proto2)
mySecondTask.addOutput(out)
mySecondTask.setCode("out = proto1 * proto2")
mySecondCapsule = new Capsule(mySecondTask)

new ExplorationTransition(explorationCapsule,mySecondCapsule)

The aggregation

An aggregation is a particular Transition. It enables to merge results of Tasks, which have been previously run using an Exploration Task and Transition. The results are retrieved as an array of values.

An example of aggregation (suite of the previous example):

import org.openmole.core.implementation.transition.*
import static org.openmole.core.implementation.data.Prototype.*


myThirdTask = new GroovyTask("myThirdTask")
myThirdTask.addInput(toArray(out))
myThirdTask.setCode("for(v in out) println v")
myThirdCapsule = new Capsule(myThirdTask)

new AggregationTransition(mySecondCapsule,myThirdCapsule)

The MOLE

A MOLE is a workflow with a start capsule. The MOLE is what is executed.

An example of MOLE execution (suite of the previous example):

import org.openmole.core.implementation.mole.*

mole = new Mole(explorationCapsule)
ex = new MoleExecution(mole)
ex.start()

Then, you can use the ex (javadoc) variable for monitoring the execution: 

> print ex
Ready: 1711
Running: 1
Achieved: 0
Completed: 0
Failed: 0
Transition Performed: 0
Canceled: 0

Complete script

import org.openmole.core.implementation.data.*
import org.openmole.core.implementation.sampling.*
import org.openmole.core.implementation.task.*
import org.openmole.core.implementation.capsule.*
import org.openmole.core.implementation.transition.*
import org.openmole.core.implementation.transition.*
import org.openmole.core.implementation.mole.*

import org.openmole.plugin.domain.range.*
import org.openmole.plugin.sampling.complete.*
import org.openmole.plugin.task.groovy.*

import static org.openmole.core.implementation.data.Prototype.*

//-------------- prototypes ---------------
proto1 = new Prototype("proto1", Integer)
proto2 = new Prototype("proto2", Integer)
out = new Prototype("out", Integer)

//---------- factors and sampling ----------
factor1 = new Factor(proto1, new IntegerRange("0","10","2"))
factor2 = new Factor(proto2, new IntegerRange("10","20"))
sampler = new CompleteSampling(factor1,factor2)


//--------------- tasks ----------------
explorationTask = new ExplorationTask("explorationSpaceTask",sampler)

mySecondTask = new GroovyTask("mySecondTask")
mySecondTask.addInput(proto1)
mySecondTask.addInput(proto2)
mySecondTask.addOutput(out)
mySecondTask.setCode("out = proto1 * proto2")

myThirdTask = new GroovyTask("myThirdTask")
myThirdTask.addInput(toArray(out))
myThirdTask.setCode("for(v in out) println v")

//------------- capsules --------------
explorationCapsule = new ExplorationCapsule(explorationTask)
mySecondCapsule = new Capsule(mySecondTask)
myThirdCapsule = new Capsule(myThirdTask)


//----------- transitions ------------
new ExplorationTransition(explorationCapsule,mySecondCapsule)
new AggregationTransition(mySecondCapsule,myThirdCapsule)

//--------- mole execution ----------
mole = new Mole(explorationCapsule)
ex = new MoleExecution(mole)
ex.start()

logo cemagref

logo iscpif

logo lifegrid

logo region auvergne

logo patres project