Home > Model Components > User Defined Keywords

User Defined Keywords

Overview

The User defined keyword (UDK) object allows the user to add solver keywords to the solver LOG input file. Adding directly solver keywords is useful when these keywords have no dedicated GUI (cannot be called directly in the interface) or when these keywords are to be defined in a more generic way.

DeepLines gives already the possibility to add solver keywords to a LOG file of an analysis: the panel Calculation parameters → Analysis Type → Static (or Time domain) → Advanced has an active edit box to write solver keywords if the User defined keywords check box is selected. However, some solver keywords need to reference structural objects or nodes by their IDs (which are integers). It is difficult for the user to know in advance which ID will be used to identify such object or node in the LOG file. Moreover, these IDs may change during a project if objects are added/removed in the model. That is why defining solver keywords in the Advanced panel can be hard. The purpose of this new way of defining solver keywords is to facilitate the references to the objects IDs.

Graphical User Interface

An UDK object can be added in the model tree view using the following toolbar icon:

The item Edit... of the contextual menu of the UDK object opens the following dialog box which allows to define the UDK:

User Defined Keywords can be components of an Environment Set.

In an Environment Set dialog box, selecting the User Defined Keyword check box in the General tab, opens an UserDefinedKeywords tab which displays the same content of previous dialog box allowing to define the UDK.

Definition of a User Defined Keyword

A User defined keyword object is composed of a set of sub-types, each sub- type is defined by the association of two components:

• A Keyword content : it contains a text which will be written in the solver LOG file;

• A Keyword configuration : it helps the user to reference objects IDs which are needed by most solver keywords.

The image of the UDK dialog box above, shows three areas:

• Area 1 : area used to define UDK sub-types;

• Area 2 : area used to define Keyword contents;

• Area 3 : area used to define Keyword configurations.

Keyword content

The keyword content is identified by a name and its content has to be filled by the user in the edit box. The content must consist of lines that can be interpreted by the solver. Commentaries can be added if their lines begin by the character C. See an example of a keyword content in the Area 2 of the UDK dialog box shown above.

Note

A sub-type can be defined with only one keyword content and without a keyword configuration. In that case:

• adding a User defined keyword object in an analysis has a similar effect to add the equivalent keyword content in the edit box of the Advanced panel. These two ways of defining solver keywords add the content of the edit box without changes.

• it is more convenient to use the User defined keyword toolbox instead of the equivalent keyword content in the edit box of the Advanced panel: its access is easier because it belongs to the model tree and the same User defined keyword can be used for multiple analyses sets.

Keyword configuration

The aim of the keyword configuration component of the User defined keyword object is to help the user to reference IDs used by the LOG file.

Each time a solver keyword needs to reference an ID of a previously defined object or node, the user can use in place of this ID, a term that we will call an id-identifier. There are four types of id-identifiers:

$idobj	structural object
$idloc	localization on a structural object which is a predefined node of this object
$idpos	position on a structural object which will be replaced by the nearest node
$idvar	variation table

An id-identifier is composed of one the four previous types followed by a number which identifies the id-identifier among the elements of the tables contained in the keyword configuration, for example: $idloc2.

See an example of a keyword configuration in the Area 2 of the UDK dialog box shown in the HMI section.

The $idobj takes on a different meaning depending on the type of object to which it refers:

Object type	$idobj
Equipment	Group ID
Ballast Arch HAWT	Object ID
Pulley Spring Flexjoint Load excursion	Element ID
Floater Buoy Rigid body	Master node ID
BOPStack Tensioner Telescopic joint	Error

Translation mechanism

The id-identifiers are defined in the keyword configuration and referenced in the keyword content which is associated to the keyword configuration within the same sub-type.

The id-identifier referenced in a keyword content will be automatically replaced by the corresponding ID in the LOG file. The keyword contents of all the sub-types are written at the end of the LOG file. The referenced objects have been defined before in the file and so their IDs are known.

In sub-types, the same keyword content can be associated with several keyword configurations. Inversely, a same keyword configuration can be associated to multiple keyword contents.

Associations of a keyword configuration with a keyword content in sub-types can be checked by the use of the Check button. For example, if an id- identifier is used in the keyword content and if it is not defined in the keyword configuration associated in the same sub-type, an error message is displayed. Note that data are saved before checking, as the Save button does.

It is a good practice to check sub-types in this way before generating LOG files.

Lists of keyword contents and configurations

It is important to notice that the lists of keyword contents and configurations are managed independently of the User Defined Keyword objects. A keyword content or configuration can be created or deleted by, respectively, the New or Delete button. Each time a new User Defined Keyword object is open, the same lists of Keyword Contents and Configurations are available in their corresponding combo-boxes. This is also true for User Defined Keyword objects defined by the use of an environment set. This way configurations can be reused and should be seen as "types".

