Table of Contents:
 
 

1. User-defined Variables *

1. 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 solutio 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.
 
 

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 komprehend 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 somhow more practical information about how to address parts of the data stored in user-defined variables in the argument blocks of the user-defined functios. 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. Especialy 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 expmple, 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 nad 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 bed 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!
 
 
 

2. Basic Concepts of User-defined Variables

 

Manuals list

Manuals list & contents

Table of contents

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.
 
 
 

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., untill 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 themselve 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.
 
 
 

1. Addressing Variable Elements

 

 
 
 
 
 
 
 

Special conventions exist about referencing shell's user-defined variables and their elements in the argument blocks of the file interpreter's functions.

First of all, each variable has its name. Variables of different types can have the same names, e.g. we can have both matrix and vector variable names a1. Usual rules apply for variable names. They are strings which consist of letters and numbers, while the first character of a name must always be a letter.

Since variables can hold multi-dimensional tables of elements, we must specify which element of the variable's element table is in question. This is done by indices which specify the position of an element in the element table. Indices must be listed in square brackets and be separated by spaces or commas. They specify, by turns, from which sub-table of a specific level the element must be taken. Variable name followed by a list of indices in square brackets form the specification of an element. Spaces are allowed between the variable name and index list.

Example:

Let us have a vector variable v of rank 3 and dimensions 3*2*2. The specification v[3,1,2] refers to the second vector of the first sub-sub-table of the third sub-table of the variable v.

Variables of rank 0 can hold only one element, therefore there is no need to specify indices when addressing their only element. Element specification can in this case be only a variable name, or eventually we can put empty square brackets behind the name (e.g. v1, v1[ ]).
 
 
 

2. Addressing Variable Sub-tables and Variables

 

 
 
 
 
 
 
 

Some functions perform operations on whole sub-tables of elements rather than on individual elements of variables. Specification of variables' element sub-tables is similar to specification of individual arguments. The only difference is that few last indices are not specified, i.e. less indices are usually listed than the variable rank. It is always considered than the last indices are missing. A sub-table spcified this way consists of elements which have fixed first indices as specified in the specification, while the rest indices vary in their range (from 1 to the appropriate dimension). As usual, the precedent indices change faster while elements are listed by order.

Example:

Suppose we have a variable v of rank 3 and dimensions 3*2*2. The specification v[2] then refers to a sub-table of rank 2 and dimensions 2*2 with elements v[2,1,1], v[2,1,2], v[2,2,1] and v[2,2,2]. The specification v[2,1]refers to the first sub-table of this table, which contains elements v[2,1,1] and v[2,1,2].

A sub-table specification can also refer to a whole element table of a variable. In this case the specification consists only of a variable name, which can be eventionally followed by empty square brackets, i.e. v or v[ ].

Some operations perform not on data elements or element sub-tables, but on whole variables. The appropriate functions require variable specifications in their argument blocks. These consist only of variable names and may not be followed by square brackets, not even empty ones.
 
 
 

3. Operations on Variable Sub-tables

 

 
 
 
 
 
 
 

Some general rules apply to operations on the element sub-tables of variables. These rules are mostly concerned with the dimension compatibility. The file interpreter's functions which operate on variable sub-tables can be deivided inoto several sub-groups.
 
 

1. Functions that just Perform Operations on Elements (Simple Unary operations)

 

 
 
 
 
 
 
 

These functions iterate over indices of the element sub-tables, take the appropriate elements one by one and perform an operation on them. Sometimes it is important to know which is the order in which elements are taken, because the operations which are performed on the elements can depent on the state of other elements of the sub-table.

The operation begins with the element that has all indices of the sub-table set to 1. indices are then incremented in trns, starting with the last one. When a certain index reaches its range (i.e. the appropriate dimension of the sub-table), it is set to 1 and its preceeding index is incremented. This is repeated untill all indices reach their range.

Example:

Suppose that we have a variable v of dimensions 3*2*2, and we perform an unary operation named unopsimp on the elements of its sub-table v[2]. The code which does that is

unopsimp { v[2] }

and the operation is performed on the elements in the following order:

v[2,1,1], v[2,1,2], v[2,2,1], v[2,2,2].

The first index is fixet since it was given in the specification, while the rest two indices change alternatelz in the above described way.
 
 

2. Functions that Perform Operations on Elements and Store Results in Another Sub-table (Unary Operations Which Store Results)

 

 
 
 
 
 
 
 

These operations usually leave the elements on which they act unchanged, but store the results of the performed operations in the elements of another table (there can be exceptions).

The order in which operations are performed is the same as in the previous case. The difference is that another element sub-table must be specified in which the results of operations are stored. The result table must be of the same dimensions than the one on which the operations are performed. The results of operations on elements of the first sub-table are then stored in the appropriate elements of the result sub-table, i.e. in the elements with the same indices.

Usually, the elementsd of the result sub-table don't need to be initialised. While the results are stored in the table, the elements are appropriately initialised if necessary.

Instead of properly specifying the result dable of the appropriate dimensions, we can only specify the variable name. If a variable with that name does not yet exist, it is created before the beginning of the operation. It is created with the element table of the same dimensions than the dimensions of the element sub-table on which the operation is performed. If a whole variable table is specified (not a sub-table) which exists, but does not have the right dimensions, it is deleted and created anew with the right dimensions. If a result sub-table is specified with wrong dimensions, this is an error and the operation will not be performed.

Specifications of variables or sub-tables on which the operation is performed and in which the results are stored are arguments of the file interpreter's function that performs the operation. Usually, the specification of the sub-table on which the operation is performed, is the first argument, and the specification of the sub-table in which the results are stored, is the second argument of such functions.

Example:

Let's have a variable v of dimensions 3*2*2, a variable r1 with dimensions 4*2*2, a variable r2 with dimensions 3*2. Let's say we want to perform the operation unop on the sub-table v[3] and that we would like to use one of the variables r1 or r2 for storing results of the operation. We can to that different ways:

unop { r1[2] v[3] }

is legal since the dimensions of the sub-tables r2[2]and v[3] match. The operation is performed in turns on elements v[3,1,1], v[3,1,2], v[3,2,1] and v[3,2,2] and the results of the operation are stored in elements r1[3,1,1], r1[3,1,2], r1[3,2,1] and r1[3,2,2], accordingly.

unop { r2 v[3] }

is also legal because the first specification specifies the whole variable table. Since the dimensions do not match, variable r2 is first deleted and then created anew with dimensions 2*2 that match the dimensions os v[3]. The situation is similar if we perform

unop { r1 v[3] }

We can not, however, perform the operation

unop { r1[1] v[3] }

since r1[1] is a sub-table of the variable r1 and it does not have the same dimensions than v[3].
 
 

3. Operations on Pairs of Variable Elements (Binary Operations)
Most of binary operations on pairs of elements of variable sub-tables store their results in a third table of elements. For this result table the same results apply as in the chapter about unary operations which store their results.

There are two possibilities for the element tables on which the operation is performed. They can either be of the same dimensions or one table has a single element. In the second case, the operation combines the single element with all elements of the other sub-table.

At functions which perform binary operations, the specification of the result sub-table (or variable), and specifications of the sub-tables on which the operation is performed, are arguments of these functions. Usualy the specificatios of the sub-tables on which the operation is performed, are the first two arguments, and the specification of the result sub-table is the third argument of such functions. If the appropriate operations are not commutative, the order of the first two arguments matters, too.

Example:

Let us say there are variables v1 of dimensions 3*2*2, v2 of dimensions 5*2*2, v3 of dimensions 4*2, r1 of dimensions 2*2*2, and r2 of dimension 2*3, and a binary operation named binop. Then we can perform the following operations:

binop { r1[2] v1[2] v2[4] }

is valid since all sub-tables have the same dimensions.

binop { r1[ ] v1[2] v2[4] }

is also valid since the first argument specifies the whole element table of the variable r1. This table is not of the same dimension as should the result table be, therefore variable r1 is first deleted and then created with write dimensions (2*2) before the operation is performed.

binop { r2[ ] v3[2,1,2] v2[5] }

is also legal because v3[2,1] specifies a single element. This element is in turns combined with all four elements of the sub-table v2[5], the operation is performed on such pairs and results are stored in the appropriate elements of variable r2. This variable is deleted and then created anew with dimensions 2*2 before the operation begins.

