Default hooks 🔗

What is a Hook? 🔗

Tasks in OpenMOLE are mute pieces of software. They are not conceived to write files, display values, or generally present any side effects at all. The role of a task is to compute some output data from their input data. That's what guarantees that their execution can be deported to other machines.
OpenMOLE introduces a mechanism called Hook to save or display results generated during the execution of a workflow. Hooks are conceived to perform an action on the outputs of the task they are plugged to. Different hooks are available for different actions that need to be performed.

How to plug a hook to a task 🔗

The hook keyword is used to save or display results generated during the execution of a workflow. There is only one mandatory argument to specify, the kind of output you want:

• hook display to display the results in the standard output, note that it is completely equivalent to writing hook(display) or hook(output = display)
• hook(workDirectory / "path/to/a/file") to save the results in a file

Let's consider this simple workflow:

// Define the variable i
val i = Val[Int]

// Define a task which returns its input value multiplied by 2
val hello = ScalaTask("i = i * 2") set (
  (inputs, outputs) += i
)

// Define an exploration task
DirectSampling(
  evaluation = hello,
  sampling = i in (0 to 9)
) hook (workDirectory / "results")

The hook is plugged to the end of the hello task in the DirectSampling, which means that every time hello finishes, the hook is executed. At the end of the execution you will find a file calle results.omr in the same directory as your script that contains all the results produced by the execution of the task. In the interface you can then open this file and export it in CSV or JSON format.
These default hook are able to store files and directories. If some of you output variables are files there values are stored in the OMR file along with the others variables.

Default hooks 🔗

OpenMOLE methods come with a default hook to save their results in a properly formatted file. To use these embedded hooks, you can directly give the required arguments (e.g. the path of the created file) to the hook keyword.
The specific arguments of the default hooks for each method, when they exist, are described in the corresponding documentation page in the Explore section.

Advanced hook usage 🔗

Appart from the default hook for each method OpenMOLE provide several hook to store results in specific maners.

Write a string 🔗

Any string can be appended to a file using the hook AppendToFileHook. The appended string can be a combination of variables from the data flow and plain text.

val i = Val[Int]

val h = AppendToFileHook(workDirectory / "path/of/the/file.txt", "string ${i} to append")

Write an entire file 🔗

AppendToFileHook can be used to write an entire file as well.

val file = Val[File]
val i = Val[Int]

val h = AppendToFileHook(workDirectory / "path/to/a/file/or/dir${i}.csv", "${file.content}")

The path to the new file can be expanded using variables from the data flow (i here for instance). The variables or expressions written between ${} are evaluated and replaced with their value.

Write into a CSV file 🔗

The hook CSVHook takes data from the data flow and appends it to a file formatted as CSV.

val i = Val[Int]

val h = CSVHook(workDirectory / "path/to/a/file/or/dir${i}.csv")

Some additional optional parameters can be passed to the CSVHook:

• values = Seq(i, j) specifies which variables from the data flow should be written in the file. The default behaviour when this list is not specified is to dump all the variables from the dataflow to the file.
• header = "Col1, Col2, ColZ" customises the header of the CSV file to be created with the string it receives as a parameter. Please note that this only happens if the file doesn't exist when the hook is executed.
• arrayOnRow = true forces the flattening of input lists such that all list variables are written to a single row/line of the CSV file.

val i = Val[Int]
val j = Val[Array[Int]]

val h = CSVHook(workDirectory / "path/to/a/file/or/dir${i}.csv", values = Seq(i, j), header = "i, j", arrayOnRow = true)

Write a matrix into a file 🔗

Some workflows may output two dimensional data, which can be understood as a matrix. For this, the MatrixHook writes matrix-like data to a file.

val matrix = Val[Array[Array[Double]]]

val h = MatrixHook("file.csv", matrix)

Output format will be a CSV file. Data understood as matrix are one and two dimensional arrays of double, int and long.

Hook to copy a file 🔗

The CopyFileHook makes it possible to copy a file or directory from the data flow to a given location on the machine running OpenMOLE.

val file = Val[File]
val i = Val[Int]

val h = CopyFileHook(file, workDirectory / "path/to/copy/the/file${i}.txt")

Display variables 🔗

To display a variable i from the workflow in the standard output, use the hook DisplayHook(i):

val i = Val[Int]
val j = Val[Int]

val h = DisplayHook(i, j)

If no variable is specified in DisplayHook(), the whole data flow will be displayed.

Display strings 🔗

To display a string in the standard output, use the DisplayHook("string"). The string can be formed of plain text and/or variables. You can think of the DisplayHook as an OpenMOLE equivalent to Scala's println.

val i = Val[Int]

val h = DisplayHook("The value of i is ${i}.")

Conditional hooking 🔗

You may want to filter outputs that are redirected to a hook, i.e. do conditional hooking. You can use for that the when keyword, built from a hook and a condition:

val i = Val[Int]

val display = DisplayHook("The value of i is ${i}.") when "i > 0"

Decorators exist for a simpler syntax: ConditionHook(myHook,myCondition) is equivalent to myHook when myCondition and myHook condition myCondition (where the condition can be given as a condition or a string).

Variable restriction 🔗

You may want to restrict the hooked variables to a subset, like a variable filter. You can use the following notation in the hook function {hook(yourHookHere, values = Seq(i,j))}

val i = Val[Int]
val j = Val[Int]
val k = Val[Double]

val task = EmptyTask() set (
  outputs += (i, j, k)
)

task hook(display, values = Seq(i, j)) // only i and j are displayed
task hook(workDirectory / "results/res.omr", values = Seq(j,k)) // only j and k are stored into the file