4.1 Program

It was previously mentioned that numEclipse could be used in both interactive and programming mode. We saw a number of examples of how the interpreter could be used interactively. We also looked at an example of m-script program in chapter 1. Unlike other programming languages, an m-script program does not have strict structure. It does not have “begin” or “end” statements or curly brackets to show the start and end of the program. The program is stored in a text file with “.m” extension, i.e., m-file. It contains a sequence of statements which you could also execute individually from the command prompt. In that sense, it is very much like a batch file. It also makes the program much simpler. A programmer will normally try different commands interactively. Once, he is sure about the sequence of commands to achieve the objectives, he could copy the commands from the “history view” to an m-file within the Source folder of the project. The program could be executed from the command prompt using the “run” command. A script program runs in the same workspace as the interpreter. It means that all the existing variables in the memory will be available to the program. Similarly, all the variables created during the execution of the program will be available in workspace memory even after the completion of program execution. This could also cause potential conflicts among variables with the same name. To avoid such a situation, we could use the “clear” command in the beginning of the program. This command removes all variables from the workspace memory. In the following, we present a simple program which generates Fibonacci numbers based on user input. Fibonacci numbers are generated based on a recurrence relation as defined in the following.

(4.1)

In the above program, line 1 asks the user to provide the number of Fibonacci numbers to generate. Line 2, converts the user input from string to a number. Lines 3 and 4, initialize the first two values of Fibonacci numbers as defined in the recursive formula given above. Lines 6–8, use a “for” loop to generate the numbers. The last line, 9, displays the values of vector “fib”. Note the question mark in the last line; it is used to display the value of the variable. In the interactive mode, you do not need to use a question mark to display the value but in a program it is required.

The program becomes immediately available for use in any interpreter in the project. The above code shows how to invoke the program. All the programs must be saved in the “Source” folder within the project. Unlike MATLAB, these programs cannot be compiled into MEX files. Although the compiled program could speed up the execution of a program, it does not make sense to compile code for an interpreter. If you really need performance then you should consider writing the program in Java or C as described later in the chapter.

4.2 Function

The ability to create user-defined functions is available in all programming languages including m-script. Most of the programming in numEclipse involves writing functions. A “toolbox” is a collection of functions in a particular subject area. For example, an image processing toolbox will contain functions related with image processing. A lot of built-in toolbox functions within numEclipse are also implemented using m-script.

In general, a function takes zero or more arguments as input and returns one output value. Here you can go beyond this and define functions which could take a variable number of arguments and return a variable number of output values. In the following, we will show the specification and example of each possible case. Here is a simple specification of a function.

In a simple case, a function takes a fixed number of input arguments and returns a single output value. The following example presents a simple function.

You would notice that unlike other programming languages there is no need to use a “return” statement. The output variable is directly assigned the value in the function body. The “return” statement is available but it is used differently from other programming languages. It is used to stop the execution of the function or procedure. The program execution is returned to the calling program, when a “return” statement is encountered in a program. Each function call creates a separate workspace memory for the function. The actual input arguments are copied to this workspace. It means that a pass-by-value approach is used instead of pass-by- reference. The advantage is that the function could alter the input parameters within the function but it will not affect the parameter values in the calling program or function. Say, for some reason you want to make a variable available to the interpreter’s memory space, it is possible by declaring the variable as global variable within the function. For example,

global planck_constant;

planck_constant = 6.626e-34;

Like a program, a function is also created in the m-file. The file name must be same as the function name for the sake of traceability. The interpreter uses the file name as the function name. In MATLAB or Octave, you could define multiple functions or procedures in the same file; numEclipse does not allow this for the sake of simplicity. Like a program, the function file must reside under the “Source” folder, within any nested folder if required. It also becomes immediately available for use in any interpreter within the same project. Here is an example to test the function.

In the above test example, note that the same function works for both a real number and complex number argument. It will even work for a matrix, as mentioned before, every number in numEclipse is treated as a matrix.

The second syntax definition in the following shows that a function can return more than one value in an array.