binop { r1[ ] v3 v2[1] }

is not legal since the dimensions of sub-tables v3 and v2[1] do not match.


 
 
3. Basic Operations on User-defined Variables

 

Manuals list

Manuals list & contents

Table of contents

For every tiype of the user-defined shell's variables there is a set of interreter's and calculator's functions for manipulation of these variables. Some of these functions are of a general character and are similar for almost all types of variables.

Among the most important are the file interpreter's functions for creating variables and setting their values. For matrix variables these are functions newmatrix, dimmatrix and setmatrix.

The newmatrix function creates a matrix variable with specific dimensions. The only argument of this function is the name of the matrix variable followed by the list of dimensions in a square bracke. If this bracket is empty or if it is omitted, a variable with rank 0 is created (such variable can hold a single element). If a matrix variable with a given name exists when the newmatrix function is called, it is first deleted and then created.

The dimmatrix function is similar than newmatrix, except that if a matrix variables of a given name already exists and has right dimensions, it is leaved untouched.

The setmatrix function initialises individual elements of a matrix variable according to the value given in its argument block. The first argument is the specification of a matrix element, i.e. a variable name followed by a list of indices). The second argument specifies the values that should be assigned to that matrix element. This includes matrix dimension and all components, although only the dimension or individual components can be given.

If the first argument of the setmatrix function is a complete element specification with a list of indices, a given element must already exist. This can be assured by an appropriate execution of the newmatrix or dimmatrix function. If the element specification is given without an index list and a matrix variable with a given name does not exist yet, it is first created with rank 0. This is the only case when the setmatrix command creates a matrix variable. In other cases the variable must exist before.

Similar functions than newmatrix and dimmatrix exist for other types of variables. They only have different name (string "matrix" is replaced by the appropriate type name). Similar functions to setmatrix exist for other types of variables, with appropriately different names and formats of the second argument which specifies the element values.

Other important general functions are these for copying, moving and printing variables or their elements. For matrix variables, the function movematrixvar renames a matrix variable. The first name is the old and the second argument is a new name of the variable. Function copymatrixvar copies a whole matrix variable to another matrix variable. Again, names of the copied and the result variables are the two arguments of the functions. The movematrixvar function first deletes the second variable if it already exists, while the copymatrixvar function deletes it only if it is not of the right dimensions, and the same applies for individual elements.

The copymatrix function copies sub-tables of elements of matrix variables to another element sub-tables. It behaves like functions which perform unary operations on element sub-tables and store results to another sub-tables. Similarly the movematrix function moves sub-tables of elements to another sub-tables. It also behaves like functions which perform unary operations on element sub-tables and store results to another sub-tables. Particularity of this function is that the elements on which operation is performed are also affected (they are deleted).

The printmatrix prents a sub-table of elements of a matrix variable. It behaves like a simple unary operation. The printmatrixvar function does the same, except that it prints all matrices of the variable's element table and also some additional data about the variable.

For each variable type there are usually one or more expression evaluator's functions which return specific information about the variable's elements. For matrix variables such functions are getmatrix, which returns matrix element's components or dimensions, and getmatrixdim, which returns dimensions or rank of a matrix variable.

For variables that contain numerical information (i.e. scalars, vectors or matrices), there are functions which set the components of these information for sub-tables of variables' elements. For matrix variables such function is setmatrixcomponents or shortly setmatcomp. The first argument of this function is a specification of a sub-group of elements on which the operation is performed. The second argument is a mathematical expression the value of which is evauated and assigned to each component of the group of matrices separately. Two special calculator's functions, namely varindex and varcomponent can be used in functions similar to setmatcomp. The first one returns a specific index of the matrix element, and the second one returns the specific component number of the matrix component which is currently being assigned.
 
 
 

4. Special Expression Evaluator's Functions varindex and varcomponent

 

Manuals list

Manuals list & contents

Table of contents

Calculator's functions varindex and varcomponent are designed to support those file interpreter's functions which iterate over components of the variable's element sub-tables and assigne them values specified by mathemathical expressions. Such functions are, for example, setmatomp, setveccomp, setscalcomp, etc.
 
 

1. varindex [ indexnum ]

Returns a specific index (defined by indexnum) of the variable's element which is currently in the assigment procedure of a function like setmatcomp. The function can be called only in the specific situation where a component of a variable's element is being assigned by a function like setmatcomp.

If the value of indexnum is zero, the function returns the rank (i.e. number of dimensions) of the element table of the variable in the assignment procedure.

Example:

Let us have a matrix variable m of dimensions 2*3 and let us execute the command

setmatcomp { m[2] varindex[0] + 3 * varindex[2] }

When the components of the matrix sub-table are assigned, the term varindex[0] has the value 2 since the rank of variable m is 2. The value of the expression varindex[2] depends on which matrix element is currently in the evaluation procedure, since it returns the second index of that element. For m[2,1] its value is 1, for m[2,2] its value is 2 and for m[2,3] its value is 3. Therefore, all components of m[2,1] will be assigned the value 2 + 3 * 1 = 5, all components of m[2,2]will be assigned the value 2 + 3 * 2 = 8, and all components of m[2,3] will be assigned the value 2 + 3 * 3 = 11.
 
 

2. varcomponent [compnum ]

Returns a specific component index (defined by compnum) of the variable element's component which is currently in the assigment procedure of a function like setmatcomp. The function can be called only in the specific situation where a component of a variable's element is being assigned by a function like setmatcomp.

If the value of compnum is zero, the function returns the number of dimensions of a variable element (e.g. 2 for matrices, 1 for vectors, 0 for scalars).

Example:

Let us have a matrix variable m of dimensions 3*2 where all its elements are 2 by 2 matrices. and let us execute the command

setmatcomp { m[3] 10 * varindex[1] + varindex[2] + 0.1 * varcomponent[1] + 0.01 * varcomponent[2] }

The command affects matrix elements m[3,1] and m[3,2] and sets their components to the following values:

m[3,1]: {{31.11, 31.12}, {31.21, 31.22}}

m[3,2]: {{32.11, 32.12}, {32.21, 32.22}}
 
 

5. Matrix Variables

 

Manuals list

Manuals list & contents

Table of contents

Matrix variables hold matrix objects. These are two-dimensional arrays of decimal numbers. Both dimensions of an array are also a part of a matrix object.

Elements of matrix variables can be empty (uninitialised) which means that they contain no data.
 
 

1. File Interpreter's Functions for Manipulation of Matrix Variables

 
1. newmatrix { varname < [ dim1, dim2, ... ] > }

Creates a new matrix variable named varname with dimensions dim1, dim2, etc. It does not initialise variable elements. The rank of the created matrix variable equals the number of specified dimensions (dim1, dim2, etc.). If no dimensions are specified, a variable with rank 0 is created. If a matrix variable named varname already exists, it is firs deleted (together with its elements).

Explanation:

The shell's variables can hold multi-dimensional tables of objects of a given type (matrices in this case). Variable dimensions refer to the dimensions of such table, and variable rank is the number of these dimensions.
 
 

2. dimmatrix { varname < [ dim1, dim2, ... ] > }

The same a newmatrix, except that if a matrix variable named varname with proper dimensions already exists, it does not delete it.
 
 
3. setmatrix { elspec matspec }

Sets a matrix element specified by elspec to the values specified by matspec. The specification of a matrix element elspec consists of a variable name and an optional index list in square brackets, e.g. m1[2,3]. The index list is not necessary if the rank of the matrix variable is 0.

elspec must address an existing matrix element, except if no indices are specified. In this case a matrix variable of rank 0 is created before the matrix element is set.

matspec specifies the contents, which are assigned to a matrix element. Matrix dimensions and components are normally specified in matspec. Alternatively, only dimensions, individual components, or groups of components can be specified in matspec.

If matrix dimensions are specified in matspec, then if the matrix element specified by elspec already exists, but has wrong dimensions, it is deleted and created again with the right dimensions. If matrix element is not yet initialised, it is created anew. If it exists and has the right dimensions, it is not changed before the components are read.

Just components can be specified in matspec only if the matrix element specified by elspec already exists with the right dimensions.

All matrix components can be specified in matspec, but alternatively only one or only few components can be specified. In this case the components which are not specified remain the same. If these components have not been specified before, they will have indefinite values.

The standard format of matspec is the following:

