Difference between revisions of "ONELAB scripting syntax"

Latest revision as of 13:21, 19 November 2012

ONELAB can be used to combine virtually any solver or data treatment code to build metamodels of relatively high complexities. A metamodel named model is constructed by defining clients and parameters in a file named model.ol with the syntax described below. A metamodel file contains only ONELAB statements.

Native ONELAB clients (i.e. the mesh generator Gmsh and GetDP) need no interfacing and need only be declared in the metamodel. For all other clients, ONELAB interfacing is based on the preprocessor principle. The natural input files of the clients are instrumented by the user (i.e. augmented with ONELAB commands). The name of the instrumented file is the name of the original file to which the ".ol" extension is added (e.g. an instrumented name.ext file will be named name.ext.ol). Instrumented files are preprocessed, i.e. parsed by ONELAB to generate a valid input file for the client, just before its execution begins.

ONELAB commands in instrumented files must be enclosed between

OL.block
   ...
OL.endblock

tags, or start with the

OL.line

tag. Comment lines in instrumented files start with "#".

Clients

name.register(interfaced|encapsulated{, pathname});

register the client name as an interfaced or native (encapsulated) client. The second argument is the executable name (full pathname or any alias that would be defined on your system).

name.commandLine(pathname)

defines the pathname to the client executable, if it was not given as second argument in the register statement.

name.in(file,...)

comma-separated list of input files. Their presence is checked before execution. File with a .ol extension are converted before execution.

name.out(file,...)

comma separated list of output files. They are deleted before execution.

name.run(options)

the string options is interpreted (if it contains substitution statements) and appended to the commandline when calling the client.

name.active(0|1)

sets the client active or inactive. Inactive clients are not executed but remain registered.

name.up(file,j,k,Parameter/Name, ...)

tells ONELAB to extract the kth numbers from the jst line in the file file, and to upload it as a new parameters named Parameter/Name. If the line number j is "-1", the last line of the file is considered instead of the jth. The group of four arguments can be repeated in one single "up" statement to upload several parameters.

name.merge(file, ...)

comma separated list of solution files interpretable by Gmsh (.pos, .msh, .geo, ...) to be merged after execution.

name.check()

This optional statement forces the client to be checked immediately after its declaration so that parameters it declares can be used directly in the sequel of the metamodel definition.

Clients on remote hosts

Clients can be run on remote hosts. For this, automatic ssh on the remote host without password should be authorized (Cf for instance [1] to see how this can be done on linux systems). Most of the above syntax is unchanged. Client registration, however, requires additional information:

name.register(interfaced|encapsulated,{pathname}, remote_host, remote_dir);

register the client name as an interfaced or native (encapsulated) remote client. The second argument is the executable name (full pathname or any alias that would be defined on the remote host). The 3rd and 4th mandatory arguments define the remote host (e.g. username@host) and the remote directory (either a full path or a relative path from the home directory).

Moreover, lists of input and output files (i.e. the arguments of the in and out statements) need now specify whether each individual file in the list should be looked for on the local or on the remote host. This is very simply and systematically done by writing "./filename" in the list whenever the file is to be looked for in the working directory on the local host, and "filename" when it has to be looked for in the remote directory on the remote host.

The metamodel CRYO (See Elmer) uses remote clients.

Parameters

name.number(Value{,Path{,Label{,Range}}})

defines a ONELAB parameter of type number", with name Path/name and assign the value Value to it. The prepended Path string allows sorting parameters hierarchically in the ONELAB window. Label is the display name in the ONELAB window. The Range is a string built on the model of "min:max:step" that indicate the minimum and maximum value of the parameter as well as an increment that will be used when looping on the parameter.

name.range(Range)

defines the range of the parameter if it was not given in the declaration.

name.string(Value,Path,ShortHelp)

defines a ONELAB parameter of type string", with name Path/name and assign the value Value to it. Label is the display name in the ONELAB window.

name.setVisible(0|1)

sets the parameter name to be visible or not in the ONELAB window.

name.setReadOnly(0|1)

sets the parameter name to be read-only or not. Read-only parameters are depending parameters, i.e. parameters that depend on other parameters and whose value is set by the metamodel, not by the user. Even when visible, they cannot be modified in the ONELAB window.

name.addChoices(Value, ...)

add items to the list of possible choices for the parameter. The list of choices is used when ONELAB makes a loop on the parameter.

name.resetChoices()

resets the list of choices of the parameter name.

name.valueLabels(Value, Label, ...)

adds items to the list of possible choices for a parameter of type "number", and associates a label with each choice. The labels appear in a small menu when clicking on the drop-down arrow besides the parameter in the ONELAB window. Several pairs "Value, Label" can be given comma-separated in one single "valueLabel" statement.

name.radioButton(Value{,Path,{Label}})

defines a parameter of type number with "0" and "1" as only possible choices. Radio button parameters are used for on/off or yes/no options. They appear as a tickbox in the ONELAB window.

Value substitution

OL.get(name)

insert here the value from the server of the parameter name. This command may appear several time in the same line.

OL.eval(string)

after resolving "OL.get" statements, if any, the string is sent to the algebraic interpreter [MathEx] for evaluation. E.g. OL.eval( floor((OL.get(A) + OL.get(B))/ 2)), where "floor" is a built-in function of MathEx.

Conditional statements

There are three conditional statements in ONELAB.

OL.iftrue(param) | OL.ifntrue(param) | OL.if(expression)
... 
OL.else 
... 
OL.endif

The "iftrue" statement is true if the parameter param is not 0 (number case) or not the empty string "" (string case). The "ifntrue" statement is true if the parameter param is 0 (number case) or the empty string "" (string case). In the "if" statement, expression is constructed on the model

termA {< | > | == | <= | >=} termB

where termA and termB are interpreted if necessary. For instance:

OL.if( OL.get(This/Parameter) <= 10 )

Miscellaneous

OL.include(file)

insert here the result of the preprocessing of the file file

OL.msg(string)

interpretes the string string and echoes the result to the terminal.

Definition of ONELAB tags

By default, ONELAB commands are identified in instrumented files by the onelab tag "OL.", and comment lines, ignored by the preprocessor, start with the comment tag "#". Those tags can however be modified to accomodate various client syntaxes. The command

onelab.tags(\,//);

for instance, redefines the onelab tag as "\" and the comment tag as "//"

The commands

onelab.tags(); onelab.tags(,); or onelab.tags(OL.,#);

indifferently, restore the defaults values.

Example:

#example of tag redefinition
OL.include(filename)
onelab.tags(\,//)
\iftrue(PARAM)
  do something
  // we are using modified tags
\endif
onelab.tags()
#default tags are restored
Val = OL.get(PARAM)