2. UniScript in Examples

The following examples will show you how to use UniScript. Start UniPlot and type in the examples yourself.

Start UniPlot by double-clicking the UniPlot icon in the Program Manager. After UniPlot is started, click on the calculator Main_Command button in the toolbar or select View=>Command Window. The UniScript command window will look similar to this:

../../_images/UniScriptScreenShot-en.png

The asterisk * is the UniScript prompt. The prompt indicates that UniScript is ready for your input.

Now enter some of the following line expressions:

* 7+12
    19.0000
* 5-7
    -2.0000
* 3*5
    15.0000
* 1/2
    0.5000
* (2+5)*5
    35.0000
* y = sin(0.5)
* y
    0.4794
* y+2
    2.4794
*

You can use UniScript as a powerful calculator. However, UniScript is also a matrix based system for scientific and engineering calculations, as the next example will illustrate.

2.1. Matrix algebra

We want to solve this linear system

\begin{pmatrix}
   4 & 7 \\
   2 & 5
 \end{pmatrix}
 \cdot
 \begin{pmatrix}
   x_{1} \\
   x_{2}
 \end{pmatrix}
 =
 \begin{pmatrix}
   1 \\
   4
 \end{pmatrix}

Type:

* a = [4,7;2,5]
* a
    4.0000   7.0000
    2.0000   5.0000
* b = [1;4]
* b
    1.0000
    4.0000
* x = a\b
* x
   -3.8333
    2.3333
* a * x
    1.0000
    4.0000

The arguments of a matrix must be enclosed in square brackets. Columns are separated by a comma and rows are separated by a semicolon. The expression line x = a\b solves the linear system. UniScript uses the powerful LAPACK-Library to solve the equation so that even large linear systems can be solved quickly and stability.

UniScript has other matrix functions that compute the determinants, inverse or eigenvalues.

* det(a)
    6.0000
* a^-1
    0.8333  -1.1667
   -0.3333   0.6667
* eig(a)
    8.2749 + 0.0000i
    0.7251 + 0.0000i

Eigenvalues will be computed as complex numbers. UniScript uses i to represent the imaginary part of a complex number.

* (3 + 5i) * (2 + 7i)
  -29.0000 + 31.0000i

Almost all math functions in UniScript can be used with complex numbers. Try sqrt(-1) as an example.

2.2. Command Line editing

  • You can recall a previous command to edit or correct errors. To recall the command use the up or down arrow keys (command history).
  • The F7 key opens the command history dialog box.
  • The F8 key recalls all the command lines which start with the same characters before the cursor.
  • The ESC key clears the command line. The ESC key can also be used to interrupt a running function.
  • The INSERT key switches from insert to the overtype mode and vice versa.
  • The BACKSPACE key deletes the character before the insertion point.
  • The DELETE key deletes the characters after the insertion point.

The command window is mainly used to test a command or to view the values of variables. In all other cases, you should use an editor.

2.3. Using an Editor

You can create an editor by typing the command EdCreate(). To arrange the command window and the editor window choose Window=>Tile Vertical .

Type the following lines into the editor

a = [4, 7; 2, 5]
b = [1; 4]
print "The determinant of", a
print "is", det(a)
print "The solution of the equation"
print "a*x = b, with a = ", a
print "and b = ", b, "is", a\b

Save the new file under a name with the extension .ic (e.g. test.ic) and then choose UniScript=>Save/Execute. UniScript will execute the commands you typed into the editor. The output of the print commands will be displayed in the command window.

To get help for a function, position the cursor on the function name and press the F1 key. If you place the cursor on the function det, you will get the following help page:

../../_images/Help_det-en.png

2.4. Temperature table - 1. Version

In the next example, we want to write a program that prints out a temperature table. In the first column, we want the temperature to appear in degrees Fahrenheit. In the second column, we want the temperature shown in Celsius. To convert the Fahrenheit temperature into Celsius, we use the equation C = 5 / 9 * (F - 32).

0       -17.8
20       -6.7
40        4.4
...       ...
260     126.7
280     137.8
300     148.9

First, delete the contents of the editor. Choose Edit=>Select All and then press the Delete key.

This example is taken from a book about the programming language C (Kernighan, Brian W., und Ritchie, Dennis M.: Programming in C, Hanser, München, 1983). Besides highlighting the similarity of UniScript and C, this example will show you some important aspects of programming which are as valid for UniScript as for C.

The program that will print the temperature table looks like the following:

/* Converts Fahrenheit to Celsius
    for f = 0, 20, ..., 300 */
def main()
{
    lower = 0;   /* lower boundary of the Temp. Table */
    upper = 300; /* upper boundary */
    step = 20;   /* step size */

    fahr = lower;
    while (fahr <= upper) {
        celsius = (5.0 / 9.0) * (fahr - 32.0);
        printf("%4.0f %6.1f\n", fahr, celsius);
        fahr = fahr + step;
    }
}

