Scilab: Functions and Plotting

Functions

Functions are the basic building blocks of any non-trivial program. Scilab has hundreds of built-in functions, but it also allows you to define your own. Here's how:

Create a source code file, with a name of the form mysinc.sci. It's handy to end the name with .sci. The name of the file must be the same as the name of the function; so, in this example, the function must be called mysinc. An example of a Scilab function, mysinc.sci
Inside the file, write the function.
- The first line must look like this:
```
      function result = thisfunc(arg1, arg2)
```
  where
  - the word function indicates that this is a function
  - the word result will hold the result of the computations; it will be returned as the result of calling the function
  - the name of the function, thisfunc, appears after an equals sign
  - if there are any arguments to the function, they appear within parantheses after the function name
  Functions should always return values. Sometimes the value is the result of a computation, sometimes it is a string like 'yes' or 'no'. If nothing else, some functions can be defined to return
  - 0 to indicate that all is well
  - 1 to indicate that a problem occurred
- Immediately after the function declarations should be a set of comments which describe the function and all its arguments, like this:
```
function y = mysinc(x)
//
// this function calculates the "sinc" of its argument,
// defined as
//                     sin(x)
//         sinc(x)  = ---------
//                       x
//                       
//
// Input arguments:      
//         x           a floating-point value; we treat it has
//                          having units of radians when taking sine
//                          
// we check to make sure that the argument is not zero before
// we perform the calculation; if it is, then we return 1, which
// is the proper limit as the argument approaches 0


 
```
  When a user types the command head_comments mysinc, all the comment lines immediately following the function definition are printed to the screen.
- After the "header" comments comes the function's source code itself. If the function returns a single value (as the mysinc example does), make sure that you assign the proper value to the return argument at the end of the function.
- The final line of a function must be endfunction

Input and output arguments

Functions can have any mix of input and output arguments. Input arguments should not be changed in the course of the function! Output arguments should not be referenced in the function until they have been set!

Many common, simple functions have a single input and a single output argument. For example, one could write Scilab definitions of some common mathematical functions like so:

      square root:         function y = square_root(x)
      cosine:              function y = cosine(x)

Some functions have no input arguments; for example, a random number generator which simply returns a random value between 0 and 1 might be defined like this:

      random number:       function y = rand

Scilab's built-in rand function works this way (actually, one can call it with arguments, but only for fairly arcane purposes).

Some functions have two or more input arguments. Suppose you want to write a function which performs the same job as a for loop: beginning at some starting value, count by some increment until reaching an ending value. You function definition might look something like this:

      count over a range:  function counter(startval, increment, endval)

It's also possible for a function to have more than one output argument. One very common mathematical task is to convert from rectangular [x,y] coordinates to polar [r, theta], and vice versa. Either conversion requires two input values, and two output values. For example, the definition of one such function might look like this:

    rectangular to polar:  function[r, theta] = rect_to_polar(x, y)

The output arguments appear immediately after the keyword function, enclosed in square brackets. Note that the input arguments are enclosed in parantheses.

You may download the 'rect_to_polar' function, examine it, and try it out. Note the checks to figure out in which quadrant the vector lies. We need to do this because the Scilab functions all deal with angles in the range (-pi to +pi), whereas we want to yield angles in the range (0 to +2pi).

Making simple plots

Scilab contains many powerful tools for creating complicated graphs and images. We will need only the simplest of these tools. You can find a more detailed discussion with pictures elsewhere.

To create a 2-D x/y plot,

create a vector of X values
create a vector of Y values (which must have the same number of elements)
type plot (x, y)

For example, try these commands:

      x = 0 : 0.1 : 30;
      y = sin(x);
      plot(x, y);

If you call plot a second time, it will sit on top of the first plot:

      y = sqrt(x);
      plot(x, y);

If you want to erase the old plot and start from scratch, and add to it the new one on the same set of axes, use the clf command before making the second plot:

      clf;
      y = sin(x);
      plot(x, y);

There's another way to do it, too: you can supply more than a single pair of (x, y) values to the plot function:

      x = 1 : 0.1: 30;
      y1 = sin(x);
      y2 = cos(x);
      y3 = sqrt(x);
      plot(x, y1, x, y2, x, y3);

The Graphics chapter of the Scilab documentation contains many, many more examples of the software's graphing capabilities.