



























                                    MATCOM LIBRARY

                      A Matlab(R) compatible C++ matrix library

                                  March 1996 release


                                          2



           TABLE OF CONTENTS




           TABLE OF CONTENTS ............................................2


           Legal stuff - MUST READ ......................................4

           Copyright ....................................................4
           Disclaimer ...................................................4
           Trademarks ...................................................4

           What is the MATCOM LIBRARY? ..................................5

           Introduction .................................................5
           Features .....................................................5

           Requirements .................................................6

           Platform and OS, C++ compiler ................................6
           Gnuplot ......................................................6
           Image viewer .................................................6
           Sound player .................................................6

           Installation .................................................8

           PC Release ...................................................8
           Unix Release .................................................8
           Installation troubleshooting ................................12
           Runtime troubleshooting .....................................13
           Compiling MATCOM LIBRARY for other systems ..................14

           Limitations .................................................16

           Matrix size .................................................16
           Graphics ....................................................16
           Debugging ...................................................16
           Sparse ......................................................16

           Compatibility ...............................................17

           Matlab ......................................................17
           Octave ......................................................20

           Runtime error messages ......................................21

           Matrix names ................................................21

           Other .......................................................22

           Where is ... ................................................22
           Bug reports .................................................22
           How to reach me .............................................22

           The MATCOM LIBRARY Reference ................................23


                                          3

           Introduction ................................................23
           Features of MATCOM LIBRARY ..................................23
           matlib.h header file ........................................23
           The M matrix class ..........................................24
           Constructors ................................................24
           Class functions .............................................24
           The Mr matrix index class ...................................25
           Memory Allocation/Deallocation ..............................26
           Calling functions conventions ...............................26
           initialization - initM(matlibin,matlibout,matliberr) ........26
           termination - exitM() .......................................26
           Input/Output streams ........................................26
           Function reference ..........................................27
           Examples ....................................................53
           Compiler switches ...........................................54


                                          4

           Legal stuff - MUST READ


           Copyright

           This software is copyrighted work by Yaron Keren. It is a
           copyrighted freeware, no payment needed for the use of this
           software. MATCOM LIBRARY may be distributed for a nominal
           distribution fee and may be included in a CD-ROM collection.
           MATCOM LIBRARY may not be re-selled or included with other
           products except:

           APPLICATIONS, EXECUTABLES LINKED WITH MATCOM LIBRARY MAY BE
           USED FOR ANY PURPOSE WITHOUT CHARGE.

           Disclaimer

           THERE IS NO WARRANTY FOR THE PROGRAM. THE ENTIRE RISK AS TO THE
           QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
           PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
           SERVICING, REPAIR OR CORRECTION.
           THE SOFTWARE IS PROVIDED ``AS-IS'' AND WITHOUT WARRANTY OF ANY
           KIND, EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT
           LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A
           PARTICULAR PURPOSE.
           IN NO EVENT SHALL THE COPYRIGHT HOLDER OR ANY OTHER PARTY WHO
           MODIFY AND/OR REDISTRIBUTE THIS PROGRAM  BE LIABLE FOR DAMAGES
           INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, INDIRECT OR
           CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO
           USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR
           DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR
           THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
           OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
           ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

           Trademarks

           Borland C++ is a trademark of Borland International.
           Matlab(R) is a trademark of The MathWorks, Inc.
           MS-DOS, MS-WINDOWS and Visual C++  are trademarks of Microsoft
           Corporation.
           SunOS is a trademark of Sun.

           Trademarks of companies mentioned in this documentation appear
           for identification purposes only and are the property of their
           respective companies.




           BY USING MATCOM LIBRARY YOU AGREE TO ALL OF THE ABOVE.


                                          5

           What is the MATCOM LIBRARY?


           Introduction

           The Matlab(R) family of products provides a great environment
           for numerical computation. However, it lacks in speed,
           integration with other languages and development tools. In
           addition, one can not distribute a working prototype.

           MATCOM LIBRARY is a C++ matrix class based closely on the
           Matlab language.

           Features

           o Highly compatible with the Matlab 4 language dialect.
           o All code and binaries produced are free for any purpose.


                                          6

           Requirements


           Platform and OS, C++ compiler

           The following are supported (Platform/OS/Compiler):

           PC/DOS/DJGPP
           PC/DOS/DJGPP 2
           PC/Windows/Visual C++ 1.X
           PC/Win32/Visual C++ 2.X
           PC/Windows/WATCOM C++32 9.5,10.X
           PC/Windows/Borland C++ 3.1,4.X
           PC/Win32/Borland C++ 4.X
           PC/Linux/gcc
           PC/Solaris-x86/CC
           Sparc/SunOS/gcc
           Sparc/Solaris/gcc
           SGI/Irix5/gcc
           SGI/Irix5/CC
           SGI/Irix6/gcc
           SGI/Irix6/CC
           DECstation/Ultrix/gcc
           Alpha/OSF1/gcc
           Alpha/OSF1/DECCXX
           HP9000/HPUX/gcc
           IBM SP2/AIX/xlC
           RS6000/AIX/xlC

           o Windows 95 and Windows NT are also supported on the PC.
           o Other compilers and/or Unix OS are very likely to work.
           o BLAS/DXML libraries are supported.

           Gnuplot

           2D and 3D graphics are displayed using the Gnuplot plotting
           program. Gnuplot is available for all platforms supported by
           MATCOM, not included in the MATCOM distribution. Gnuplot must
           be correctly installed and on the path.

           Image viewer

           In order to use the image command, a BMP viewer is needed. The
           default viewer is Windows PaintBrush. On Unix systems, the xv
           viewer may be used.

           Sound player

           In order to use the sound command, a WAV player is needed. The
           default viewer is the matwave program (supplied).


                                          7

           Installation


           PC Release

           1. Create a directory where you want MATCOM LIBRARY installed.

           2.  Unzip matcom.zip in the directory selected.

           3. If you are using Visual C++ 2.X, DJGPP or WATCOM C++
           compilers you need to compile the library:

           For Visual C++ 2.X run:

           vc2.bat

           For DJGPP run:

           djgpp.bat

           For WATCOM C++ run:

           watcom.bat

           A library will be created in the current directory.

           4. To use an image viewer, other than the default Windows
           Paintbrush, set the matcomviewer enviroment variable to the
           program name.
           Example:

           set matcomviewer=c:\graphics\wingif.exe

           5. To use a sound player, other than the default Windows
           matwave, set the matcomplayer enviroment variable to the
           program name.
           Example:

           set matcomplayer=c:\sound\plany.exe

           The supplied matwave.exe will not work under DJGPP.

           Unix Release

           MATCOM LIBRARY is supplied in source form which must be
           compiled.

           Compiling MATCOM

           1. Create a directory where you want MATCOM installed.

           2. Uncompress the sources:

           uncompress matsrc.tar.Z

           3. Untar the sources:

           tar -xf matsrc.tar

           You should now see directory structure:


                                          8


           +-matcom
           +-matlib
           +-matdisk

           The source files are in the matlib directoriy. The library will
           be created in the matdisk directory.

           4. If gcc is used, find out the gcc version by running:

           gcc -v

           5. Find out if BLAS Subprograms are installed on your systems.
           Try:

           man blas

           Or ask your system admin. Many vendors provide optimized
           versions of those subroutines which provide signifcantly better
           performance. MATCOM can use the BLAS library.

           6. The makefile name will depend upon the configuration:

           For pre-2.7.0 gcc:

           gcc.mak

           For 2.7.0 and later gcc:

           gcc27.mak

           For pre-2.7.0 gcc with BLAS:

           gccbls.mak

           For 2.7.0 and later gcc with BLAS:

           gcc27bls.mak

           On  HP systems with BLAS, use:

           gcc27hp.mak

           For DEC CXX:

           deccxx.mak

           For DEC CXX with DXML:

           decdxml.mak

           7. If ranlib is not installed on your system, delete the line
           starting with ranlib from the makefile in the matlib directory.
           To test for ranlib existance, try running it:

           ranlib

           If the command not found, ranlib is not installed.

           8. Run the selected makefile:


                                          9


           cd matlib
           make -f selected_makefile_name

           (with .mak extension)

           where selected_makefile_name is the name from step 6.

           9. The MATCOM LIBRARY will be found now in the matdisk
           directory. The other directories may be removed. If errors
           occured during compilation, read Installation trobuleshooting.
           If the problem is not solved, contact me.

           10. Identify the terminal type you are using. To see a complete
           list of gnuplot terminal types type

           set term

           at the Gnuplot command prompt.

           11. Set the enviroment variable GNUTERM to the terminal type
           you use, for X11:

           setenv GNUTERM X11

           This command should be included in your startup files (.cshrc
           or .login).

           As an alternative, the following command can be put in .gnuplot
           at your home directory:

           set term X11

           12. To use an image viewer, set the matcomviewer enviroment
           variable to the program name.
           Example:

           setenv matcomviewer xv

           13. To use a sound player, set the matcomplayer enviroment
           variable to the program name.
           Example:

           set matcomplayer xplay

           14. matlib may be compiled as a shared library - the procedure
           is system specific, consult your system and compiler
           documantation.


                                          10

           Installation troubleshooting

           Could not run ranlib

           The ranlib command is not needed on your system. Remove the
           line begining with ranlib from the makefile used.

           gcc: Internal compiler error: program cc1plus got fatal signal

           Your gcc version is too old. Upgrade!


                                          11

           Runtime troubleshooting

           Is Gnuplot installed on the path?

           Gnuplot must be installed on the path so MATCOM can find it. To
           test if Gnuplot is installed, try running it from the command
           line (or File/Run box on Windows). The Gnuplot filename is
           listed in `Which files are needed for the executable created?'.

           Is the compiler installed on the path?

           The compiler and tools must be installed on the path so MATCOM
           can find it. To test if the compiler is installed, try running
           it from the command line.

           1. Use the /make switch. This makes the compilation a two-step
           process. In the first step, a makefile is generated by the
           project manager:

           matcom sample

           In the second step, compile using make:

           make sample.mak

           2. See the section matcom.dos vs. matcom.win.

            ``table of contents for archive is out of date''

           The library date has changed. Run:

           ranlib matlib.a

           If ranlib is not installed on your system, run:

           ar s matlib.a

           Erratic results with DJGPP 2

           Recompile the library, adding the flag

           -float-store

           to the CPPFLAGS= line in the makefile djgpp.mak. This will hurt
           performance. It seems the problem is the generated code
           sometime overflows the FPU stack.


                                          12

           Wrong Inf/NaN operation with Linux

           Add the -mp-ieee switch to the CPPFLAGS line in the makefile
           and recompile the library.

           Wrong Inf/NaN operation with OSF1

           The cxx compiler does not generate correct code. Try using gcc
           instead.

           Wrong Inf/NaN operation with HPUX

           Results are correct but output is ? for NaN and ++ for Inf.

           core dump/segmentation failure with gcc

           If matcom, mat2cpp or the executable core dumps, please follow
           these steps:

           1. Recompile the MATCOM sources, removing the -O2 switch and
           adding the -g switch to the CPPFLAGS= line in the makefile.
           Example

           CPPFLAGS = -c -O2 -w -DNDEBUG -fno-inline

           Should be changed to:

           CPPFLAGS = -c -w -DNDEBUG -fno-inline -g

           2. Try again. If the problem persists, load the offending
           program with gdb.

           gdb matcom filename.m

           or

           gdb filename

           3. From gdb, type r.

           4. When the program aborts, type bt to produce a backtrace.

           5. Type info locals to produce variable value list.

           6. E-Mail me the Bug report along with the outputs.

           Compiling MATCOM LIBRARY for other systems

           MATCOM LIBRARY should compile and run with minimal changes
           using gcc on most Unix platforms. IEEE 754 floating point
           compliance is needed for correct operation of NaN/Inf. If you
           ported (or wish to port) MATCOM LIBRARY to another
           platform/OS/compiler, please contact me.


                                          13

           Limitations


           Matrix size

           Under Windows, matrices are limited to 8190 elements. This
           stems from the 64K segment limitation.
           Under Win32, Windows 95, Unix and DJGPP avaliable memory
           (physical+virtual) limits the size of matrices.

           Graphics

           Handle graphics, Matlab 4 style, are not supported. The image,
           colormap and related command are supported.

           Debugging

           The dbstop, dbclear,... functions are not implemented. However,
           the debug version enables debugging compiled programs using the
           C++ debugger.

           Sparse

           Sparse matrices are not yet implemented.


                                          14

            Compatibility


           The first design guide was to achieve the highest compatibility
           possible with the Matlab(R) language. However, this was not
           always possible. In several areas compromises were made:

           Matlab

           & and |

           & and | will not be short-circuit evaluated. The following code
           will fail:

           l=length(x)
           i=1
           while i<=l & x(i)>2
             x(i)
             i=i+1;
           end

           ans

           Not supported due to overhead.

           clc

           Not implemented on Windows.

           contour

           Countour plot includes a mesh plot since that is the only way
           Gnuplot plots it.

           diary

           Not implemented.

           etime

           Calculates years, months & days difference correctly.

           exist

           Return 2 if file exists, 0 otherwise: does not check for
           variable existance.

           eval

           No eval function: No support can be given to these (useful!)
           function.

           feval

           Is partially supported, with the following limitations:

           o The feval funfun argument must be an input argument of the
           containing function
           o The feval funfun argument can not be a variable


                                          15

           o The funfun argument must be first argument of the containing
           function
           o The name of the containing function must be added at the end
           of the matcom.rsv file

           The fzero, ode23, ode23p, ode45, fsolve2, fmin, fmins functions
           work.

           See the fmax.m example.

           flops

           Not implemented.

           format

           format long, format short (default) are supported..

           help

           Not implemented.

           home

           Not implemented on Windows.

           image

           Implemented using an extrenal BMP viewer.

           input

           Accepts only real scalars form keyboard. input(prompt,'s')
           accepts string input. Input is not evaluated i.e. 1+1 will not
           return 2.

           isglobal

           Not implemented.

           keyboard

           Not implemented: no interpreter.

           lasterr

           Not implemented.

           load

           If more than one variable is to be loaded, variables must be
           specified explicitly.
           If one variable named different form filename is to be loaded,
           variables must be specified explicitly.
           Syntax: load filename [var1 var2 var3] [-ascii]

           lookfor

           Not implemented.


                                          16


           matlabpath

           This command has no effect since the function path is
           determined at compile time, not runtime.

           nargout

           MATCOM can not distinguish between nargout being 0 or 1. Even
           if there is no output argument, nargout will be 1.

           pack

           Not implemented.

           path

           See matlabpath.

           qz

           The QZ algorithm is not supported for complex arguments.

           sscanf

           Not implemented (fscanf does).

           unix

           Not implemented.

           what

           Not implemented.

           which

           Not implemented.

           who

           Not implemented.

           zp2ss

           The source file zp2ss.m needs to be changed as follows. Make a
           copy of the file and replace the line:

           eval('[num,den] = zp2tf(z,p,k);')

           with:

           [num,den] = zp2tf(z,p,k);

           before compiling.

           Octave


                                          17

           Octave is a Matlab-compatible interpreter with many useful
           language extensions. Octave .m files can be used with MATCOM if
           only supported extensions are used. See `Where to find Octave'.

           Supported extensions

           # comments, endif, enddo, endwhile, endfor, endfunctions, ++, -
           -, continue, <>, !=, arg, stdin, stdout, stderr.
           stdin, stdout and stderr will work only with printf/fprintf.

           Unsupported extensions

           ! operator as not, save/load syntax, functions builtin,
           variable argument list.


                                          18

           Runtime error messages


           Matrix names

           Usually, the error message will include the matrix name. If the
           matrix was nameless (temporay), a ? will be substituted.

           Example:

           a=1;
           a(2)
           error: a(?): index out of matrix

           This happens since the `2' has no matrix name associated with
           it.


                                          19

           Other


           Where is ...

           Please see the file where-is.txt.

           Bug reports

           Bug reports should include the following information:

           o MATCOM LIBRARY version
           o Platform and OS
           o C++ compiler
           o Bug example - please include all files needed to reproduce
           the bug.
           o Bug description.
           o A transcript showing the bug is helpful. The Unix command
           script may be used.

           See also `core dump using gcc'.

           How to reach me

           Please mail so you can be notified of future releases of
           MATCOM.
           e-mail: yak@techunix.technion.ac.il


                                          20

           The MATCOM LIBRARY Reference


           Introduction

           The library includes matrix, file i/o, graphics, string and
           text i/o functions.
           The MATCOM translator is an automatic tool to convert your
           existing code to C++.

           Features of MATCOM LIBRARY

           o Portable across the supported OS and compilers
           o Library fully streamable - all output/input may be redirected
           o Automatic memory management
           o Matrix operators and functions
           o File I/O functions
           o Text I/O functions
           o Graphics functions : High-level interface to Gnuplot
           o Efficient code
           o May be freely used

           matlib.h header file

           The matlib.h file includes the M class declaration, operators
           and functions defined for the M class and several helper
           functions.


                                          21

           The M matrix class

           The matrix class in matlib is named M, a class of full complex
           matricess.

            Constructors

           The only constructor used in translated programs is

           M var_name(0,0,char* var_name);

           where var_name is the variable name and 0,0 the initial rows,
           coloumns.
           Other constructors are also available:

           Real-valued variable named var_name:
           M var_name(char* var_name, double real_value);

           Complex-valued variable named var_name:
           M var_name(char* var_name, double real_value, double
           imag_value);

           String variable named var_name:
           M var_name(char* var_name, char* text_value);

           Real-valued anonymous variable:
           M var_name(double real_value);

           String anonymous variable:
           M var_name(char* text_value);

           Uninitialized anonymous variable  with number_of_rows rows and
           number_of_cols cols:
           M var_name(int number_of_rows, int number_of_cols);

           Uninitialized named variable  with number_of_rows rows and
           number_of_cols cols:
           M var_name(int number_of_rows, int number_of_cols, char*
           var_name);

           Class functions

           return number of matrix rows
           int rows();

           return number of matrix coloumns
           int cols();

           return matrix size
           int size();

           return type of matrix
           int gettype();

           set type of matrix
           void settype(int t);

           get matrix name
           char *getname();


                                          22

           return address of real part
           double *addr();

           return address of real part (row,col), row and col are 1-based
           double *addr(int row, int col);

           return address of imaginary part
           double *addi();

           return address of imaginary part (row,col), row and col are 1-
           based
           double *addi(int row, int col);

           returns double refrence to real part
           double& r();

           returns double refrence to real part(idx), idx is 1-based
           double& r(int idx);

           returns double refrence to real part(rwo,col), row,col are 1-
           based
           double& r(int idx);

           returns double refrence to imaginary part
           double& i();

           returns double refrence to imaginary part(idx), idx is 1-based
           double& i(int idx);

           returns double refrence to imaginary part(rwo,col), row,col are
           1-based
           double& i(int idx);

           Those functions are low-level access and does not perform index
           range checking. Out of index      access will core dump or GPF.

           The Mr matrix index class

           This class serves as a indexing class for M. It is created by
           operator () applied to M class. There is no need to declare
           variables of this class.

           Memory Allocation/Deallocation

           Memory management is done automatically behind the scenes.
           There is no need to allocate memory directly.

           Calling functions conventions

           Usual C++ syntax for calling functions:

           y=sin(x);
           a=atan2(x,y);

           When calling functions which return more than one result, the
           following syntax is used:

           size(A, i_o, m, n); // [m,n]=size(A);


                                          23

           The input paramets are followed by output parameters with the
           i_o in between.

           initialization - initM(matlibin,matlibout,matliberr)

           Upon entering the program, initM() must be called with an input
           stream, output stream and an error stream.
           Example:

           initM(cin,  cout, cerr);

           termination - exitM()

           Before exiting, call exitM(). Failure to call these functions
           will result in reduced or incorrect functionality of matlib.

           Input/Output streams

           The input stream is assigned to matlibin, the output stream to
           matlibout and the error stream to matliberr. Those streams are
           used by the library whenever console input/output is done.


                                          24

           Function reference

           abs(x)

           Return |x|.

           acos(x)

           Return arccos(x).

           acosh(x)

           Returns arccosh(x).

           acot(x)

           Returns acot(x).

           acoth(x)

           Returns acoth(x).

           acsc(x)

           Returns acsc(x)=asin(1/x).

           acsch(x)

           Returns acsch(x)=asinh(a/x).

           all(x)

           x vector:
           1 if all values of x are non-zero, or if x is empty
           0 otherwise
           x matrix(m,n):
            A row vector (1,n) is returned, all operates on each coloumn.

           angle(x)

           Returns angle(x)=atan2(imag(x),real(x)).

           any(x)

           x vector:
           1 if any of the values of x are non-zero
           0 otherwise
           x matrix(m,n):
            A row vector (1,n) is returned, all operates on each coloumn.

           arg(x)

           Returns arg(x)=atan2(imag(x),real(x)).

           asec(x)

           Return asec(x)=acos(1/x).

           asech(x)


                                          25

           Return asech(x)=acosh(1/x).

           asin(x)

           Returns asin(x).

           asinh(x)

           Returns asinh(x).

           atan(x)

           Returns atan(x).

           atan2(y,x)

           Returns atan2(y,x).

           atanh(x)

           Returns atanh(x).

           axis()

           Toggles graph axis on and off.

           axis(a)

           a=``on'': graph axis on
           a=``off'': graph axis off
           a=``auto'': autorange graph axis
           a=[xmin xmax ymin ymax]: set graph axis range (2-dimensional)
           a=[xmin xmax ymin ymax zmin zmax]: set graph axis range (3-
           dimensional)

           balance(x)
           balance(x, i_o_t, t, b)

           balance matrix x and isolates eigenvalues whenever possible
           using the eispack balanc routine. Returns the balnaced matrix b
           and transformation matrix t.

           black(l)

           Returns an all-black colormap of size l.

           bmpwrite(img,map,filename)

           Write the image img with colormap map to the file filename in
           the BMP format.

           brackets(int type,...)

           Concatenates matrix.
            type=`d': all following values must be doubles. s_d means next
           row, l_d means end of list.
            type=`s': all following values must be char*. s_s means next
           row, l_s means end of list.
            type=`M': all following values must be M class. s_M means next
           row, l_M means end of list.


                                          26


           Failure to use only allowed types or finish the list with an
           end of list will return unpredictable results.

           cd()

           Return current directory.

           cd(dir)

           Change to dir directory.

           ceil(x)

           Return ceil(x) which is the smallest integer not smaller than
           x.

           chol(x)
           chol(x, i_o_t, R, p)

           Returns the cholesky factorization of x using the linpack pofa
           routine. x must be positive definite unless the second form is
           used. Then, if x is positive definite, R=x and p=0. Otherwise,
           R*R' is the square matrix of size (p-1) : X(1:(p-1),1:(p-1)).

           clc()

           Clear screen. This function does not work under Windows.

           clear(x)

           Sets the variable x to [].

           clockM()

           Returns current time as a row vector: [year month day hour
           minute second].

           colon(a,b,c)

           Returns a vector of values from a to c with stepsize b.

           colormap(map)

           Sets the current colormap to map.

           computer()
           computer(i_o_t, c, maxsize)

           Returns computer name and MATCOM version. If second form is
           called, name is in c and matrix maximum size is returned in
           maxsize.

           cond(x)

           Returns the matrix condition number which is the ratio between
           the largest and smallest singular value using the linpack svdc
           routine.


                                          27

           conj(x)

           Returns the complex conjugate of x.

           contour(Z)
           contour(Z, N)
           contour(X,Y, Z)
           contour(X, Y, Z, N)

           Plots contour plot x. If N is also given, plots with N lines.
           If X and Y are given, they are used as axes.

           cos(x)

           Return cos(x).

           cosh(x)

           Returns cosh(x).

           cot(x)

           Return cot(x)=1/tan(x).

           coth(x)

           Return coth(x)=1/tanh(x).

           cputime()

           Always returns zero.

           csc(x)

           Returns csc(x)=1/sin(x).

           csch(x)

           Returns csch(x)=1/sinh(x).

           cumprod(x)

           Returns comulative product of x multiplied along the coloumns.

           cumsum(x)

           Returns comulative sum of x added along the coloumns.

           deleteM(filename)

           Erase filename.

           det(x)

           Returns det(x) using the linpack geco and gedi routines.

           dft(x)

           Returns the discrete Fourier transform of x.


                                          28

           diff(x, order=one_M)

           Returns the difference vector between x values. If x is matrix,
           the difference is computed along the coloumns.

           dir()

           Lists file directory.

           disp(x,ostream& outstream=matlibout)

           Shows matrix x on the stream outstream. The default is
           matlibout which is tied to the screen.

           dos(command)

           Execute system command.

           dot_add(x,y)

           Returns x+y, done on each element.

           dot_div(x,y)

           Returns x/y, done on each element.

           dot_invdiv(x,y)

           Returns y/x, done on each element.

           dot_mul(x,y)

           Returns x*y, done on each element.

           dot_pow(x,y)

           Returns x^y, done on each element.

           dot_sub(x,y)

           Returns x-y, done on each element.

           dot_transpose(x)

           Returns the non-conjugate transpose of x.

           drawnow()

           Forces graph display.

           eig(a, b)
           eig(a, b, i_o_t, v, d)

           Returns the generalized eigenvalues and (second forrm)
           eigenvectors of a and b using the eispack qzhes, qzit, qzval,
           qzvec. Complex arguments are not supported.

           eig(x)
           eig(x, i_o_t, v, d)


                                          29

           Returns the eigenvalues and (second forrm) eigenvectors of x
           using the recommended eispack routines (rg, cg and ch).

           eps

           Returns machine epsilon. On IEEE mahcines, eps=2^-52.

           error(x)

           Displays error message on matliberr and exit.

           errorbar(y, l)
           errorbar(x, y, l)
           errorbar(x, y, l, u)

           Displays an errorbar graph of x,y with u upper part and l lower
           part. If u is ommited it is assumed u=l.

           etime(t1, t0)

           Returns time difference between t1 and t0. t1 and t0 are
           vectors returned from clockM. This routine deals correctly with
           month end, year end and leap years.

           eval(...)

           Writes an error message and exists.

           exist(x)

           Return 2 if file named x exists, 0 otherwise. This routine does
           not test for variable existance.

           exit()

           Exit the current program. Internally, exitM() is called.

           exp(x)

           Returns exp(x).

           expm(x)

           Return matrix exponential of x.

           eye(x)
           eye(x,y)

           Return I sized (x,x) or (x,y).

           fcloseM(fid)

           Close file id fid.

           feofM(fid)

           Return 1 if file fid is at end of file.


                                          30

           ferrorM(fid, clear=zero_M)
           ferrorM(fid, i_o_t, msg, errnum)
           ferrorM(fid, clear, i_o_t, msg, errnum)

           Return error message for file fid. If clear is 1, clears the
           error condition. The error number is returned in errnum.

           feval(...)

           Writes an error message and exists. feval is implemented by
           using function pointers.

           fft(x)
           fft(x,y)

           Compute the fast Fourier transform. If y is given a y-element
           result is returned. Computation is done for each coloumn if x
           is matrix.

           filter(b, a, x)
           filter(b, a, x, zi)
           filter(b, a, x, i_o_t , y, zf)
           filter(b, a, x, zi, i_o_t i_o, y, zf)

           Filter x data using filter coefficients b and a. zi is assigned
           to initial filter conditions, final condiitons are returned in
           zf.
           The filter transform function is:

                    b(1)+b(2)*z^-1+...+b(nb)*z^(-nb+1)
            Y(z) = ------------------------------------ X(z)
                      1 +a(2)^z^-1+...+a(na)*z^(-na+1)


           find(x)
           find(x, i_o_t, I, J)
           find(x, i_o_t, I, J, v)

           Returns the indices of x non-zero elemets. The row index is
           returned in I, column index in J and a list of the elements in
           v.

           finite(x)

           Returns 1 if x is finite and 0 if not (per element).

           fix(x)

           Returns the x chopped to integer.

           fliplr(x)

           Returns x flipped left-right.

           flipud(x)

           Returns x flipped up-down.

           floor(x)


                                          31

           Return floor(x) which is the largest integer not larger than x.

           flops()
           flops(x)

           Returns 0.

           fopenM(filename, i_o_t, fid, msg)
           fopenM(filename, permission, i_o_t, fid, msg)
           fopenM(filename, permission, machine, i_o_t, fid, msg)
           fopenM(filename, permission="r", machine="n")

           Opens file filename with permission using machine format
           machine. The machine format may be `n' for native, `l' for
           little-endian IEEE or `b' for big-endian IEEE machines. An
           error message will be returned in msg.

           format(x)

           Change display format:
           x=`short', x=`s' - set short format.
           x=`long', x=`l' - set long format.

           fprintfM(fid, format, a, ...)

           Fprintf to file using the C command printf conventions in a
           vectorized fashion.

           fread(fid, i_o_t, A, count)
           fread(fid, size, i_o_t, A, count)
           fread(fid, size, precision, i_o_t, A, count)
           fread(fid, size, precision, skip, i_o_t, A, count)
           fread(fid, size=Inf, precision="uchar", skip=zero_M)

           Read data from file fid upto size data elements. The element
           size in the file is controled by presicision. If specified,
           skip bytes are skipped after each read. The result is returned
           in A with count elements read.

           frewind(fid)

           Seek the file fid to the beginning.

           fscanfM(fid, format)
           fscanfM(fid, format, size)
           fscanfM(fid, format, size, i_o_t, A, count)
           fscanfM(fid, format, size, i_o_t, A, count, errmsg)

           Fscanf form file fid using the C command scanf conventions in a
           vectorized fashion. The result is returned in A with count
           elements read and an errormessage errmsg.

           fseek(fid, offset, origin)

           Seek the file fid to offest. Origin may be:
           `bof' - origin is relative to beggining
           `cof' - origin is relative to current pointer
           `eof' - origin is relative to enf of file, backwards


                                          32

           ftell(fid)

           Returns file fid position.

           full(x)

           Returns x.

           fwrite(fid, A, precision="uchar", skip=zero_M)

           Writes data A to file fid. The element size in the file is
           controled by presicision. If specified, skip bytes are skipped
           after each write.

           getenv(x)

           Returns the enviroment value of the variable x.

           gray(l)

           Returns a gray colormap of size l.

           grid()

           Toggles graph grid on and off.

           grid(a)

           a=`on': graph grid on
           a=`off': graph grid off

           hess(a)
           hess(a, i_o_t, p, h)

           Returns the hessenberg form of the matrix a using the eispack
           routines. In the second form, Both the transformation matrix P
           and the hessenberg form h are returned.

           hilb(n)

           Returns the Hilbert matrix of order n.

           hold(a)

           a=`on': the next plot command will add onto the current plot
           a=`off': the next plot command will be a new plot

           home()

           Returns the cursor to top-left position.

           ifft(x)
           ifft(x,y)

           Compute the fast inverse Fourier transform. If y is given a y-
           element result is returned. Computation is done for each
           coloumn if x is matrix.

           imag(x)


                                          33

           Returns the imaginary part of x.

           image(img)

           Display the image img.

           Inf

           Return infinity.

           input(x)
           input(x, s)

           Displays prompt x and returns the user input. The second form
           returns user input as string.

           int2str(x)

           Returns string form of matrix x.

           inv(x)

           Returns inverse of x using the linpack geco and gedi routines.

           invdiv(a, b)

           Returns b divided by a. b and a represent a linear equation
           system. Gaussian elimination is used if a is square and b has
           the same number of rows using the linpack gefa, gesl routines.
           Otherwise, least-square solution is returned using the linpack
           qrdc, qrsl routines.

           invhilb(n)

           Returns the inverse Hilbert matrix of order n.

           ishold()

           Returns the graph hold state.

           isieee()

           Always return 1. MATCOM ports to IEEE systems only.

           isinf(x)

           Return 1 if x is Infinity.

           isnan(x)

           Return 1 if x is NaN.

           joincols(a, b)

           Returns [a b].

           joinrows(a, b)

           Returns [a ; b].


                                          34

           length(x)

           Returns length(x).

           linspace(x1, x2, n=100)

           Returns a row vector with n values from x1 to x2, equal
           spacing. If n is not specified, a default of 100 is used.

           load(char *fname, a, ...)

           Load upto ten variables from the file fname.

           loadascii(char *fname, M& a)

           Load one variable from an ascii file.

           log(x)

           Returns log(x).

           log10(x)

           Returns log10(x).

           log2(x)
           log2(x, i_o_t, f, e)

           Returns log2(x). If the second from is used, x IEEE mantissa is
           returned in f, x IEEE exponent in e.

           loglog(y,...)

           Plots on logarithmic x and y scales.

           logspace(x1, x2, n=50)

           Returns a row vector with n values from x1 to x2, logarithmic
           equal spacing. If n is not specified, a default of 50 is used.

           ltifr(a, b, s)

           Returns the frequency response of the system h(s)=(sI-a)\b for
           vector s.

           ltitr(a, b, u, x0)

           Returns the time respone of the system x(n+1)=a*x(n)+b*u(n)
           with initial x=x0.

           lu(x)
           lu(x, i_o_t, l, u)
           lu(x, i_o_t, l, u, p)

           Returns the result of the linpack gefa routine. The second form
           returns the lu decomposition of x such that x=l*u. In the third
           form, p*x=l*u.

           magic(n)


                                          35

           Returns a magic square of order n.

           matlabpath()
           matlabpath(x)

           Those functions has no effect.

           max(x)
           max(x, i_o_t, y, I)

           Returns maximum of x take columonwise. If x is complex, the
           absolute value is used. The second form returns y=max(x) and an
           index I of the values.

           max(x,y)

           Returns max(x,y).

           mean(x)

           Return the average of x taken coloumnwise.

           menu(title,choice1,...)

           Displays a menu of the choices and returns the number entered
           by the user.

           mesh(z)
           meshc(z)
           mesh(x,y,z)
           meshc(x,y,z)

           Plots a mesh defined by z. If x and y are specified, they are
           used as axes. The meshc function also plots a contour under the
           mesh.

           min(x)
           min(x, i_o_t, y, I)

           Returns minimum of x take columonwise. If x is complex, the
           absolute value is used. The second form returns y=max(x) and an
           index I of the values.

           min(x,y)

           Return min(x,y);

           NaN

           Return IEEE NaN.

           nargin

           Return the number of function input arguments.

           nargout

           Return the number of function output arguments. Note that
           nargout is never zero.


                                          36

           nnz(x)

           Returns the number of non-zeros values in x.

           nonzeros(x)

           Returns the non-zeros values in x.

           nop_M

           Return an empty matrix.

           norm(x, P=two_M)

           If x is a vector

           P=inf,  returns max(abs(x)).
           P=-inf,  returns min(abs(x)).
           Otherwise, returns sum(abs(v)^P)^(1/P).

           If x is matrix

           P=2, returns the max(svd(x)).
           P=1, returns max(abs(sum(x))).
           P=inf,'inf' returns max(abs(sum(x'))).
           P=`fro', returns sqrt(sum(diag(x'*x))).

           num2str(x, prec=4)

           Returns the string representation of x with precision prec.

           one_M

           Returns 1.

           ones(x)
           ones(x, y)

           Return ones matrix sized (x,x) or (x,y).

           operator ! (x)

           Returns logical not x.

           operator && (x, y)

           Returns logical x and y.

           operator || (x, y)

           Returns logical x or y.

           operator * (x, y)

           Returns x*y (matrix multiplication).

           operator + (x,y)

           Returns x+y.


                                          37

           operator - (x)

           Returns -x.

           operator - (x, y)

           Returns x-y.

           operator /(x, y)

           Returns x/y (matrix division).

           operator < (x,y)

           Returns logical x<y.

           operator <= (x,y)

           Returns logical x<=y.

           operator == (x,y)

           Returns logical x==y.

           operator > (x,y)

           Returns logical x>y.

           operator >= (x,y)

           Returns logical x>=y.

           operator!= (x,y)

           Returns logical x<>y.

           operator<<(ostream& outstream, M& x)

           Displayes matrix x on stream outstream.

           pascalM(n, r=zero_M)

           Returns Pascal matrix of order n. If r=1 the lower triangular
           Cholesky factor of the Pascal matrix is returned. If r=2 a
           transposed and permuted version is returned.

           pauseM()
           pauseM(x)

           Pauses until a key is pressed. If x is given:
           x=`off', ignore all pause calls
           x=`on', pause on all pause calls
           n, pause for n seconds

           plot(y,...)

           Plot graphs. With one argument, plots y vs. running integer.
           With two arguments, y vs. x.


                                          38

           polar(theta,r)
           polar(theta,r,s)

           Plots polar plot of r vs. theta. s may be used to modify the
           plot style.

           pow2(x)
           pow2(x,y)

           Returns 2^x. Second form creates a number whose IEEE mantissa
           is x and exponent is y.

           powM(x,y)

           Returns x^y. Either x or y may be a matrix but not both.

           printfM(format, a, ...)

           Print the matrix a using C printf format format.

           prod(x)

           Returns the coloumnwise product of x.

           qr(x)
           qr(x, i_o_t, q, r)
           qr(x, i_o_t, q, r, e)

           Returns the output from linpack qrdc routine. The second form
           eturns the qr factorization of x, x=q*r. In the third form,
           x*e=q*r.

           qr(x, M)
           qr(x, M, i_o_t, q, r)
           qr(x, M, i_o_t, q, r, e)

           Returns the economy size qr factorization.

           quit()

           Quits the program. Before quitting, exitM is called.

           quiver(x)
           quiver(x,y)
           quiver(x,y,s)

           Plots a quiver plot.

           qz(a, b, i_o_t, aa, bb)
           qz(a, b, i_o_t, aa, bb, q)
           qz(a, b, i_o_t, aa, bb, q, z)
           qz(a, b, i_o_t, aa, bb, q, z, v)

           Return the generalized eignevalues of a and b using the qz
           algorithm, q*a*z=aa, q*b*z=bb, a*v*diag(bb)=b*v*diag(aa). The
           alphas and betas eignevalues are on the diagonal of aa and bb.


                                          39

           randM()
           randM(x)
           randM(x,y)

           Return a uniformly distributed random number. The second form
           return a random (x,x) matrix, the third form random (x,y)
           matrix.
           The third form may be also used to set the seed where x=`seed'
           and y=seed.


           randn()
           randn(x)
           randn(x,y)

           Return a uniformly distributed random number. The second form
           return a random (x,x) matrix, the third form random (x,y)
           matrix.
           The third form may be also used to set the seed where x=`seed'
           and y=seed.

           rank(x)
           rank(x, tol)

           Returns the number of singular values larger than
           eps*max(size(x))*max(svd(x)). In the second form, returns the
           number of singular larger than tol.

           rcond(x)

           Returns an estimate for x condition using the linpack geco
           routine.

           real(x)

           Returns the real part of x.

           rem(x,y)

           Returns the reminder of x,y.

           reshape(x, m, n)

           Returns x reshaped to have m rows and n coloumns.

           rot90(x, k=one_M)

           Returns x rotated 90*k degrees counter-clockwise.

           round(x)

           Returns x rounded to an integer.

           save(char *fname, a,...)

           Saves upto ten variables in the file filename.

           saveascii(char *fname, a,...)

           Saves upto six variables in the file filename in ascii format.


                                          40


           schur(x)
           schur(x, i_o_t, u, t)

           Returns the Schur form of x using the eispack routines. In the
           second from, x=u*t*u' and u*u'=I.

           sec(x)

           Returns sec(x)=1/cos(x).

           sech(x)

           Returns sech(x)=1/cosh(x).

           semilogx(y,...)

           Plots on semilogarithmic x scale.

           semilogy(y,...)

           Plots on semilogarithmic y scale.

           setstr(x)

           Sets x to a string without modifying its values.

           shg()

           Update graphics display.

           sign(x)

           Returns sign(x).

           sin(x)

           Returns sin(x).

           sinh(x)

           Returns sinh(x).

           size(x)
           size(x, i_o_t, m_Mat, n_Mat)
           size(x, type)

           Returns a two-element vector with x rows and x coloumns. The
           second form puts x rows in m_Mat and x coloumns in n_Mat. The
           third form returns x rows if type is 1 and x coloumns if type
           is 2.

           sort(x)
           sort(x, i_o_t, S, I)

           Return sorted x. In the second form, the sorted matrix is
           returned in S and a sort index in I.

           soundM(y, rate=8192)


                                          41

           Plays a sound y at samplerate rate.

           sparse(...)
           spdiags(...)
           spparms(...)

           Compatibilty functions, sparse matrices are not supported.

           sprintfM(format, a,...)

           Printf a matrix a using C format string format.

           sqrtM(x)

           Return sqrt(x).

           sscanfM(s, format)
           sscanfM(s, format, size)
           sscanfM(s, format, size, i_o_t, A, count)
           sscanfM(s, format, size, i_o_t, A, count, errmsg)

           sscanf is not supported.

           stderrM
           stdinM
           stdoutM

           Those streams are valid file identifiers for the file i/o
           functions.

           str2mat(a,...)

           Creates a string matrix out of the argument list.

           strcmp(a,b)

           Returns 1 if a and b are same strings.

           sum(x)

           Return sum of x, taken coloumnwise.

           svd(x)
           svd(x, i_o_t, U, S, V)

           Returns the singualr values of x using the linpack svdc
           routine. The second form also returns the u and v, x=u*s*v'.

           svd(x, z)
           svd(x, z, i_o_t, U, S, V)

           Returns the economy size svd decomposition.

           systemM(cmd)

           Runs the specified cmd.

           tan(x)

           Returns tan(x).


                                          42


           tanh(x)

           Returns tanh(x).

           text(x,y,a)

           Places text a at (x,y) on the graphic display.

           tic()

           Starts a timer.

           title(a)

           Sets graph title to a.

           toc()

           Stops and displays the timer.

           transpose(x, int d=0)

           Return x transposed. If d=1, x is not cojugated.

           tril(x)
           tril(x, y)

           Return the lower triangular matrix of x. In the second form,
           the y-diagonal and below matrix is returned.

           triu(x)
           triu(x, y)

           Return the upper triangular matrix of x. In the second form,
           the y-diagonal and above matrix is returned.

           two_M

           Returns 2.

           type(fname)

           Types the filename fname into the screen.

           view(a)
           view(az,el)

           Sets the view angle to az azimuth and el elavation. In the
           first form,
           a=[az el], sets the view angle:
           a=3, az=-37.5 and el=30.
           a=2, az=0 and el=90.

           warning(x)

           Display a warning message x.

           wavwrite(wavedata, rate, filename)


                                          43

           Write wavedata to a .wav file filename with samplerate rate.

           white(l)

           Return white colormap of size l.

           whos()

           Dispalys list and sizes of variables.

           xlabel(t)

           Sets the graph x label to t.

           xorM(x,y)

           Return logical x xor y.

           ylabel(t)

           Sets the graph y label to t.

           zero_M

           Return 0.

           zeros(x)
           zeros(x,y)

           Return zeros matrix sized (x,x) or (x,y).

           zlabel(t)

           Sets the graph z label to t.


                                          44

           Examples

           magic.cpp

           The files magic.cpp, magicsum.m and makefile demonstrate how to
           compile and link .m files together with C++ code. To compile
           the example:

           for BC++:

           make -f makefile.bcc

           for gcc:

           make -f makefile.gcc

           OWL example - owl.cpp

           The files owl.cpp and owl.ide demonstrate how to use MATCOM
           LIBRARY in a Borland C++ OWL program. To run the example open
           the project owl.ide in the Borland IDE and run it.

           If you wish to use the win32 library within OWL programs, see
           the instructions below.


                                          45

           Compiler switches

           The following compiler switches should be used when linking
           with the matlib library:

           Borland C++ 3.1
           Flags: -w- -ml -A -WE mlibbc3w.lib
           Meaning: No warnings, Large memory model, ANSI mode, Windows
           app, Link with mlibbc3w.lib.

           Borland C++ 4.X
           Flags: -w- -x- -ml -A -WE mlibbc4w.lib
           Meaning: No warnings, no exceptions, Large memory model, ANSI
           mode, Windows app, Link with mlibbc4w.lib.

           Borland C++ 4.X / Win32s
           Flags: -w- -x- -A -WE mlibbc32.lib
           Meaning: No warnings, no exceptions, ANSI mode, Windows app,
           Link with mlibbc32.lib.

           Borland C++ 4.X / Win32
           Flags: -w- -x- -A -WC mlibbc32.lib
           Meaning: No warnings, no exceptions, ANSI mode, Console app,
           Link with mlibbc32.lib.

           Borland C++ 4.X / Win32+OWL
           Before using the library, modify it with the command:

           tlib mlibbc32.lib -wintty.obj -winttyc.obj

           Use same flags as Borland C++ 4.X/Win32, linking must be
           static.

           Visual C++ 1.X
           Flags: /f /G2 /YX /Mq /AL mlibvc1w.lib
           Meaning: Fast compiler,  286 code, Precompiled header, QuickWin
           support, Large memory model, Link with mlibvc1w.lib.

           Visual C++ 2.X
           Flags: /YX /O2 user32.lib mlibvc2w.lib
           Meaning: Precompiled header, Optimize, Link with user32 and
           mlibvc2w.lib.

           WATCOM C++
           Flags: /bt=windows
           Meaing: target windows
           Linker respone file should include:
            system win386
            option stack=128k
            library mlibwt.lib
            name projectname.rex

           wbind -n projectname is needed after wlink.


                                          46

           DJGPP
           Flags: -lmlib -lgpp -lpc -lm
           Meaing: link with matlib, C++, PC specific and math libraries.

           DEC CXX
           Flags: -lmlib -lm
           Meaing: link with matlib and math libraries. To use the dxml
           library -ldxml is needed.

           Gnu C++
           Flags: -lmlib -lg++ -lm
           Meaing: link with matlib, C++ and math libraries.
           To link with BLAS, add -lblas.

           Gnu C++ 2.7 or above
           Flags: -lmlib -lg++ -lstdc++ -lm
           Meaing: link with matlib, C++, standard C++ and math libraries.
           To link with BLAS, add -lblas.

           SGI CC
           Flags: -lmlib -lm
           Meaing: link with matlib and math libraries.
           To link with BLAS, add -lblas.

           BLAS, all UNIX
           The fortran libraries might be needed after the blas library:
           -lblas -lftn -lm
           or
           -lblas -lf2c -lm