The following code shows the example of a function with multiple returned values. Note that there is no “end” or “endfunction” to close the function. Unlike statements, use of “end” is optional in functions and procedures.

The comment on the second line of the function definition is used as a help document in MATLAB and Octave. numEclipse has not implemented a help system yet. But for the sake of documentation, it is a good idea to put some comments describing the function.

The following listing shows how to call these functions.

Most mathematical functions have zero or more input arguments and a single output argument. A user of these functions will always pass the fixed number of arguments and expect single output. Here is another example,

This function accepts two input arguments, x and y, and it returns the minimum of these two arguments. The “end” keyword in above function is the end of the “if' statement rather than the function. In fact, the “end” keyword for the function is optional. You can also use “endfunction” like in octave script. One most important point, there is no mention of input arguments’ data type. This is really wonderful, this function will work for real numbers, complex numbers, row/column vectors and matrices. The relational operator “<=” automatically overload based on the type of operands.

In the following we show some examples of the function call.

“min” function as described above does not put any constraints on the type of the input arguments. This might be a problem in certain situations for example when somebody tries to find a minimum of a string and a matrix. In that case, you will use the “error” function as shown below.

In this modified definition, we call an error function when the type of input arguments does not match. The “error” function returns the control back to the caller program along with its string argument. Another function, “warning”, could also be used in the situation where you want to send a string message back to the caller program without returning the control, so the function will keep executing.

The above function restricts the number of input arguments to two. Say, we want to modify it in such a way that it could accept any number of inputs and return the minimum of those input arguments. This is how we will do it.

When the above function is called as shown above, all the input arguments are packed into a cell array “varargin” and an automatic variable “nargin” is created with value 5 which reflects the number of inputs. The i^th argument could be accessed using the curly bracket, vararginf{i}.

Now, we want to modify this function to return more than one value. Say, we want it to return both the minimum and maximum values.

This function could be called as shown below.

If we call the same function slightly differently, as follows.

We will get an array index out of range error. This situation could be avoided by using the “nargout” as shown below.

The “nargout” contains the number of output variables requested by the caller program. Checking this variable enables the function to printout a meaningful error message. Let’s give another twist to this function.

And here is the call to this function.

In this function, the first input argument is a string which determines if the function should return the minimum or maximum of the rest of the input arguments. This example is presented to show that “varargin” could be used with other input arguments. Similarly, “varargout” could be used with other output arguments. But, we should always use these at the end of the list of the arguments, for obvious reason. Another important point to remember is that in this situation “nargin” and “nargout” will return the total number of input and output arguments and it will not be the same as the length of these cell arrays. So if you want to loop around these arrays then it is better to use the “length” function on these cell arrays rather than the automatic variables, “nargin” and “nargout”.

A function could also be referenced using a function handle. This allows us to call the original function indirectly through its handle. The function handle is created using the “@” symbol in front of the function name.

 < function handle > = @<function name >

e.g. f = @sin

The advantage of this feature is that we can create a function of function by passing a function handle to another function. In the following function, we calculate the first difference values for the given input function.

In the following, we demonstrate how two different functions are passed as input arguments to the above function. This feature enables us to write generalized mathematical functions which will work with any input function, for example, functions to integrate, differentiate, or function to solve differential equations.

Once all the user defined functions are developed and tested, you might want to deploy them as a toolbox for other users. As mentioned earlier, numEclipse does not support compilation of m-script functions to MEX files. But, it does have a neat mechanism of deployment. The deployment package is just a zip file containing the user-defined functions. So you compress the m-files containing the functions in a zip file and deliver to the end-users.

The end-user should take the following steps to include these functions into the interpreter.

To be on the safe side it is always recommended to re-start, if you are not sure. This completes the deployment. You are ready to try it now. Now we deleted the “extreme.m” file from the workspace and deployed the zip file. Then we tried the function again and the result is same as before.

Say, you had two definitions of the same function. One in the workspace and other one deployed as a library. The interpreter will pick the definition from the workspace since it has higher precedence.