dim1 dim2 { {1 1 : comp_1,1 } {1 2 : comp_1,2 } ... {2 1 : comp_2,1 } ... }

where dim1 and dim2 are the number of rows and columns, respectively, and comp_1,1, comp_1,2, etc., are matrix components. In the brackets where we specify components, component indices (i.e. the row number and the column number) are specified on the left side of a colon.

Alternatively, whole rows are given in one bracket:

dim1 dim2 { {1: comp_1,1 comp_1,2 ... } {2: comp_2,1 comp_2,2 ... } ... }

or components are just listed by turns, listing row by row:

dim1 dim2 { comp_1,1 comp_1,2 ... comp_2,1 comp_2,2 ... ... }

If row and column numbers are specified with the components, then the order in which components are listed does not matter. Similarly, if only row numbers are specified, the order in which rows are listed does not matter.

All numbers, which occur in the matspec, can be given by mathemathical expressions that are evaluated in the expression evaluator or by expression evaluator's variables.

Examples:

Let us say that we have a matrix variable m of dimensions 2*3 and that we want to assign a 2 by 2 matrix to its element m[1,3]. Let the assigned matrix be a diagonal matrix with diagonal components set to 3.2. In a standard form this is done like this:

setmatrix { m[1 3] 2 2 {{1 1 : 3.2 } { 1 2 : 0 } { 2 1 : 0 } { 2 2 : 3.2 } }

Instead individual components, whole rows can be listed in curlz brackets:

setmatrix { m[1 3] 2 2 {{1 : 3.2 0 } { 2 : 0 3.2 } }

All components can be just listed without specifying their row and column numbers:

setmatrix { m[1 3] 2 2 { 3.2 0 0 3.2 } }

When component numbers are given, the order in which components are specified does not matter. The same matrix can also be set like this:

setmatrix { m[1 3] 2 2 {{ 1 2 : 0 } { 2 2 : 3.2 } { 2 1 : 0 } {1 1 : 3.2 }}

or like this:

setmatrix { m[1 3] 2 2 {{ 2 : 0 3.2 } {1 : 3.2 0 } }

If the matrix element is already initialised with proper dimensions, only components can be specified with the setmatrix command. This can be illustrated with an example where the dimensions and components are specified separately:

setmatrix { m[1 3] 2 2 }

setmatrix { m[1 3] { 3.2 0 0 3.2 } }

With the first setmatrix command the matrix element dimensions are initialised, i.e. a matrix with two rows and two columns is created. With the second setmatrix command the componenets of the matrix element are set. We can furtherly split the setting of components into two parts:

setmatrix { m[1 3] 2 2 }

setmatrix { m[1 3] { 3.2 0 } }

setmatrix { m[1 3] { { 2: 0 3.2 } } }

With the second setmatrix command, only the first two matrix components were set. This means that the whole second row remained unset. We set this row with the third setmatrix command.

All numbers in the setmatrix commands can be replaced by mathematical expressions or by calculator's variables. We can simply put ${expr} or $varname in place of numbers, where expr is a mathematical expression that can be evaluated in the expression evaluator, and varname is a name of the expression evaluator's variable. This and the fact that we can set only dimensions and individual components by the setmatrix command enables additional matrix variables manipulation .

Example:

Let us have a matrix variable of rank 0 named m. The following code creates an exact copy of m named mc regardless of the dimensions of m:

if { ( getmatrix["m",0,1]>0 && getmatrix["m",0,2]>0 )
[
setmatrix { mc ${getmatrix["m",0,1]} ${getmatrix["m",0,2]}}
= {countrow:1}

while { (countrow<=getmatrix["m",0,1])
[
= {countcol:1}
while { (countrow<=getmatrix["m",0,2])
[
setmatrix { mc { {
$countrow $xountcol :
${getmatrix["m",countrow,countcol]}
} }
}
= {countcol:countcol+1}
] }
= {countrow:countrow+1}
] else
[
newmatrix { mc }
] }
 
 

4. copymatrixvar { varname1 varname2 }

Copies the matrix variable named varname1 to the variable named varname2. If the second matrix variable does not yet exist, it is created first. If it exists, it is overwritten.
 
 
5. movematrixvar { varname1 varname2 }

Moves the matrix variable named varname2 to the variable named varname1. If a matrix named varname2 already exists, it is overwritten. After the operation the matrix variable named varname1 no longer exists.
 
 
6. deletematrixvar { varname }

Deletes the matrix variable named varname, together with its elements. After the operation the matrix variable named varname no longer exists.
 
 
7. printmatrixvar { varname }

Prints the information (dimensions and components) about all matrix elements contained in the matrix variable named varname, to the standard output. General information about the matrix variable (e.g. rank and dimensions) is also printed.
 
 
8. fprintmatrixvar { varname }

The same as the printmatrix function, except that it prints to the programme's output file.
 
 
9. copymatrix { subspec1 subspec2 }

Copies a sub-table of matrix elements specified by subspec1 to a sub-table specified by subspec2. Elements are copied one by one from the first sub-table to the appropriate places of the second sub-table. Dimensions of the sub-tables must be the same, except if the second specification (subspec2) refers to the whole element table of a matrix variable (i.e. the specification does not include an index list). In this case, the second variable is created anew if necessary. The old variable is in this case first deleted if it exists.

If the second sub-table already contains matrix elements, they are overwritten by the elements of the first sub-table.
 
 

10. movematrix { subspec1 subspec2 }

oves a sub-table of matrix elements specified by subspec1 to a sub-table specified by subspec2. Elements are moved one by one from the first sub-table to the appropriate places of the second sub-table. Dimensions of the sub-tables must be the same, except if the second specification (subspec2) refers to the whole element table of a matrix variable (i.e. the specification does not include an index list). In this case, the second variable is created anew if necessary. The old variable is in this case first deleted if it exists.

If the second sub-table already contains matrix elements, they are overwritten by the elements of the first sub-table. After the operation, the first sub-table contains only empty (uninitialised) elements.
 
 

11. deletematrix { subspec }

Deletes a sub-table of matrix elements specified by subspec. Matrices in the sub-table are deleted one by one. After the operation is performed, the sub-table contains only empty (non-initialised) elements.

If subspec specifies a whole table of elements of a matrix variable, the matrix variable itself is not deleted. Only its elements become empty (uninitialised).
 
 

12. printmatrix { subspec }

Prints information about elements of a sub-table of matrices specified by subspec.
 
 
13. fprintmatrix { subspec }

Prints information about elements of a sub-table of matrices specified by subspec to the shell's output file (outfile).
 
 
14. setmatrixcomponents { subspec expr }, shortly setmatcomp

Sets the components of all matrices contained in the element sub-table specified by subspec, to the value of the expression expr. The expression expr is evaluated by the expression evaluator for each component separately. The function iterates over all matrices of the sub-table specified by subspec and over all components of these matrices and assigns them values specified by expr.

Two special expression evaluator's functions, varindex and varcomponent are designed for use with functions like setmatcomp. When the expressions expr is being evaluated for a specific component of a specific matrix element, the varindex function returns a specific index of the matrix element that is affected. The varcomponent function returns a specific component index (row or matrix number) of the component, which is currently in the evaluation procedure.

Setting matrix components by the setmatcomp function is much quicker than doing it by programming loops which iterate over matrices of a variable's sub-table and over their components. This is because we avoid iterative calls of interpreter's functions. Instead, only one interpreter's function is called to do the job, the iteration loops are implemented in advance in this function and only the expression exp is evaluated again and again. The evaluation of this expression is very quick because it is parsed and interpreted outside the iteration loops. An already parsed and interpreted expression is evaluated within the iteration loops.

Example:

Let us have a matrix variable m which contains 5*2*3 matrices of dimension 5*2. Let us assign values to all components of the sub-table m[4] in such a way that component values will equal 100 times the first index of the sub-table element plus 10 times the second index of the sub-table element plus 0.1 times the row number plus 0.01 times the column number of components. This is done by the command

setmatcomp { m[4] 100 * varindex[2] + 10 * varindex[3] + 0.1 * varcomponent[1] + 0.01 * varcomponent[2] }
 
 

15. matrixsum { subspec1 subspec2 subspecres }

Adds together matrices from element tables specified by subspec1 and subspec2 and stores the results into matrices on the element table specified by subspecres.

The aim of this function is to demonstrate how binary operations on sub-tables of matrix variables work.
 
 

16. matrixop { spec = < operator > spec < operator spec > }, matop
Performs a matrix operation specified in the argument block. The operation specification consists of object specifications (matrix,    vector and scalar objects) and operators.
 
This function performs some basic matrix and vector operations like multiplication and addition, evaluation of norms and determinants, matrix inversion, solution of systems of equatinos, etc.

One operation can be performed at a time. The argment block of the command is an expression which consists of object specifications (operands) and operators. Object specifications usually start with a two letter prefix which specifies the type of a specific object: s_ for scalars, v_ for vectors and m_ for matrices. This is followed by the specification of an element of a specific type, which is given by variable name and index list in square brackets. No spaces are allowed between the prefix which specifies object type and element specification. Element specification refers to a specific element of a user-defined variable. The operations can be performed only on individual elements (objects) within one call to the matop function, not on tables of elements.

Sometimes the object specification is a mathematical expression which can be evaluated in the expression evaluator. In this case, the expression must be in curly brackets.

Usually the operations which are performed produce some results which is stored in some object. In this case, in the argument block we gave first the specification of the object (variable element) into which the result is stored, followed by the assignment operator =.

The following operations can be performed by the matrixop function:

• matop{m_m0 = m_m1 + m_m2} : matrix m0 becomes the sum of matrices m1 snd m2.
• matop{m_m0 = m_m1 - m_m2} :
• matop{v_v0 = v_v1 + v_v2} : vector v0 becomes the sum of vectors v1 and v2.
• matop{v_v0 = v_v1 - v_v2} : vector v0 becomes the difference between matrices v1 and v2.
• matop{m_m0 = m_m1 * m_m2} : matrix m0 becomes the product of matrices m1 snd m2.
• matop{v_v0 = m_m1 * v_v2} : vector v0 becomes the product of vectors v1 and v2.
• matop{s_s0 = v_v1 * v_v2} : Scalar variable s0 becomes the scalar product of vector variables v1 and v2.
• matop{m_m0 = m_m1 * {expr}} : Matrix m0 becomes matrix m1 multiplied by the value of the expression expr.
• matop{v_v0 = v_v1 * {expr}} : Vector v0 becomes vector v1 multiplied by the value of the expression expr.
• matop{v_x = m_A solve v_b} : Vector x becomes the solution of the equation A x = b
• matop{m_m0 = transpose m_m1} : Matrix m0 becomes the transpose of the matrix m1.
• matop{m_m0 = transpose v_v1} : Matrix m0 becomes th etranspose of the vector v1.
• matop{m_m0 = invert m_m1} : matrix m0 becomes the inverse of th ematrix m1.
• matop{s_s0 = norm m_m1} : Scalar s0 becomes the euclidian norm of the matrix m1 (the square root of the sum of squares of components).
• matop{s_s0 = norm v_v1} : Scalar s0 becomes the euclidian norm of the vector v1.
• matop{m_m0 = normalize m_m1} : Matrix m0 becomes the normalised matrix m1 (its component are divided by its norm).
• matop{v_v0 = normalize v_v1} : Vector v0 becomes the normalized vector v1.
• matop{m_m0 = identitymatrix {expr}} Matrix m0 becomes the identity square matrix of dimension that equals the value of the expression expr.
• matop{m_m0 = zeromatrix {expr1} {expr2}} : .Matrix m0 becomes the zero matrix of dimensions that equal the values of the expressions expr1 and expr2.
• matop{m_m0 = randommatrix {expr1} {expr2}} : Matrix m0 becomes a matrix of dimensions that equal the values of the expressions expr and expr1 with random components between 0 and 1. If only one expression is given, mo becomes a square matrix of the appropriate dimension.
• matop{v_v0 = zerovector {expr}} : Vector v0 becomes a yero vector of the dimension that equals the value of the expression expr.
• matop{v_v0 = randomvector {expr}} : Vector v0 becomes a zero vector of the dimension that equals the value of the expression expr.
Examples

matop { m_m1[2,3] = transpose m_a0[1] }
 
 

2. Expression Evaluator's Functions for Manipulating Matrix Variables

 
1. getmatrix { varname < elind1, elind2, ... > rownum colnum }

Returns a specific matrix component. varname is the name of a matrix variable. elind1, elind2, etc., are the indices, which specify the matrix element on the variable's element table. rownum is the row number and colnum is the column number of the component, which is returned.

If the variable named varname is of rank 0, then no indices elind1, elind2, etc. need to be specified.

If rownim is 0, the function returns number of rows of the matrix if colnum is 1, or number of columns of the matrix if colnum is 2.
 
 

2. getmartixdim { varname dimnum }

Returns the dimnum-th dimension of the matrix variable named varname. If dimnum is 0, it returns the rank of the variable.

6. Vector Variables

 

Manuals list

Manuals list & contents

Table of contents

Vector objects are one-dimensional arrays of decimal numbers. The dimension of an array is also a part of a vector object.

Elements of vector variables can be empty (uninitialised) which means that they contain no data. The dimension and components of such elements are not defined.
 
 

1. File Interpreter's Functions for Manipulating Vector Variables

 
1. newvector { varname < [ dim1, dim2, ... ] > }

Does the same as newmatrix, but for vector variables.
 
 
2. dimvector { varname < [ dim1, dim2, ... ] > }

Does the same asdimmatrix, but for vector variables.
 
 
3. setvector { elspec vecspec }

This function is similar to the corresponding matrix function setmatrix. It sets a vector element specified by elspec to the values specified by vecspec. The specification of a vector element elspec consists of a variable name and an optional index list in square brackets, e.g. v1[2,3]. The index list is not necessary if the rank of the vector variable is 0.

elspec must address an existing vector element, except if no indices are specified. In this case a vector variable of rank 0 is created before the vector element is set.

vecspec specifies the contents which are assigned to the vector element. Vector dimension and components are normally specified in vecspec. Alternatively, only the dimension, individual components, or groups of components can be specified in vecspec.

If vector dimensions are specified in vecspec, then if the vector element specified by elspec already exists, but have a wrong dimension, it is deleted and created again with the right dimension. If vector element is not yet initialised, it is created anew. If it exists and has the right dimension, it is not changed before the components are read.

Just components can be specified in vecspec only if the vector element specified by elspec already exists with the right dimension.

All vector components can be specified in vecspec, but alternatively only one or only few components can be specified. In this case the unspecified components remain the same. If the components have not been specified before, their values will be indefinite.

The standard format of vecspec is the following:

dim { {1 : comp₁ } { 2 : comp₂ } { 3 : comp₃ } ... }

where dim is vector dimension (the number of rcomponents), and comp₁, comp₂, etc., are vector components. In the brackets where we specify components, the component numbers are specified on the left side of a colon.

Alternativaly, the components are just lister by turns:

dim { comp₁ comp₂ comp₃ ... }

If the component numbers are specified with the components, then the order in which components are listed does not matter.

All numbers that occur in the vecspec can be given by mathemathical expressions that are evaluated in the expression evaluator or by expression evaluator's variables.

Examples:

Let us say that we have a vector variable v of dimensions 2*3 and that we want to assign a 4 dimensional vector to its element v[1,3]. Let the assigned vector components have values 1.1, 2.2, 3.3 and 4.4. In a standard form this is done like this:

setvector { v[1 3] 4 { {1 : 1.1 } { 2 : 2.2 } { 3 : 3.3 } { 4 : 4.4 } }

All components can be just listed without specifying their component numbers:

setvector { v[1 3] 4 { 1.1 2.2 3.3 4.4 } }

When component numbers are given, the order in which components are specified does not matter. The same vector can also be set like this:

setvector { v[1 3] 4 { { 3 : 3.3 } {1 : 1.1 } { 4 : 4.4 } { 2 : 2.2 } }

If a vector element is already initialised with proper dimensions, only components can be specified with the setmatrix command. This can be illustrated with an example where the dimensions and components are specified separately:

setvector { v[1 3] 4 }

setvector { v[1 3] { 1.1 2.2 3.3 4.4 } }

With the first setvector command the vector element dimension is initialised, i.e. a vector with four components is created. With the second setvector command the componenets of the vector element are set. We can furtherly split the setting of components into two parts:

setvector { v[1 3] 4 }

setvector { v[1 3] { 1.1 2.2 } }

setvector { v[1 3] { { 3 : 3.3 } { 4 : 4.4 } } }

With the second setvector command, only the first two vector components were set. The rest components were set by the third setvector command.

All numbers in the setvector commands can be replaced by mathematical expressions or by calculator's variables. We can simply put ${expr} or $varname in place of numbers, where expr is a mathematical expression that can be evaluated in the expression evaluator, and varname is a name of an expression evaluator's variable. This and the fact that we can set only dimensions and individual components by the setvector command enables additional vector variables manipulation .

Example:

The following code creates a zero rank vector variable tab which holds a table of valuesof the exponential function on the interval [0,1] with step 1:

= {currentx: 0}

= {lastx: 10}

= {step: 1}

= {dim: 11}

setvector {tab dim}

= {compnum : 1}

while { (currentx<=lastx)

[

setvector {tab { { $compnum : exp[currentx] } }}

= {currentx:currentx+step}

= {compnum:compnum+1}

] }
 
 

4. copyvectorvar { varname1 varname2 }

Does the same as copymatrixvar, but for vector variables.
 
 
5. movevectorvar { varname1 varname2 }

Does the same as movematrixvar, but for vector variables.
 
 
6. deletevectorvar { varname }

Does the same as deletematrixvar, but for vector variables.
 
 
7. printvectorvar { varname }

Does the same as printmatrixvar, but for vector variables.
 
 
8. fprintvectorvar { varname }

Does the same as frintmatrixvar, but for vector variables.
 
 
9. copyvector { subspec1 subspec2 }

Does the same as copymatrix, but for vector variables.
 
 
10. movevector { subspec1 subspec2 }

Does the same as movematrix, but for vector variables.
 
 
11. deletevector { subspec }

Does the same as deletematrix, but for vector variables.
 
 
12. printvector { subspec }

Does the same as printmatrix, but for vector variables.
 
 
13. fprintvector { subspec }

Does the same as fprintmatrix, but for vector variables.
 
 
14. setvectorcomponents { subspec expr }, shortly setveccomp

This function is similar to its matrix equivalent setmatcomp. It sets the components of all vectors contained in the element sub-table specified by subspec, to the value of the expression expr. The expression expr is evaluated by the expression evaluator for each compponent separately. The function iterates over all vectors of the sub-table specifiefd by subspec and over all components of these vectors and assignes them values specified by expr.

Two special expression evaluator's functions, varindex and varcomponent are designed for use with functions like setveccomp. When the expressions expr is being evaluated for a specific component of a specific vector element, the varindex function returns a specific index of the vector element that is affected. The varcomponent function returns the number of the component which is currently in the evaluation procedure. It must be called with argument 1, although vector objects have only one dimension anyway (because of compatibility reasons).

Setting vector components by the setveccomp function is much quicker than doing it by programming loops which iterate over vectors of a variable's sub-table and over their components. This is because we avoid iterative calls to interpreter's functions. Instead, only one interpreter's function is called to do the job, the iteration loops are implemented in advance in this function and only the expression exp is evaluated again and again. The evaluation of this expression is very quick because it is parsed and interpreted outside the iteration loops.

Example:

Let us have a vector variable v which contains 6*3*4 vectors of dimension 10. Let us assign values to all components of the sub-table v[3] in such a way that component values will equal 10 times the first index of the sub-table element plus the second index of the subtable element plus 0.1 times the component number. This is done by the command

setveccomp { v[3] 10 * varindex[2] + varindex[3] + 0.1 * varcomponent[1] }
 
 

15. vectorsum { subspec1 subspec2 subspecres }

Does the same as matrixsum, but for vector variables. The aim of this function is mostly to demonstrate how binary operations on variable sub-tables work.

 
2. Expression Evaluator's Functions for Manipulating Vector Variables

 
1. getvector { varname < elind1, elind2, ... > compnum }

Returns a specific vector component. varname is the name of a vector variable. elind1, elind2, etc., are the indices which specify the vector element on the variable's element table. compnum is the number of the component which is returned.

If the variable named varname is of rank 0, then no indices elind1, elind2, etc. do not need to be specified.

If compnum is 0, then the function returns the dimension (number of components) of the vector element.
 
 

2. getvectordim { varname dimnum }

The same as getmatrixdim, but for vector variables.

 
 
7. Scalar Variables

 

Manuals list

Manuals list & contents

Table of contents

Scalar objects are simply decimal numbers.

Elements of scalar variables can be empty (uninitialised) which means that they contain no data, the same as elements of vector or matrix variables..
 
 

1. File Interpreter's Functions for Manipulating Scalar Variables

 
1. newscalar { varname < [ dim1, dim2, ... ] > }

Does the same as newmatrix, but for scalar variables.
 
 
2. dimscalar { varname < [ dim1, dim2, ... ] > }

Does the same asdimmatrix, but for scalar variables.
 
 
3. setscalar { elspec scalspec }

Sets a scalar element specified by elspec to the value specified by scalspec. The specification of a scalar element elspec consists of a variable name and an optional index list in square brackets, e.g. s1[2,3]. The index list is not necessary if the rank of the scalar variable is 0.

elspec must address an existing scalar element, except if no indices are specified. In this case a scalar variable of rank 0 is created before the scalar element is set.

scalspec specifies the value which is assigned to the scalar object. It can be given as a number, as a mathematical expression that can be evaluated by the expression evaluator, or as an expression evaluator's variable. Expressions in place of numbers must be of the form ${expr} where expr is a mathematical expression, and calculator's variables in place of numbers must be of the form $varname, where varname is the calculator's variable name.
 
 

4. copyscalarvar { varname1 varname2 }

Does the same as copymatrixvar, but for scalar variables.
 
 
5. movescalarvar { varname1 varname2 }

Does the same as movematrixvar, but for scalar variables.
 
 
6. deletescalarvar { varname }

Does the same as deletematrixvar, but for scalar variables.
 
 
7. printscalarvar { varname }

Does the same as printmatrixvar, but for scalar variables.
 
 
8. fprintscalarvar { varname }

Does the same as printmatrixvar, but for scalar variables.
 
 
9. copyscalar { subspec1 subspec2 }

Does the same as copymatrix, but for scalar variables.
 
 
10. movescalar { subspec1 subspec2 }

Does the same as movematrix, but for scalar variables.
 
 
11. deletescalar { subspec }

Does the same as deletematrix, but for scalar variables.
 
 
12. printscalar { subspec }

Does the same as printmatrix, but for scalar variables.
 
 
13. printscalar { subspec }

Does the same as fprintmatrix, but for scalar variables.
 
 
14. setscalarcomponents { subspec expr }, shortly setscalcomp

This function is similar to its matric equivalent setmatcomp. It sets the values of all scalars contained in the element sub-table specified by subspec, to the value of the expression expr. The expression expr is evaluated by the expression evaluator for each scalar separately.

A special expression evaluator's function varindex is designed for use with functions like setscalcomp. When the expressions expr is being evaluated for a specific scalar element, the varindex function returns a specific index of the scalar element that is affected.

It makes sense to use this function only with scalar variables with rank greater than zero, especially if they contain a large number of scalars. It is differently with matrix and vector variables where element themselves hold more components.

The varcomponent function can not be used woth setscalcomp since scalars are simple objects without components.

Varning:

The setscalcomp function assigns values only to those scalars which are initialised. It has no effect if it is performed on a sub-table the elements of which are not initialised. Note that functions which create scalar variables like newscalar or dimscalar usually do not initialise the scalars on variable's element table.

Example:

Let us have a scalar variable s which contains 2*3*4 scalars. Let us assign values to all components of the sub-table s[2] in such a way that scalar values will equal 10 times the first index of the sub-table element plus the second index of the sub-table element. This is done by the command

setscalcomp { s[3] 10 * varindex[2] + varindex[3] }
 
 

15. scalarsum { subspec1 subspec2 subspecres }

Does the same as matrixsum, but for scalar variables. The aim of this function is mostly to demonstrate the use of binary operations performed on sub-table of variable's elements.

 
2. Expression Evaluator's Functions for Manipulating Scalar Variables

 
1. getscalar { varname < elind1, elind2, ... > }

Returns the value of a specific scalar object. varname is the name of a scalar variable. elind1, elind2, etc., are the indices which specify the scalar element on the variable's element table.

If the variable named varname is of rank 0, then no indices elind1, elind2, etc. do not need to be specified.
 
 

2. getscalardim { varname dimnum }

The same as getmatrixdim, but for scalar variables.

 
 
8. Counter Variables

 

Manuals list

Manuals list & contents

Table of contents

Counter objects are integer numbers.

Elements of counter variables can be empty (uninitialised) which means that they contain no data, the same as elements of vector or matrix variables.
 
 

1. File Interpreter's Functions for Manipulating Counter Variables

 
1. newcounter { varname < [ dim1, dim2, ... ] > }

Does the same as newmatrix, but for counter variables.
 
 
2. dimcounter { varname < [ dim1, dim2, ... ] > }

Does the same asdimmatrix, but for counter variables.
 
 
3. setcounter { elspec countspec }

Sets a counter element specified by elspec to the value specified by countspec. The specification of a counter element elspec consists of a variable name and an optional index list in square brackets, e.g. cc[2,3]. The index list is not necessary if the rank of the counter variable is 0.

elspec must address an existing counter element, except if no indices are specified. In this case a counter variable of rank 0 is created before the counter element is set.

countspec specifies the value which is assigned to the counter object. It can be given as a number, as a mathematical expression that can be evaluated by the expression evaluator, or as an expression evaluator's variable. Expressions in place of numbers must be of the form ${expr} where expr is a mathematical expression, and calculator's variables in place of numbers must be of the form $varname, where varname is the calculator's variable name.

Warning:

countspec can also result in a decimal. In this case, it is first rounded and then assigned to the appropriate element of a counter variable.
 
 

4. copycountervar { varname1 varname2 }

Does the same as copymatrixvar, but for counter variables.
 
 
5. movecountervar { varname1 varname2 }

Does the same as movematrixvar, but for counter variables.
 
 
6. deletecountervar { varname }

Does the same as deletematrixvar, but for counter variables.
 
 
7. printcountervar { varname }

Does the same as printmatrixvar, but for counter variables.
 
 
8. fprintcountervar { varname }

Does the same as fprintmatrixvar, but for counter variables.
 
 
9. copycounter { subspec1 subspec2 }

Does the same as copymatrix, but for counter variables.
 
 
10. movecounter { subspec1 subspec2 }

Does the same as movematrix, but for counter variables.
 
 
11. deletecounter { subspec }

Does the same as deletematrix, but for counter variables.
 
 
12. printcounter { subspec }

Does the same as printmatrix, but for counter variables.
 
 
13. fprintcounter { subspec }

Does the same as fprintmatrix, but for counter variables.
 
 
14. setcountercomponents { subspec expr }, shortly setcountcomp

This function is similar to its matric equivalent setscalcomp. It sets the values of all counters contained in the element sub-table specified by subspec, to the value of the expression expr. The expression expr is evaluated by the expression evaluator for each counter separately.

A special expression evaluator's function varindex is designed for use with functions like setcountcomp. When the expressions expr is being evaluated for a specific counter element, the varindex function returns a specific index of the counter element that is affected.

It makes sense to use this function only with counter variables with rank greater than zero, especially if they contain a large number of counters. It is differently with matrix and vector variables where element themselves hold more components.

The varcomponent function can not be used woth setcountcomp since counters are simple objects without components.

Varning:

The setcountcomp function assigns values only to those counters which are initialised. It has no effect if it is performed on a sub-table the elements of which are not initialised. Note that functions which create counter variables like newcounter or dimcounterusually do not initialise the counters on variable's element table.

Example:

Let us have a counter variable c which contains 2*3*4 counters. Let us assign values to all components of the sub-table c[2] in such a way that counter values will equal 10 times the first index of the sub-table element plus the second index of the sub-table element. This is done by the command

setcountcomp { c[3] 10 * varindex[2] + varindex[3] }
 
 

15. countersum { subspec1 subspec2 subspecres }

Does the same as matrixsum, but for counter variables. The aim of this function is mostly to demonstrate the use of binary operations performed on sub-table of variable's elements.

 
2. Expression Evaluator's Functions for Manipulating Counter Variables

 
1. getcounter { varname < elind1, elind2, ... > }

Returns the value of a specific counter object. varname is the name of a counter variable. elind1, elind2, etc., are the

indices which specify the counter element on the variable's element table.

If the variable named varname is of rank 0, then no indices elind1, elind2, etc. do not need to be specified.

2. getcounterdim { varname dimnum }

The same as getmatrixdim, but for counter variables.

 
9. Options

 

Manuals list

Manuals list & contents

Table of contents

Oprions are object that can have two values:0 or 1. We also say that they are unset (value 0) or set (value 1). Usually they are used to control behaviour of various functions of the shell.

No special type of variables is prepared for carrying options. Rather than that, options are hold by counter variables. An option hold in a counter variable is considered to be 0 if the appropriate counter is 0, and 1 if the appropriate counter is different than zero.

If a counter that represents a specific option does not exist or is not initialised, the appropriate option is considered to be 0.

Actually, the file interpreter's and expression evaluator's functions for manipulating counter variables could be used for handling options. Nevertheless, there are a few functions that are created especially for setting options and checking their status. The main reason for that is maintaining greater clarity of the code in the command file.
 
 

1. File Interpreter's Functions for Handling Options

 
1. setoption { optspec }

Sets the option specified by optspec. optspec is the specification of the counter element that represents the option. The appropriate counter element is set to 1.
 
 
2. clearoption { optspec }

Clears the option specified by optspec. optspec is the specification of the counter element that represents the option. The appropriate counter element is set to 0 if it exists, otherwise nothing happens.
 
 
2. Expression Evaluator's Functions for Handling Options

 
1. getoption { varname < elind1, elind2, ... > }

Returns 1 if the specified option is set and 0 if it is not set. varname is the name of a counter variable. elind1, elind2, etc., are the indices which specify the counter element that holds the option, on the variable's element table. If the counter variable named varname is of rank 0, then no indices elind1, elind2, etc. do not need to be specified.

A specific option is considered to be set, if the appropriate counter element exists, is initialised and is different than zero. Otherwise, this option is considered to be unset.
 
 
 

10. Field Variables

 

Manuals list

Manuals list & contents

Table of contents


 
1. File Interpreter's Functions for Manipulating Field Variables

 
1. newfield {varname < [dim1, dim2,...]> }

Does the same as newmatrix, but for field variables.
 
2. dimfield { varname < [dim1, dim2,...]> }

Does the same as dimmatrix, but for field variables.
 
3. setfield {elspec fieldspec }

Does the same as setmatrix, but for field variables.
 
4. initfield {subspec fieldspec }

Does the same as initmatrix, but for field variables.
 
5. copyfieldvar{ varname1 varname2 }

Does the same as copymatrixvar, but for field variables.
 
6. movefieldvar{ varname1 varname2 }

Does the same as movematrixvar, but for field variables.
 
7. deletefieldvar{ varname }

Does the same as deletematrixvar, but for field variables.
 
8. printfieldvar{ varname }

Does the same as printmatrixvar, but for field variables.
 
9. fprintfieldvar{ varname }

oes the same as fprintmatrixvar, but for field variables.
 
10. copyfield{ subspec1 subspec2 }

Does the same as copymatrix, but for field variables.
 
11. movefield{ subspec1 subspec2 }

Does the same as movematrix, but for field variables.
 
12. deletefield{ subspec }

Does the same as deletematrix, but for field variables.
 
13. printfield{ subspec }

Does the same as printmatrix, but for field variables.
 
14. fprintfield{ subspec }

Does the same as fprintmatrix, but for field variables.
 
15. setfieldcomponents{ subspec expr }

Does the same as setmatrixcomponents, but for field variables.
 
16. setfldcompcond{ subspec (cond) expr }

Does the same as setmatcompcond, but for field variables.
 
17. filereadfieldcomp { filespec fieldspec <lin col> <next> }

Function reads an array of numbers from an arbitrary file at the current position and stores its components to a programme's field variable. The first argument of the function (fieldspec) is a specification of the field variable. Standard form of the variable specification consists of the variable name and optionally the index table in square brackets. Arguments lin, col and next are optional. By specifying arguments lin and col user sets the dimension of the field variable where the array components are stored to. These arguments must always be specified together. If they are not specified, field variable dimension is set to the dimension of the array found in the input file. If optional argument next is specified, the position of the first byte after the last array component is assigned to the expression evaluator's variable with the same name.
Reading of the array components starts at the current position in the file. If filespec is not defined, an error report is written to the standard output and to the programme's output file. If field variable fieldspec is not defined, a new field variable with name fieldspec and rank 0 is created. This action is reported to the standard output and to the programme's output file. If creating is not successful an error report is written to the standard output and to the programme's output file. If field variable fieldspec exists its contents is overwritten at function call. If arguments lin and col are specified and the dimensions of the field variable is greater than the dimensions of the actual array in the input file, fieldspec gets NULL value. If number of arguments is smaller than 2 or greater than 5 an error report is written to the standard output and to the programme's output file.
 
18. filewritefieldcomp { filespec fieldspec }

Appends field components stored in field variable fieldspec to an arbitrary file filespec. File filespec has to be opened for writing. The output is formatted as an array of numbers delimited by spaces. Dimensions of the array are the same as the dimensions of the field variable fieldspec (lin x col).
Possible errors that can occur are:
• output file filespec is not defined
• field variable fieldspec is not defined
In both cases an error report is written to the standard output and to the programme's output file.
 
19. filereplacefield { filespec fieldspec fieldname searchpos <start>}

Searches for the first field with name fieldname in an arbitrary input file filespec from position searchpos on and replaces its components by components stored in field variable fieldspec. start is an optional argument. If it is specified, the position of the beginning of an array of field components is assigned to the expression evaluator's variable with the same name.
Possible errors that can occur are:
• input file filespec is not defined
• field variable fieldspec is not defined
• string fieldname is not found between position searchpos and EOF
• number of arguments is not equal 4 or 5
In all of these cases an error report is written to the standard output and to the programme's output file.

 
1. Expression Evaluator's Functions for Manipulating Field Variables
   
   
1. getfield{varname <elind1, elind2,...> rownum colnum }

Does the same as getmatrix, but for field variables.
 
 
2. getfielddim{varname dimnum }

Does the same as getmatrix, but for field variables.

 
 
 
6. File Variables

 

Manuals list

Manuals list & contents

Table of contents

File objects are sused in the shell to establish the connection with files on the disk. File objects hold basic information about files, i.e. the file pointer, the file name, the current position, and the mode in which the file is open. Each file object can be connected with a physical file or not. Various shell's functions that deal with files shell access files through file objects.

Elements of file variables can be empty (uninitialised) which means that they contain no data and that they are not connected with any files.
 
 

1. File Interpreter's Functions for Manipulating File Variables

 
1. newfile { varname < [ dim1, dim2, ... ] > }

Does the same as newmatrix, but for file variables.
 
 
2. dimfile { varname < [ dim1, dim2, ... ] > }

Does the same asdimmatrix, but for file variables.
 
 
3. setfile { elspec filespec }

Sets a file element specified by elspec to the value specified by filespec. The specification of a file element elspec consists of a variable name and an optional index list in square brackets, e.g. f1[2,3]. The index list is not necessary if the rank of the file variable is 0.

elspec must address an existing file element, except if no indices are specified. In this case a file variable of rank 0 is created before the file element is set.

filespec specifies the value of the file object. It consists of the file name (i.e. the name of the physical file) and optional mode in which the file is open:

filespec = filename < openmode >

openmode ia a string which defines how the file must be open. It consists of one or two letters, with the following possibilities: r, w, a, r+, w+, a+ (Table 1).
 

Table 2: Meaning of different opening modes for files.
 

mode	meaning
r	Opens the file for reading. The file must have existed before if we want to open it in this mode. The file position is set to the beginning of the file (i.e. 1).
w	Opens the file for writing. If the file already exists, it is overwritten. If it does not exist, it is created anew.
a	Opens the file for appending. This option is similar to w, except that the old content of the file is not overwritten if it has existed before. The file position is set to the end of the file.
r+	The same as r, except that writing to the file is also possible.
w+	The same as w, except that reading from the file is also possible.
a+	The same as a, except that reading from the file is also possible.

The setfile function opens the file in the mode specified. If the setfile function is repeated with the same file object, the file connected to that object is closed if it was open before the execution of the command and vice versa.
 
 

4. copyfilevar { varname1 varname2 }

Does the same as copymatrixvar, but for file variables.
 
 
5. movefilevar { varname1 varname2 }

Does the same as movematrixvar, but for file variables.
 
 
6. deletefilevar { varname }

Does the same as deletematrixvar, but for file variables. The files that are deleted are closed first.
 
 
7. printfilevar { varname }

Does the same as printmatrixvar, but for file variables. The name of the physical file, the current position in the physical file and the opening mode of the file are printed for each file element.
 
 
8. fprintfilevar { varname }

Does the same as printmatrixvar, but for file variables. The name of the physical file, the current position in the physical file and the opening mode of the file are printed for each file element.
 
 
9. copyfile { subspec1 subspec2 }

Does the same as copymatrix, but for file variables.
 
 
10. movefile { subspec1 subspec2 }

Does the same as movematrix, but for file variables.
 
 
11. deletefile { subspec }

Does the same as deletematrix, but for file variables. The files that are deleted are closed first.
 
 
12. printfile { subspec }

Does the same as printmatrix, but for file variables.
 
 
13. fprintfile { subspec }

Does the same as fprintmatrix, but for file variables.

 
2. Expression Evaluator's Functions for Manipulating File Variables

 
1. getfile { varname dataid < elind1, elind2, ... > }

Returns specific data about a specific file object. varname is the name of a file variable. elind1, elind2, etc., are the indices which specify the file element on the variable's element table. If the variable named varname is of rank 0, then no indices elind1, elind2, etc. need to be specified.

dataid specifies which data about the file object must be returned. According to the value of dataid, the function returns the following:
 

dataid	what is returned by getfile
0	1 if the file is open, 0 otherwise.
1	1 if the file is open for reading, 0 otherwise.
2	1 if the file is open for writing, 0 otherwise.
3	The current position of the file; positions start with 1 and mean the positions in the file in bytes where the operations act.


 

2. getfiledim { varname dimnum }

The same as getmatrixdim, but for file variables.

 
 
7. Shell's Variables with a Pre-defined Meaning

 

Manuals list

Manuals list & contents

Table of contents

Some variables of the shell have a pre-defined meaning and are supposed to be used for a particular purpose. They are basically still user-defined variables and behave in many terms the same as other user-defined variables. They are distinguished in a sense that they are used to accomplish specific tasks. Besides, some operations that act on variables of specific types treat the pre-defined variables in a slightly different way, usually with some additional automatism.

Each pre-defined variable serves for specific tasks. Some of them store results of operations and algorithms without this should be specified by the user. These results are automatically available for further use after the appropriate operations are finished. The others serve for data exchange between different shell's functions, e.g. between optimisation algorithms and the function, which performs the direct analysis. Both kinds of variables are supposed to carry the information with exactly defined meaning, e.g. the current value of the objective function or the optimised values of parameters. Furtherly, we can find yet another group of pre-defined variables. These simply serve as variables on which certain operations act without the variable in use is explicitly specified. A typical example is the shell's output file (variable outfile) to which the output of the function fwrite (and many others) is directed, although this is never explicitly specified.

There is usually some additional automatism connected with the pre-defined variables. For example, when a pre-defined file outfile is open by the setfile function, the file is open for writing without this is explicitly specified in the argument block of the setfile command. When a pre-defined vector or matrix variable is set by the setvector or setmatrix command, it is not necessary to specify the variable dimensions if the dimensions are known from what was done in the shell before.

To generalise the above statements, we can establish that there is usually some information related with the pre-defined variables which has more general meaning. Such information is for example the number of optimisation parameters. Dimensions of several pre-defined vector, matrix and scalar variables are bound to the number of parameter. Once the number of parameters is known to the shell, the appropriate dimensions of pre-defined variables that are bound to this information are also known and they need not to be specified in some functions which operate on variables.

Such general information as the number of parameters are stored in theshell in special places separatedfrom the system of user-defined variables. These information either exist in advance (e.g. the information that the pre-defined file outfile should normally be open for writing) or are set when some related actions are undertaken. For example, the number of parameteers is set when the appropriate dimension of any pre-defined variable related to this information is set (e.g. the dimension of the vector parammom or paramopt). The user can access (i.e. set and get) these information in two ways: through the dependent information about variables and through the appropriate expression evaluator's and file interpreter's functions.
 
 
 

1. Pre-defined Matrix, Vector and Scalar Variables

 
Matrix, vector and scalar pre-defined variables hold general information which is directly related to optimisation or inverse problems, like the initial, current and optimal values of parameters, experimental measurements and their errors, simulated measurements, the objective function and the constraint functions and their derivatives with respect to parameters,etc. It is obvious that groups of these variables are related through their dimensions. For example, the vector of (curtrent) parameters has the same dimension as the gradient of the objective function.

General information related to these pre-defined variables are listed in Table 3. These information are not stored in the user-defined variables, but in the internal shel's variables. They can be obtained and set through special expression evaluator's and file interpreter's functions.

Table 3: general information related to some pre-defined matrix, vector, and scalar variables:
 

information	meaning
numparam	The number of optimisation parameters
numconstraints	The number of constraint functions
numobjectives	The number of the objective functions (usually equals 1)
nummeas	The number of measurements (applicable for inverse problems)

Some automatism is built in the shell regarding the pre-defined matrix, vector and scalar variable. This especially concerns the file interpreter's functions that assign values to variable elements or allocate variables. When a specific dimensions of any of these pre-defined variables or their elements is set, the appropriate internal shell's variable related to that dimension changes accordingly.

The oposite is also valid: When we call functions that set the values of variable elements, we do not need to specify dimensions that are determined by the shell's internal variables that have defined values.

Example:

Let's say that we set the vector of initial guesses param0 with dimension 3:

setvector {param0 3 { 2.43 5.34 6.444 }}

Since this pre-defined vector has by definition the dimension numparam, the shell's internal variable numparam is automatically set to 3. The same effect would have, for example, the code

setvector {paramopt 3 }

since the pre-defined vector paramopt has by definition the same dimension (numparam).

If we then set the vector of current parameter values parammom, we do not need to specify its dimension, although the vector variable does not yet exist and will be created anew. This is because the dimension of this vector, which is by definition numparam, is already known since it was set implicitly when the dimension of the vector param0 or paramopt was set. Therefore, we can set the vector parammom simply by specifying components:

setvector {parammom { 1.64 22.3 101.1 }}
 
 

1. Scalar Pre-defined Variables

 

pre-defined scalar variable	characterisation of the variable
objectivemom [] < [numobjectives] >	Value(s) of the objective function(s) at the current parameter values.
objectiveopt [] < [numobjectives] >	Value(s) of the objective function(s) at the optimal values of parameters.
objective0 [] < [numobjectives] >	Value(s) of the objective function(s) at the initial guess.
constraintmom [numconstraints]	Values of the constraint functions at the current values of parameters.
constraintopt [numconstraints]	Values of the constraint functions at the optimal values of parameters.
constraint0 [numconstraints]	Values of the constraint functions at the initial guess.


 
 
 
2. Vector Pre-defined Variables

 

pre-defined vector variable	characterisation of the variable
parammom [] (numparam)	Current vaules of parameters.
paramopt [] (numparam)	Optimal values of parameters.
param0 [] (numparam)	Initial guess for parameters.
parammomold [] (numparam)	A copy of current parameter values (usually made when the current parameters are transformed).
transf [] (numparam)	Vector of transformed parameters.
direction [] (numparam)	Directin of a line search.
startpoint [] (numparam)	Initial point of the line search.
meas [] (nummeas)	Experimental measurements (used at inverse analyses)
sigma [] (nummeas)	Vector of measurement errors.
measexact [] (nummeas)	Exact measurements; Imaginary quantity that is used e.g. at monte carlo simulations with aim to estimate the influence of the measurement errors on the results.
measmom [] (nummeas)	Current values of simulated measurements.
measopt [] (nummeas)	Simulated measurements in the optimum (i.e. solution of the inverse problem).
meas0 [] (nummeas)	Simulated measurements at the starting guess (i.i. param0).
gradobjectivemom [] <[numobjectives]> (numparam)	Gradient of the objective function(s) at the current parameter vlues.
gradobjectiveopt [] <[numobjectives]> (numparam)	Gradient of the objective function(s) at the optimum.
gradobjective0 [] <[numobjectives]> (numparam)	Gradient of the objective function(s) at the initial guess.
gradconstraintmom [numconstraints] (numparm)	Gradients of the constraint functions at the current parameter values.
gradconstraintopt [numconstraints] (numparam)	Gradients of the constraint functions at the optimal values of parameters.
gradconstraint0 [numconstraints] (numparam)	Gradients of the constraint functions at the initial guess.
gradmeasmom [nummeas] (numparam)	Gradients of the simulated measurements at the current values of parameters.
gradmeasopt [nummeas] (numparam)	Gradients of the simulated measurements at the optimum.
gradmeas0 [nummeas] (numparam)	Gradients of the simulated measurements at the initial guess.


 
 
 
3. Matrix Pre-defined Variables
 

pre-defined matrix variable	characterisation of the variable
der2objectivemom [] < [numobjectives] > (numparam,numparam)	Second derivatives (Hessian) of the objective function(s) at the current values of parameters.
der2objectiveopt[] < [numobjectives] > (numparam,numparam)	Second derivatives (Hessian) of the objective function(s) at the optimal values of parameters.
der2objective0[] < [numobjectives] > (numparam,numparam)	Second derivatives (Hessian) of the objective function(s) at the initial guess.
der2constraintmom [numconstraints] (numparam,numparam)	Second derivatives (Hessian) of the constraint functions at the current values of parameters.
der2constraintopt [numconstraints] (numparam,numparam)	Second derivatives (Hessian) of the constraint functions at the optimal values of parameters.
der2constraint0 [numconstraints] (numparam,numparam)	Second derivatives (Hessian) of the constraint functions at the initial guess.
der2measmom [nummeas] (numparam,numparam)	Second derivatives (Hessian) of the simulated measurements at the current values of parameters.
der2measopt [nummeas] (numparam,numparam)	Second derivatives (Hessian) of the simulated measurements at the optimal values of parameters.
der2meas0 [nummeas] (numparam,numparam)	Second derivatives (Hessian) of the simulated measurements at the initial guess.


 
2. File Interpreter's Functions for Setting Shell's Internal Data Related to Pre-defined Variables

 
1. setnumparam { val }

Sets the number of parameters numparam to val. Val is a numerical argument, which means that it can be given as a number, as a mathematical expression in the form ${expr} or as an expression evaluator's variable in the form $varname. If a non-integer value is given for val, it is rounded.
 
 
2. setnumobjectives { val }

Sets the number of objective functions numobjective to val. By default, this number is set to 1. Val is a numerical argument, which means that it can be given as a number, as a mathematical expression in the form ${expr} or as an expression evaluator's variable in the form $varname. If a non-integer value is given for val, it is rounded.
 
 
3. setnumconstraints { val }

Sets the number of constraint functions numconstraints to val. Val is a numerical argument, which means that it can be given as a number, as a mathematical expression in the form ${expr} or as an expression evaluator's variable in the form $varname. If a non-integer value is given for val, it is rounded.
 
 
4. setnummeas { val }

Sets the number of measurements nummeas to val. Val is a numerical argument, which means that it can be given as a number, as a mathematical expression in the form ${expr} or as an expression evaluator's variable in the form $varname. If a non-integer value is given for val, it is rounded.
3. Expression Evaluator's Functions for Accessing Shell's Internal Data Related to Pre-defined Variables

 
1. getnumparam [ ]

Returns the number of parameters numparam.
 
 
2. getnumobjectives[ ]

Returns the number of objective functions numobjectives.
 
 
3. getnumconstraints [ ]

Returns the number of constraint functions numconstraints.
 
 
4. getnummeas [ ]

Returns the number of measurements nummeas.
4. Pre-defined File Variables

 

 
 
 
 
 

The pre-defined file variables represent files which have a specific meaning in the shell, e.g. the shell's output file or the input and output file of the direct analysis. Some operations act exclusively in these pre-defined files. For example, the fwrite function prints its output to a pre-defined file outfile.

The pre-defined file variables should have rank 0, although this is not always necessary. However, in all cases only the first element of the file variable's element table can be involved in operations that act on pre-defined files. The user should avoid defining pre-defined variables with rank greater than zero.
 
 

1. File Pre-defined Variables

 

pre-defined file variable	characterisation of the variable
infile []	Shell-s input file.
outfile []	Shell-s output file.
aninfile []	The simulation (direct analysis) input file.
anoutfile []	The simulation (direct analysis) output file.