ONELAB onelab.py module

Once a ONELAB client is created in a Python script, e.g. with

import onelab
c = onelab.client(__file__)

ONELAB parameters can be created, accessed and modified using:

• n = c.defineNumber('a number name', <attributes...>)

• s = c.defineString('a string name', <attributes...>)

• c.setNumber('a number name', <attributes...>); n = c.getNumber('a number name', <attributes...>)

• c.setString('a string name', <attributes...>); s = c.getString('a string name', <attributes...>)

These commands behave in a similar way to the equivalent Gmsh and GetDP commands.

Common parameter attributes

Here's the list of attributes available for all ONELAB parameters:

• readOnly=0|1: If readOnly is set, the value cannot be changed server-side, and the value provided in the python script is always used
• visible=0|1: Should the parameter be visible in the interface?
• help='string': Help string for this parameter
• label='string': Alternative label used in the graphical user interface, replacing the part of Name located after the last /

Other attributes can be specified using the generic attribute dictionary, e.g. attribute={'Highlight':'string'}. See the Gmsh and GetDP commands for a list of all other attributes.

Number attributes

In addition, numbers can take the following specific attributes:

• min=number: Minimum value allowed when scrolling in the interface, and when looping on the parameter
• max=number: Maximum value allowed when scrolling in the interface, and when looping on the parameter
• step=number: Step value used when scrolling in the interface, and when looping on the parameter
• choices={number, number, ...}: Possible choices for the parameter
• labels={number:'string', number:'string', ...}: Possible choices for the parameter, with string labels for each choice

String attributes

Strings accept the following specific attributes:

• kind='string': Mutable kind of the string (currently: "file")
• choices={'string', 'string', ...}: Possible choices for the parameter

Access to runtime Gmsh front-end parameters

Accessing a number of Gmsh runtime parameters can be useful to develop more involved on more user-friendly Python-ONELAB solvers.

• c.action == 'check' | 'compute': Test on the string variable c.action can be done to branch on parts of the script to be executed or not according to the mode.

• c.loop == 0|1:Gmsh can loop on parameters to perform simple parametric analyses. The variable c.loop is 1 when Gmsh is engaged in such a loop, 0 otherwise.

• c.batch == 0|1: The variable c.batch is 1 when a Python script script.py is called by Gmsh with no GUI, i.e. with gmsh script.py -. It is 0 otherwise.

• c.getPath | c.checkPath: The function c.getPath(subdir/filename) returns a pathname built by appending subdir/filename to the pathname of the directory where the Python script under execution is located. The function c.checkPath is the same as c.getPpath but also checks whether the built pathname exists on disk. If the pathname does not exist, an error is issued.

Saving/loading models and solutions

If the Archive output files automatically checkbox is checked in the gear menu of Gmsh, the files declared in the python script by the statement

c.outputFiles( [file1.ext1, file2.ext2, …] )

as well as the database state, are copied at the end of each run of the model into the archive subdirectory of the working directory with names

file1_yyyy-mm-dd_hh-mm-ss_tag.ext1
file2_yyyy-mm-dd_hh-mm-ss_tag.ext2
...
onelab_yyyy-mm-dd_hh-mm-ss_tag.db

The automatically appended stamp consists of a to the second accurate timestamp yyyy-mm-dd_hh-mm-ss, augmented with the user-defined ONELAB string parameter named Metamodel/Tag (which can be a null string). The purpose of automatic archiving is to keep track of all simulations done, which might be memory-space consuming. The declared output files should therefore not be too large in size, and contain in a concise form the main results of a simulation. The archived database, on the other hand, allows reproducing the simulation if needed.

When a metamodel involves heavy and time-consuming computations, it is also interesting, in addition to the output files, to also save the solution files. This allows making series of post-processing runs on the same simulation data. To do this, the Load Database and Save Database commands of the gear menu are used. If the script contains a statement

c.solutionFiles( [file1.ext1, file2.ext2, …] )

saving the database under the name onelab_tag.db into the directory dbdir with the Save Database widget will save the ONELAB database and additionally rename on disk the declared solution files into

dbdir/archive/file1_tag.ext1
dbdir/archive/file2_tag.ext2
...

It is a good practice to save the databases in the working directory, so that the saved solution files end up in the same directory as the automatically archived output files.

Be sure to clearly understand the difference between 'output files' and 'solution files'. The former are small-size files (order of a few kB) that summarize a simulation in a concise way, typically data for graphs. The latter are large-size files (order of MB) containing solutions at all nodes and all time steps of the finite element problem. The user is invited to clean up the archive subdirectory regularly. Practically, when a simulation is completed that you want to save,

• click on gear menu/Save database,
• enter a filename of the form onelab_tag.db in the Save as box, with an explicit tag that characterizes the simulation at hand (e.g. onelab_case1.db or onelab_reference.db)
• browse to the directory where the database should be saved (recommended: in the working directory)
• click on Save.

To reload a simulation,

• click on gear menu/Open database
• select the database to restore (e.g. onelab_case1.db)
• click on Open. As long as the Use restored solution' checkbox remains checked, model runs will use the restored solution files.