4.3 Procedure

A procedure is same as a function except it does not return any value. The syntax definition for a procedure is shown below.

Here is an example of a procedure.

In the following, we show how to call a procedure.

And it results in the following plot.

Similar to a function, we could also create a procedure with variable number of input arguments. We also have the automatic “nargin” and “varargin” available within a procedure. The only difference from a function is that we cannot return a variable. Although it is not good programming practice, we can still make a procedure communicate with another procedure using the global variables. A procedure also starts with the keyword “function” and it is also written in an m-file. The packaging and deployment process also remains the same.

4.4 Java Programming

It is assumed that the reader is familiar with the java development using eclipse. To develop java functions in numEclipse, you would also need to understand some internals of this application. Before we go into those details, let us start with a simple example to demonstrate the development process.

Select eclipse menu File → New Project, it will bring up “New Project” wizard. Select “Java Project” and click on “Next” button. Type the name of project on the “New Java Project” dialog box and click on “Finish” button to create the new java project. You would need to follow similar steps to create the package “test” and a java class “MyJavaClass” within the package. In the following figure, we show a java project “MyJavaProject” containing a class “MyJavaClass” and a static method “addOne”. Note that, in the “Referenced Libraries” of project “MyJavaProject” you need to add the “library.jar” file. It is available within the numEclipse plug-in. You will not be able to compile the class without this library in the classpath. Once the class is successfully compiled, you can immediately start to use it in the interpreter. Right-click in the numEclipse project “MyFirstProject” and select “Properties” from the pop-up menu. Select “Project References” on the “Properties” dialog box and select “MyJavaProject”. This establishes the link between the two projects. Now, switch back to any interpreter and try out the function “addOne” as shown in the following.