Warning

As a consequence of the above, if you change a keyword content or configuration which is used by several UDK objects, the change will concern all these UDK objects. If you want to make a change to a particular UDK object, you have to define a new keyword content or configuration relative to that object.

Variation Table and $idvar id-identifier

For example, $idvar1 references a variation table defined as a Variation table type. As indicated by its name, a variation table gives the variation of a variable in function of another variable. For solver keywords, a variation table contains, most of the time, the values of a time-dependent or position- dependent variable.

When a $idvar id-identifier is found in a keyword content, it is replaced, like other id-identifiers, by its ID in the LOG file. But in the case of a variation table, the presence of the id-identifier will also automatically append the content of the table in the LOG file as a *TABLEMCOL solver keyword.

For example, the following keyword content:

C --- X-direction ( Incremental ) 
*INCDX
$idloc1 1 -64.95 $idvar1
C --- Y-direction ( Incremental )
*INCDX
$idloc1 2 37.5 $idvar1
C ---

is translated to the LOG file like this:

*TABLEMCOL
1 2 2
0 0.1
10 1
C --- X-direction ( Incremental )
*INCDX
207 1 -64.95 1
C --- Y-direction ( Incremental )
*INCDX
207 2 37.5 1
C ---

If a *TABLE keyword is needed, the $idvar id-identifier has to be suffixed by $table.

For example, the following keyword content:

C --- X-direction ( Incremental )
*INCDX
$idloc1 1 -64.95 $idvar1$table
C ---
C --- Y-direction ( Incremental )
*INCDX
$idloc1 2 37.5 $idvar1$table
C ---

is translated to the LOG file like this:

*TABLE
1
0 0.1
10 1
C --- X-direction ( Incremental )
*INCDX
207 1 -64.95 1
C --- Y-direction ( Incremental )
*INCDX
207 2 37.5 1
C ---

Env Table and $env identifier

The user can directly write values in the keyword content or previously define these values in an EnvTable. In the latter case, the user has to mention the term $env which identifies together an EnvTable and the indexes of the row and column in the table. Indexes begin at 1.

An EnvTable is simply a table of values: there is not necessarily a link between the columns as for a variation table. However, the first column of an EnvTable has a particular meaning in the case of the EnvTable is used in an EnvSet component, as indicated in the section. The $env identifier is not associated to a solver ID, that is why its name does not contain the prefix "id".

Multiple values can be referenced at once by the same id-identifier if these values belong to the same row of the EnvTable. For that, the indexes of the columns must be specified with one of the following two forms:

• separating them by a semi-column character, for example: 2;7;5,

• using the interval notation \<index1>:\<index2>, for example: 2:4, or in reverse order, 4:2.

The row index can take only one value.

UDK used in an Environment Set

As indicated in the previous section, an EnvTable can be used to translate values in the LOG file from an UDK object. However, as its name suggests, an EnvTable is intended for use as part of an Environment Set. In that case, the row index cannot be set by the user (the Row column is shaded) and the row index is determined automatically according to the following mechanism: for each analysis (each combination matrix line), if its index is present in the first column of the EnvTable, the corresponding values are written in the LOG file. To apply this mechanism, the EnvTable must contain the analyses indexes in its first column.

Consider, for example, the following Environment Set with an UDK component:

The EnvTable_1 has the following content:

The LOG files generated for the first and third analyses of the Environment Set contain, respectively:

• Analysis 1 (EnvSet_1.log)

  *TABLEMCOL
  3 3 2
  0 0
  5 1
  10 1
  *INCDX
  8 1 1.2 3
  

• Analysis 3 (EnvSet_3.log)

  *TABLEMCOL
  3 3 2
  0 0
  5 1
  10 1
  *INCDX
  8 3 5 3
  

Nothing is added in the .log file of the Analysis 2, because no UDK component has been chosen in the combination matrix of the Environment set.

For Analysis 1, the index 1 of the analysis is present in the first column of the EnvTable at the second line: therefore $env1 and $env2 are replaced respectively by 1.2 and 1.

In the same way, for the third analysis, $env1 and $env2 are replaced in the .log file respectively by 5 and 3.

Note

Defining User Defined Keywords in an Environment Set is useful only if:

• an EnvTable is defined in the keyword configuration and the mechanism of changing the row of the EnvTable in function of the row of the combination matrix must be applied,
• or the User Defined Keyword is not used in all rows of the combination matrix. In other cases, it is much simpler to define User Defined Keywords as model tree objects.