5. User-defined Variables

User-defined variables are used to store different types of data in the shell. Results of various operations and algorithms can be stored in these variables for further use in the solution procedure.

Another important use of user-defined variables is for transferring data between different modules, operations and algorithms of the shell. A typical example of that is passing data between optimisation algorithms and the function which performs direct analyses. Variables with a pre-defined meaning are used for this task.

Variable types that are currently implemented in the shell are scalar, vector, matrix, file and field.

5.1.1.1 How this Chapter is Organised

In the first sub-chapter some basic concepts of user-defined variables and functions for variable manipulation are explained. Understanding these concepts can help the user to understand the behaviour of the supporting interpreter’s and calculator’s functions. However, it is not absolutely necessary to read through this chapter to comprehend the next ones. Therefore if you find the chapter boring and dry, simply skip it. You can return back later when you will have some insight about what everything is about, or when you feel the need for clearing some conceptual things.

The first part of the first sub-chapter explains what user-defined variables of the shell actually are. The second part offers somehow more practical information about how to address parts of the data stored in user-defined variables in the argument blocks of the user-defined functions. The third part explains the concepts of operations which affect groups of data objects of a given type. Storing groups of objects in a single variable and performing operations on them is a strong feature of the shell. An experienced user can easily take the advantage of this feature.

In the second sub-chapter a rough overview over the basic functions for variable manipulation is made. The examples refer to matrix variables, but similar functions exist for most of the variable types. The user is advised to read this sub-chapter to get a compact view on the subject.

The third sub-chapter describes the functions which enable an advanced way of setting components of the variables. The chapter is in that place because the described functions are used for several variable types. The user is advised to skip the chapter and return to it when needed.

The following sub-chapters include description of functions for handling of different types of variables. The first of these sub-chapters is dedicated to matrix variables. Many things described here are similar for other variable types. Especially the treatment of vector, scalar and field variables is in many terms the same. The user can therefore take this as an representative example which can ease the introduction to the treatment of other variable types. In many cases it will happen, for example, that the user will not need to read a description of a specific function for vector manipulation if he is already familiar with the appropriate function for matrix manipulation.

The last sub-chapter is dedicated to variables with a pre-defined meaning. These variables provide the necessary data links between different modules and operations of the shell. They are of great importance for setting optimisation and inverse problems.

Finally, let me conclude with a useful hint. Maybe it is not bad at all to start at the chapter about matrix variables. At least you will quickly get a feeling about which information you miss to get a clear insight. Have a nice reading!

5.2 Important Note: Naming Recommendations

Although it is currently possible to name two variables of different types by the same name, this should be avoided in Inverse command files. The variable system will undergo substantial changes in the future, and backward compatibility will only be provided for scripts that follow this recommendation. Beside that, variable names should be restricted to those which can be used in C and other language. Names should consist of alphabetic characters (‘A’ to ‘Z’ and ‘a’ to ‘z’), underscores (‘_’) and digits (‘0’ to ‘9’) and should begin either by an alphabetic character or an underscore.

5.3 Basic Concepts of User-defined Variables

Each type of the shell’s user-defined variables has its own set of file interpreter’s and expression evaluator’s functions for manipulating variables of that type. Basic manipulation includes creating, copying, renaming and deleting variables. Beside that, for each type of variables there exists a specific set of operations typical for that type, i.e. algebraic operations and setting or obtaining components for vector and matrix variables.

5.3.1 Tables of Elements

Each user-defined variable can hold a multi-dimensional table of elements of a specific data type. Number of dimensions of this table is called rank of a variable. Variable’s element tables can be thought of as a recursive tables, where the basic level holds a specific number of sub-tables, each of which again holds a number of sub-tables, etc., until the last level which holds a table of elements of a specific type. Numbers of sub-tables or element which level holds are called variable dimensions, and the umber of levels (or dimensions) of a variable is called variable rank. Variables with rank 0 can hold only one element. Variables with rank greater than 0 can hold as many data elements as is the product of variable dimensions.

Example:

Suppose we have a vector variable v with rank 3 and dimensions 2, 3 and 2. The variable can hold 3*2*2=12 elements which are organised in the following way:

Table v: contains 3 sub-tables (because the first dimension is )

Sub-table v[1]: contains 2 sub-tables (because the second dimension is 2)

Sub-table v[1,1]: contains 2 elements (because the third dimension is 2)

Element v[1,1,1]

Element v[1,1,2]

Sub-table v[1,2]: contains 2 elements (because the third dimension is 2)

Element v[1,2,1]

Element v[1,2,2]

Sub-table v[2]: contains 2 sub-tables (because the second dimension is 2)

Sub-table v[2,1]: contains 2 elements (because the third dimension is 2)

Element v[2,1,1]

Element v[2,1,2]

Sub-table v[2,2]: contains 2 elements (because the third dimension is 2)

Element v[2,2,1]

Element v[2,2,2]

Sub-table v[3]: contains 2 sub-tables (because the second dimension is 2)

Sub-table v[3,1]: contains 2 elements (because the third dimension is 2)

Element v[3,1,1]

Element v[3,1,2]

Sub-table v[3,2]: contains 2 elements (because the third dimension is 2)

Element v[3,2,1]

Element v[3,2,2]

The variable v containd three sub-tables, each of which contains two sub-sub tables, each of which contains two vectors. Variable lazout is also shwn in Table 1.

Table 1: Variable v with dimensions 3*2*2.

Level 1:	variable v
Level 2:	*v[1]*		*v[2]*		*v[3]*
Level 3:	*v[1,1]*	*v[1,2]*	*v[2,1]*	*v[2,2]*	*v[3,1]*	*v[3,2]*
Elements:	*v[1,1,1]* *v[1,1,2]*	*v[1,2,1]* *v[1,2,2]*	*v[2,1,1]* *v[2,1,2]*	*v[2,2,1]* *v[2,2,2]*	*v[3,1,1]* *v[3,1,1,2]*	*v[3,2,1]* *v[3,2,2]*

In the case of variables that hold elements which themselves contain tables of elements, e.g. vectors and matrices, the same variable can contain elements of different dimensions. Exept at variables with a pre-defined meaning, it is completely upon user's will which are the dimensions of elements stored in a specific variable. However, this freedom is seldomly used because it decreases the level of organisation.

In the case of multi-dimensional tables, each sub-table of the same level holds the same number of sub-tables or elements, which equals the dimension of that level. Of course, some elements can contain no data.

In the above example, the first level (i.e. the variable itself) contains three sub-tables of the second level (because the first dimension is 3), i.e. v[1], v[2] and v[3]. Each of these contains two sub-tables of the third level (because the second dimension is 2), i.e. v[1] contains v[1,1] and v[1,2], v[2] contains v[2,1] and v[2,2] and v[3] contains v[3,1] and v[3,2]. And each of these sub-tables of the third level contains two elements because the third dimension is 2.

5.3.1.1 Addressing Variable Elements

Special conventions exist about referencing shell’s user-defined variables and their elements in the argument blocks o