Let us look at the function “addOne”, it is basically a static function. It takes an argument of type “IMatrix”. The function body contains only one line, which calls a method “plus” on the input object with the value “1.0” and returns the result of type “IMatrix”. “IMatrix” is an interface for the “Matrix” data type discussed in chapter 2. Each data type in numEclipse has a corresponding java interface, e.g., IComplex, IStruct, ICell. These interfaces are defined on the numEclipse project website (http://www.numeclipse.org/interface.html). It is important to know the methods available in each interface but there is no need to understand the actual implementation. numEclipse provides a default implementation of these data types and the pluggable architecture allows replacement of this implementation. It will be discussed later in detail in another chapter. numEclipse also provides the interface class “LinearAlgebra”. The implementation of this class provides methods to create variables of different data types. The numEclipse interpreter keeps all the variables in a look up table called “Symbol Table”. Each variable in the table is wrapped in another object called “Symbol”. This “Symbol” class provides methods to set and get the variables. In the case of an exception, a java function should throw “SemanticException”. Since it is a “RuntimeException” there is no need to use “try … catch” block. The interpreter will catch the exception and it will show the error message on the command line.

In the last example, we defined the function to accept a matrix argument and return a matrix. But when we called the function, we passed double, complex and matrix numbers and it worked for all of these data types. It is important to remember that a double or a complex variable is treated as matrix of dimension 1 × 1. So you only need to define one function for all three types. In case, you want your function to work with any other types then you should provide the overloaded definition of the function for each of those types.

The “MyJavaClass” needs some changes before it could be deployed. The modified class is shown in the following.

Note that, we added a static variable “alg” of type “Linear Algebra”. We also added a static method to set the value of this variable. These additions facilitate the pluggable implementation of linear algebra functions. The interpreter could change the implementation on the fly. The class now implements an interface “Toolbox”. Any java class that we want to deploy must implement this interface. In fact, there is not much to implement because the “Toolbox” interface is empty. The “function library manager” within the interpreter uses a common mechanism of java reflection to load all the functions whether they are built-in or deployed. When a class is implementing the “Toolbox” interface, the interpreter could identify the deployed functions.

Deployment of java functions is very similar to the deployment of m-script. Here, we export the java functions to ajar file using the eclipse File → Export menu. Then add the jar file to the numEclipse library using the preferences as we did in the previous section. Make sure that the numEclipse project does not depend on the java project in the workspace. Let the workbench restart and test the functions from the interpreter. In case of duplication, function definition in the workspace takes precedence over the deployed function.

Let us look at some more examples.

This function returns the minimum of two input arguments. In lines 2, we compare the input matrix arguments. The result of the comparison is a matrix of zeros and ones. “One” when the corresponding element is less than the element in m2 and “zero” otherwise. In line 3, we check if all elements of the resultant matrix are greater than zero and return the result accordingly. Note that we return a new instance of the input variable rather than the actual variable. This ensures that the original variables are not modified in the symbol table. This function is very similar to the function developed using m-script in the previous chapter. Let’s see how the function call works here.

Interestingly, the function works for both double and matrix input arguments. We can use any combination of double, complex and matrix input pair and it will still work. So there is no difference in the way it works regardless of the implementation language. In the following we show how to raise an error or exception.

In this modified function, we compare the size of input matrices and throw “SemanticException” in case of a mismatch. Here is an example to call this function,

Note that the error message shown on the command line is same as the string argument passed to the “SemanticException” in the function. It is always a good idea to use a meaningful message. Now, we will modify this function in such a way that it will accept a variable number of input arguments. Here is a code listing,

In this example, we used a List instead of IMatrix. Basically, when we call this function from the interpreter or any other function or program, the interpreter packs all the input arguments in a list. We extract the contents of the list to compute the result. Note that, we do not return an object passed to the function. We always create a new object out of the resultant matrix object. This ensures the integrity of the variables in the workspace.

We will change this function further to return multiple output parameters. Here is the code listing,

This method could take variable number of arguments and it could return more than one output parameters. The input and output parameters are packed into lists by the interpreter as mentioned in the previous example. Here is an example to call this method.

The result is same as we saw in the last chapter. Essentially, you could achieve the same functionality either you write the function in m-script or java. Of course, the java functions will be faster than the m-script.

4.5 C Programming

This section is intended to show you how to write C functions for numEclipse. It is more difficult of the last two approaches but luckily eclipse comes with some tools which make the development a rather smooth process. You would still need a good understanding of C and Java Native Interface (JNI). The intent here is not to teach you C or JNI but rather the development and deployment process. It is assumed that the user is familiar with C and JNI development under eclipse.

The very first step is to write a java class similar to the one developed in the previous section. Except the fact, that we are using native method over here. Here is an example,

Similar to the previous section, this class implements the interface “Toolbox”, declares an attribute “alg” of type “LinearAlgebra” and defines a setter method for this variable. Here we declare two native functions on lines 5 and 6. numEclipse cannot make a direct call to native functions so we define wrapper functions in the class with the names starting with keyword “native”. This naming convention is used by the interpreter to determine the nature of the function. The notion of wrapper function is developed with the view that some conversion will be required for the arguments before and after calling a native method. We previously mentioned that a double or complex argument in a function call is converted to a matrix. In this case, when you name the function starting with native, it will not perform this conversion to matrix. This design decision is made with the view that a lot of time a developer will be more interested in integrating existing C libraries rather than writing new ones. In that case, it makes more sense to keep the function arguments as it is, because existing libraries are unlikely to be using the matrix object defined in numEclipse.

As a next step, we generate the C header file “NativeToolbox.h” using “javah” utility on the last java class. Here is the generated code.

The C header file is not supposed to be modified as it says in the comments within the file. Next, we write a “.def” file as follows.

It basically lists the name of the functions exposed for export. Then, we write the C program “NativeToolbox.c” implementing the C functions in the header file.

Finally, we write the following makefile to generate the “dll” file.

Now, the code is ready to be deployed. We will follow similar steps to those used in the previous section. We will export the java class to a “jar” file and add the “jar” and “dll” files both to the library preference of numEclipse. You are now ready to test the native functions, as follows.

So this completes the chapter. Here we learnt how to develop and deploy a library of functions in java and C.