The first two lines are comments

/* Converts Fahrenheit to Celsius
for f = 0, 20, ..., 300 */

All characters between the comment characters /* and */ will be ignored by UniScript.

With

def main()
{
    ...
}

a program (a function) will be defined. The keyword def does not exist in C. In UniScript, a function always starts with the keyword def. In C, the function name main indicates that this is the main function. In UniScript, main has no special meaning and is a valid name like any other name.

The function name, main, is followed by parentheses () which usually contain a parameter list. In our example, this list is empty. The parentheses are still necessary to indicate to UniScript (and the programmer) that main is a function name. Braces { and } designate the beginning and the end of the function main. They have the same meaning as begin and end as in other programming languages.

A declaration of the variables follows the open brace { in C. In UniScript you do not have to declare variables.

The first statement is

lower = 0;

In this statement, the variable lower is assigned the value 0 as a double precision real number. In the C program, lower was declared as an integer. UniScript does not know integer data types. UniScript knows only three data types:

  • Double-precision floating point values.
  • Complex numbers as a pair of double-precision floating point values.
  • Strings (sequence of characters).

You can create vectors and matrices for all three data types, as shown later in this manual.

The lines

upper = 0;
step = 20;

fahr = lower;

assign start values for the other variables. It follows a so called while statement:

while (fahr <= upper) {
    ...
    fahr = fahr + step;
}

The while statement tests the expression in parentheses. In our example, it is the expression fahr <= upper. If the expression is true, it executes the statements enclosed within the braces. After the statement body has been executed, the expression is tested again, and if it is still true, the statements are executed once more. This process is repeated until the expression is no longer true. If the expression is initially false, the statement body of the loop is never executed.

The statement fahr = fahr + step increments fahr by step (by 20 in our example).

Note: When formatting functions, you could write all function statements justified to the left margin but the program is easier to read if the statements are indented one tab position. Statements inside of loops or if statements should be indented one more tab position. You can define tab sizes in the Editor. We recommend a tab size of 4 blank spaces.

Inside the braces are two other statements

celsius = (5.0 / 9.0) * (fahr - 32.0);
printf("%4.0f %6.1f\n", fahr, celsius);

The first statement converts Fahrenheit to Celsius and the second statement prints the values for fahr and celsius into the UniScript command window. The f character at the end of the function printf stands for formatted.

In our example, printf has three arguments. The first argument is the format string "%4.0f %6.1f\n". This string determines how printf should print the arguments fahr and celsius. For this purpose, the format string contains the elements %4.0f and %6.1f. A format element starts with the % character. %4.0f means that the parameter fahr will be printed with 4 digits and no decimal places. The f means that the value will be printed as a float number. The format element %6.1f will print the celsius values with 6 digits. One of the digits will be a decimal place. Characters outside the format elements will be printed directly like the blank character between the format elements in our example. The two characters, \n, cause the next character to be printed into the new line.

The main function uses 5 variables: lower, upper, step, fahr and celsius. These variables were created when the function was called up and they will be destroyed just before the function finishes.

You should type the program into an editor now. Save the file under celsius.ic. After you save the file, choose the UniScript=>Save/Execute.

You can execute the function by typing the name into the UniScript command window:

* main()

Take the time to experiment with this function. For example, change the format string of the printf function. After you have changed something, choose the Save/Execute command and execute the function from the command line.

2.5. Temperature table - 2. Version

In the next example, we want to write a new function which will have the same output as main() but uses the for statement instead of the while statement. We call the function main2(). You can type the function in the same file as main(). In UniScript, a file can contain more than one function.

/* Converts Fahrenheit to Celsius
for f = 0, 20, ..., 300
- 2. version - */
def main2()
{
    for (fahr in 0:20:300) {
        printf("%4d %6.1f\n", fahr, 5/9 * (fahr-32));
    }
}

The for statement has the following syntax:

for (var in vector) {
    ...
}

for and in are keywords. var can be any valid variable name. vector stands for the name of a vector or a constant vector. Vectors in UniScript can be created in different ways. One possibility is to separate the elements by a comma and enclose them in square brackets:

vector = [0,20,40,60,80]

You can also generate a vector with an ":" operator in the following manner:

vector = start:step:end

step can be omitted (vector = start:end). In this case step is 1.0. The expression 0:2:10 will generate a vector with the elements [0, 2, 4, 6, 8, 10].

The for statement

for (fahr in 0:20:300) {
    printf("%4d %6.1f\n", fahr, (5/9)*(fahr-32.0));
}

first creates the vector, 0:20:300, and executes the statement body for each element of the vector. fahr will be 0, 20, 40 to 300.

Counting the number of iterations is very common in loops. If you know how often you want to execute the statements of a loop, the for statement is both less work to type and more natural to think of. Therefore, main2() is a better solution than main().

2.6. Temperature table - 3. Version

But UniScript provides a more simple way to solve our temperature problem. In the following example, we can do without a loop statement:

def main3()
{
    fahr = (0:20:300)';
    printf("%4.0f %6.1f\n", fahr, (5/9)*(fahr-32));
}

In main() and main2() we passed the scalar values 0, 20, 40 etc. to the printf function. In main3(), we generate a column vector with the statement

fahr = (0:20:300)';

The transpose operator (') transposes the row vector to a column vector. Because the fahr variable is a column vector, the expression, (5/9)*(fahr-32), will create a column vector with as many elements as the fahr variable. The printf function will execute the "%4.0f %6.1f\n" format string as often as the vector has elements. printf has a built in for loop.

UniScript has many functions with built in for loops. The statement

y = sin(0:2*PI/100:2*PI)

will generate the y vector with 100 elements. This enables you to write very compact programs with UniScript.

2.7. Temperature table - 4. Version

Now we want to print the temperature table as a single line statement. You can type the line directly into the UniScript command window or into an editor.

For each UniScript=>Save/Execute command, the statement will be executed and the table will be displayed in the command window:

printf("%4d %6.1f\n", fahr = (0:20:300)', 5/9*(fahr-32));

The statement above demonstrates another example of UniScript’s ability to write compact programs. As in C, the assignment operator can be used inside the statement.

As well as the printf function, UniScript provides another simpler output function. The print statement does not need a format string or parentheses because it is not a function.

The statement

print [fahr = (0:20:300)', 5/9*(fahr-32)];

first generates a matrix with two columns from the two vectors and then prints it out in standard format.

If the statement would be typed without the square brackets,

print fahr = (0:20:300)', 5/9*(fahr-32)

then print would print one vector after the other.

The disadvantage of the print statement is that you do not have full control over the output. Secondly, the print statement cannot write directly into a file, but this is possible with a special version of the printf function, namely fprintf.

2.8. Plot the Temperature Table

As a last example, we will create a plot of the Fahrenheit/Celsius data with the plot function.

h = plot(fahr = 0:20:300, 5/9 * (fahr - 32))

The plot function itself is programmed in UniScript. The function draws the x- and y-axis and displays data as a line plot. In the following screen you can see the result of the plot function call.

../../_images/UniScriptFahrenheitCelsius.png

The plot on your monitor might not look exactly like this; the plot function uses the standard settings (see Tools=>Options).

The plot function has created a new window, drawn a diagram with one x- and one y-axis into the window and plotted the x- and y-coordinates as a line graph.

We will use the terms document, page, layer and dataset to describe the elements of a plot. A window represents a page from a document. A document contains one or more pages. A page contains one or more layers and each layer can hold one or more datasets and drawing objects (text objects, rectangles, lines, arrows etc). A dataset contains the coordinates of the data points as well as information as to how the data should be displayed inside of the coordinate system.

UniPlot is programmed in the object oriented programming language C++. Documents, pages, layers and datasets are the objects created and manipulated by UniPlot/UniScript. UniScript itself is not an object oriented programming language. UniScript uses handles to access the objects. A handle is a number that is associated with the object. The handle is valid as long as the object exists.

The statement

h = plot(fahr = 0:20:300, 5/9 * (fahr - 32))

returns a vector of handles.

  • h[1] is the handle of the page,
  • h[2] is the handle of the layer and
  • h[3] is the handle of the dataset.

Choose Window=>Tile Vertical to arrange the command and plot windows on the monitor.

Type the following into the command window:

PagePrint(h[1])

This command will send the document to your standard printer. All functions that work with plot documents have the prefix Doc. To receive a list of all function names beginning with Doc, type what("Doc*").

* what ("Doc*")
DocAddPage
DocCanPaste
DocCopyPage
DocCreate
DocDataZoom
...
DocSetProtectionFlags
DocSetReadOnly
DocSetSummaryInfo
DocSetTitle
DocShow
   54 function(s) defined

The what() function lists the names of all loaded functions. Try what(), what("Page*"), what("Layer*") and what("XY*").

Look for the description of the what function in the help system. To receive help for a certain function, type the function name inside the command window, move the cursor one character to the left and press the F1 key. To clear the command line, press the ESC key.

To finish the plot, we need to change the axis titles:

LayerSetAxisTitle(h[2], "X", "Celsius")
LayerSetAxisTitle(h[2], "Y", "Fahrenheit")
PageReplot(h[1])

Normally, you would make these changes interactively with UniPlot. But if you want to write a program that, for example, reads the axis title from a file, you need functions to access the different elements of the plot an UniScript easily enables you to do this.

id-1087286