|
|
|
ONELAB parameters can be created, accessed and modified in various ways in Gmsh (`.geo`) and GetDP (`.pro`) input files:
|
|
|
|
|
|
|
|
1. `n = DefineNumber[ 3.14, Name "a number", <attributes...>];`
|
|
|
|
|
|
|
|
2. `s = DefineString["hello", Name "a string", <attributes...>];`
|
|
|
|
|
|
|
|
3. `DefineConstant [ n = {3.14, Name "a number", <attributes...>} , s = {"hello", Name "a string", <attributes>} , ...] ;`
|
|
|
|
|
|
|
|
4. `SetNumber[ "a number", 3.14 ]; n = GetNumber["a number"];`
|
|
|
|
|
|
|
|
5. `SetString[ "a string", "hello" ]; s = GetString["a string"];`
|
|
|
|
|
|
|
|
In addition, GetDP defines two functions to access ONELAB parameters at run-time, i.e. during pre-processing, processing or post-processing operations (in contrast to the other methods listed above, which are executed when the `.pro` files are parsed):
|
|
|
|
|
|
|
|
1. `SetNumberRunTime[ 3.14 ]{"a number"}`
|
|
|
|
|
|
|
|
2. `n = GetNumberRunTime[]{"a number"}`
|
|
|
|
|
|
|
|
Finally, GetDP also defines a `SendToServer` option in its `PostOperation` object, to send post-processing results directly to the ONELAB database. See the GetDP [documentation](http://getdp.info/doc/texinfo/getdp.html#Types-for-PostOperation) for more information.
|
|
|
|
|
|
|
|
## DefineNumber and DefineString
|
|
|
|
|
|
|
|
When an input `.geo` or `.pro` file is parsed, the command
|
|
|
|
|
|
|
|
```cpp
|
|
|
|
n = DefineNumber[ 3.14, Name "a number", <attributes...>];
|
|
|
|
```
|
|
|
|
|
|
|
|
first checks if the ONELAB parameter `"a number"` exists in the ONELAB database. If it does not, it creates it in the database with value `3.14`, and assigns this same value to the local Gmsh or GetDP variable `n`. A `/` character in a parameter name is interpreted as a path separator, and results in the creation of a sub-tree in the graphical user interface. If the same input file is re-analyzed later, or if another input file is parsed and the ONELAB parameter `"a number"` already exists in the database, its associated value is fetched and is assigned to the local variable `n` (unless it is labeled `ReadOnly`: see below for all the optional attributes that can be specified in addition to the `Name` of the parameter).
|
|
|
|
|
|
|
|
This means that `3.14` can be interpreted as a default value for the local variable `n` (and the ONELAB parameter `"a number"`): the first time `n = DefineNumber[ 3.14, Name "a number"]` is parsed, `n` will be assigned the default value `3.14`. The next time, `n` will be assigned whatever value is associated with the `"a number"` parameter in the ONELAB database. The value in the database could be the original default value, a value set by the user in the graphical user interface, or a value set by another ONELAB client.
|
|
|
|
|
|
|
|
If no ONELAB server exists (e.g. if GetDP is run in stand-alone mode), the `DefineNumber` command simply assigns the default value `3.14` to the local variable `n`. An input file using `DefineNumber` to create an appealing graphical user interface using ONELAB can thus also be run as-is without ONELAB.
|
|
|
|
|
|
|
|
A similar syntax can be used to define string parameters:
|
|
|
|
|
|
|
|
```cpp
|
|
|
|
s = DefineString["hello", Name "a string", <attributes...>];
|
|
|
|
```
|
|
|
|
|
|
|
|
See below for all the optional attributes that can be specified in addition to the `Name` of the parameter.
|
|
|
|
|
|
|
|
The behavior of `DefineNumber` and `DefineString` is similar to the behavior of the functions with the same names in Python clients.
|
|
|
|
|
|
|
|
#### Examples
|
|
|
|
|
|
|
|
```cpp
|
|
|
|
x = DefineNumber[1, Name "My variable"];
|
|
|
|
x = DefineNumber[1, Name "My variable", Choices {0,1}];
|
|
|
|
x = DefineNumber[1, Name "My variable", Choices {0,3,5}];
|
|
|
|
x = DefineNumber[1, Name "My variable", Choices {0="Zero",3="Three", 5="Five"}];
|
|
|
|
x = DefineNumber[1, Name "My variable", Min 0, Max 50, Step 5}]
|
|
|
|
x = DefineNumber[1, Name "Variables/Input/My variable", Min 0, Max 50, Step 5];
|
|
|
|
y = DefineNumber[2. * x, Name "My read-only variable y = 2*x", ReadOnly];
|
|
|
|
s = DefineString["a", Name "My string variable"];
|
|
|
|
s = DefineString["a", Name "My string variable", Choices {"a", "b", "c"}];
|
|
|
|
s = DefineString["a", Name "My string variable", Kind "File"]
|
|
|
|
s = DefineString["a", Name "Variables/Input/My string variable"];
|
|
|
|
```
|
|
|
|
|
|
|
|
## DefineConstant
|
|
|
|
|
|
|
|
`DefineConstant` builds on the functionality of `DefineNumber` and `DefineString`, and adds useful features for constructing generic parametric models.
|
|
|
|
|
|
|
|
When an input `.geo` or `.pro` file is parsed, the command
|
|
|
|
```cpp
|
|
|
|
DefineConstant [ n = {3.14, Name "a number", <attributes...>} ];
|
|
|
|
```
|
|
|
|
first checks if the local variable `n` exists. If it does not exist, the command behaves as `n = DefineNumber[3.14, Name "a number"]`. If it does exist, the `DefineConstant` command is skipped and the ONELAB parameter is not created. `DefineConstant[n = {3.14, Name "a number"}]` is thus a shortcut for
|
|
|
|
```cpp
|
|
|
|
If(!Exists(n))
|
|
|
|
n = DefineNumber[3.14, Name "a number"];
|
|
|
|
EndIf
|
|
|
|
```
|
|
|
|
|
|
|
|
`DefineConstant` can also be used to define several constants at once, mixing numbers and strings:
|
|
|
|
```cpp
|
|
|
|
DefineConstant [
|
|
|
|
n = {3.14, Name "a number", <attributes...>},
|
|
|
|
s = {"hello", Name "a string", <attributes...>}
|
|
|
|
];
|
|
|
|
```
|
|
|
|
As with `DefineNumber` and `DefineString`, if a ONELAB server does not exists the `DefineConstant` command simply assigns the default values to the local variables.
|
|
|
|
|
|
|
|
When creating generic parametric models, several input files are usually combined, using `Include` to merge generic definitions in more specific models. For example, let us assume that a generic model in the file `generic_model.pro` contains the following code:
|
|
|
|
```cpp
|
|
|
|
DefineConstant[ flag = {1, Choices{1,2,3}, Name "a flag changing the behavior of the model"}];
|
|
|
|
// the model uses this flag to control the model behavior
|
|
|
|
```
|
|
|
|
Let us now consider a more specific model, that uses the generic model but only makes sense for a specific value of `flag`, say `2`. Instead of modifying the generic model to suit the needs of the specific model, the specific model can simply be written as
|
|
|
|
```cpp
|
|
|
|
flag = 2; //
|
|
|
|
Include "generic_model.pro"
|
|
|
|
```
|
|
|
|
The user-visible ONELAB variable `"a flag changing the behavior of the model"` will never be defined, and for the user of the specific model, everything behaves as if `flag` is not a parameter.
|
|
|
|
|
|
|
|
Note that in addition to setting the values of the local variables in the input `.geo` and `.pro` files, both Gmsh and GetDP allow to pass local variable definitions on the command line, with the `-setnumber name value` and `-setstring name value` command line options.
|
|
|
|
|
|
|
|
#### Examples
|
|
|
|
|
|
|
|
```cpp
|
|
|
|
DefineConstant[ x = {1, Name "My variable"} ];
|
|
|
|
DefineConstant[ x = {1, Name "My variable", Choices {0,3,5}} ,
|
|
|
|
y = {2. * x, Name "My read-only variable y = 2*x", ReadOnly},
|
|
|
|
s = {"a", Name "My string variable"} ];
|
|
|
|
```
|
|
|
|
|
|
|
|
## SetNumber, SetString, GetNumber and GetString
|
|
|
|
|
|
|
|
`SetNumber`, `SetString`, `GetNumber` and `GetString` allow to perform direct basic queries in the ONELAB database:
|
|
|
|
|
|
|
|
```cpp
|
|
|
|
SetNumber[ "a number", 1 ];
|
|
|
|
SetString[ "a string", "1" ];
|
|
|
|
a = GetNumber["a number"];
|
|
|
|
s = GetString["a string"];
|
|
|
|
```
|
|
|
|
|
|
|
|
Currently these basic functions do not allow setting optional ONELAB attributes.
|
|
|
|
|
|
|
|
## SetNumberRunTime and GetNumberRunTime (GetDP only)
|
|
|
|
|
|
|
|
All the above functions (`DefineNumber`, `DefineString`, `DefineConstant`, `SetNumber`, `SetString`, `GetNumber` and `GetString`) are executed when the input data files for GetDP and Gmsh are parsed. For GetDP, this means that the queries in the database using these functions are done once, when the `.pro` file is analyzed.
|
|
|
|
|
|
|
|
However, in some situations, one might want to exchange information with the ONELAB database while the computation is running, i.e. at ''run-time''. GetDP defines two built-in functions (at the same level as other GetDP functions like `X[]` or `Vector[]`) that allow to exchange numbers at run-time, while evaluating expressions:
|
|
|
|
|
|
|
|
```cpp
|
|
|
|
SetNumberRunTime[ 3.14 ]{"a number"}
|
|
|
|
GetNumberRunTime[]{"a number"}
|
|
|
|
```
|
|
|
|
|
|
|
|
These functions can be used in all the same places that other GetDP expressions can be used, e.g. in `Function` definitions, `Formulation` terms, inside the `Evaluate` operation in a `Resolution`, etc.
|
|
|
|
|
|
|
|
## Common parameter attributes
|
|
|
|
|
|
|
|
Here's the list of attributes available for all ONELAB parameters:
|
|
|
|
|
|
|
|
* `Name "string"`: The name of the parameter in the ONELAB database, in the form of a `/`-separated path. The `Name` attribute is mandatory to exchange the variable with the ONELAB server. If no name (and no other attribute) is given, the `DefineConstant` construct can be used to assign default values to local variables (which will not be sent to the ONELAB server).
|
|
|
|
|
|
|
|
* `ReadOnly 0|1`: If ReadOnly is set, the value cannot be changed server-side, and the value provided in `DefineConstant` is always used.
|
|
|
|
|
|
|
|
* `Highlight "string"`: Color used to draw the widget in the graphical interface.
|
|
|
|
|
|
|
|
* `Visible 0|1`: Should the parameter be visible in the interface?
|
|
|
|
|
|
|
|
* `Closed 0|1`: Should the subtree containing this variable be closed?
|
|
|
|
|
|
|
|
* `Help "string"`: Help string for this parameter.
|
|
|
|
|
|
|
|
* `AutoCheck 0|1`: Allows to disable automatic "check" (rebuild of the interface) when the value is changed.
|
|
|
|
|
|
|
|
* `GmshOption "string"`: Treat the parameter as the name of a Gmsh option (e.g. `Mesh.Algorithm`). Can also be used to force a database reset (with `ResetDatabase`), or a full model reset (with `Reset`).
|
|
|
|
|
|
|
|
* `Label "string"`: Alternative label used in the graphical user interface, replacing the part of `Name` located after the last `/`.
|
|
|
|
|
|
|
|
* `Units "string"`: Appends the given string after the variable name between square brackets.
|
|
|
|
|
|
|
|
* `ChangedValue number`: The value that the `changed` flag will take when the parameter is updated. A zero value thus means that the parameter will appear as never having being changed. Gmsh treats `changed` flag values as follows: if `changed`=1, only the mesh is saved; if `changed`=2, the model is first remeshed, then the mesh is saved; if `changed`=3, the model is first reloaded, then remeshed and finally saved.
|
|
|
|
|
|
|
|
## 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
|
|
|
|
|
|
|
|
* `Range {min, max, step}: Alternate syntax for `Min`, `Max` and `Step`
|
|
|
|
|
|
|
|
* `Choices {number, number, ...}`: Possible choices for the parameter
|
|
|
|
|
|
|
|
* `Choices {number="string", number="string", ...}`: Possible choices for the parameter, with string labels for each choice
|
|
|
|
|
|
|
|
* `ReadOnlyRange 0|1`: Treat the range (or the choices, if they are provided) as read-only
|
|
|
|
|
|
|
|
* `Loop "string"`: Loop over the parameter (the string indicates the loop imbrication level: currently "1", "2" or "3")
|
|
|
|
|
|
|
|
* `Graph "string"`: Display the list of values stored in the `choices` attribute as a 2D graph. The `string` encodes for which coordinate (x or y) in the predefined graphs (top left, top right, ...) the values will be used. Each graph is encoded as 4 characters, corresponding to the use of the values as the x, y, x' and y' coordinates (x' and y' are used when two curves should be drawn on the same graph): possible character values are `0` (value not used), `1` (iso-values), `2` (continuous map), `3` (discrete map), `4` (numeric value). The first group of 4 characters controls the pre-defined top-left graph, the second group controls the top-right graph, etc. For example, the `string` `"0200"` will use the values for the y coordinates on the top-left graph, displaying the curve with the continuous style; the `string` `"10000200"` will use the data for the x coordinates on the top-left graph and also use them as the y coordinates on the top-right graph.
|
|
|
|
|
|
|
|
## String attributes
|
|
|
|
|
|
|
|
String accepts the following specific attributes:
|
|
|
|
|
|
|
|
* `Kind "string"`: Mutable kind of the string (currently: `"file"`)
|
|
|
|
|
|
|
|
* `Choices {"string", "string", ...}`: Possible choices for the parameter
|
|
|
|
|
|
|
|
* `MultipleSelection "string"`: Allow multiple selection in choices. The string indicates the initial selection pattern, e.g. `"1001111"`.
|
|
|
|
|
|
|
|
* `Macro "string"`: If `string` is `"GmshMergeFile"`, the parameter is treated as a filename of a macro that will be merged when the parameter is clicked in the interface. If `string` is `"GmshParseString"`, the parameter is directly treated as a Gmsh macro that will be parsed when the parameter is clicked in the interface. |
|
|
|
\ No newline at end of file |