


























                                        MATCOM

                 A Matlab(R) to C++ translator and support libraries

                                 August 1995 release


                                          2



           TABLE OF CONTENTS




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


           LEGAL STUFF ..................................................5

             Copyright ..................................................5
             Disclaimer .................................................5
             Trademarks .................................................5

           WHAT IS MATCOM? ..............................................6

             Introduction ...............................................6
             Features ...................................................6
             Release notes ..............................................6

           REQUIREMENTS .................................................7

             Platform and OS ............................................7
             C++ compiler ...............................................7
             Gnuplot ....................................................7

           INSTALLATION .................................................8

             PC Release .................................................8
               If you do not have Windows ...............................8
             SunOS Release ..............................................8
             Testing the installation ...................................9
             Troubleshooting ............................................9
               Is Gnuplot installed on the path? ........................9
               Is the compiler installed on the path? ...................9
               Low DOS memory? ..........................................9

           COMPILING MATLAB FILES ......................................10

             MATCOM project manager ....................................10
               Example .................................................10
             The mpath file ............................................10
             Debug version .............................................10
               Example .................................................11
             Scalar Mode ...............................................11
               Example .................................................11
             mat2cpp translator ........................................11
             matcom.ini ................................................11

           LIMITATIONS .................................................13

             Matrix size ...............................................13
             Graphics ..................................................13
             Debugging .................................................13
             Sparse ....................................................13

           COMPATIBILITY ...............................................14


                                          3

             & and | ...................................................14
             ans .......................................................14
             diary .....................................................14
             disp ......................................................14
             exist .....................................................14
             eval, feval ...............................................14
             format ....................................................14
             help ......................................................14
             isglobal ..................................................14
             keyboard ..................................................14
             lasterr ...................................................14
             load ......................................................15
             lookfor ...................................................15
             pack ......................................................15
             save ......................................................15
             unix ......................................................15
             what ......................................................15
             which .....................................................15
             who .......................................................15
             whos ......................................................15

           PERFORMANCE .................................................16

             Matrix mode ...............................................16
             Scalar mode ...............................................16
             Tips ......................................................16
               Preallocate variables ...................................16
               Scalar mode .............................................16
               Use vector operations ...................................16
               Inline small functions ..................................16

           OTHER .......................................................17

             Which files needed for the executable created? ............17
             How to run MATCOM from different directory? ...............17
             Executable size ...........................................17
             MEX files .................................................17
             Where to get DJGPP ........................................17
             Where to get Gnuplot ......................................17
             Where to get MATCOM .......................................17
             WWW home page .............................................17
             How to reach me ...........................................18

           APPENDIX A : MATLIB LIBRARY .................................19

             Introduction ..............................................19
             The M Matrix Class ........................................19
             Features of matlib ........................................19
             Short Library Reference ...................................19
               matlib.h header file ....................................19
               Constructors ............................................19
               Class functions .........................................19
               Allocation/Deallocation .................................20
               Calling functions .......................................20
               More than one return values .............................20
               InitM() and ExitM() .....................................20
               Operators ...............................................20
               Matrix functions ........................................20
               Text I/O functions ......................................21
               File I/O functions ......................................21


                                          4

               Graphics functions ......................................21
             Using the library with your programs ......................21
               Example .................................................21
             Compiler switches .........................................21
               Borland C++ 3.1 .........................................22
               Borland C++ 4.X .........................................22
               Borland C++ 4.X / Win32s ................................22
               Visual C++ ..............................................22
               DJGPP ...................................................22
               Gnu C++/SunOS ...........................................22

           APPENDIX B : FILES INCLUDED .................................23

             PC Release ................................................23
             SunOS Release .............................................23


                                          5

           Legal stuff


           Copyright

           This software is copyrighted work by Yaron Keren.  It is a
           copyrighted freeware, no payment needed for the use of this
           software. MATCOM may be distributed for a nominal distribution
           fee and may be included in a CD-ROM collection.

           APPLICATIONS, EXECUTABLES, OBJECTS, LIBRARIES, SOURCE CREATED
           WITH MATCOM INCLUDING THE MATLIB LIBRARY MAY BE USED FOR ANY
           PURPOSE WITHOUT CHARGE.

           Disclaimer

           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 YARON KEREN BE LIABLE FOR ANY SPECIAL,
           INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR
           ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
           PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE,
           AND ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION
           WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

           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 other companies mentioned in this documentation
           appear for identification purposes only and are the property of
           their respective companies.

           DJGPP - from the readme.dj file -
           ``This package contains a 32-bit 80386 DOS extender with
           symbolic debugger, a C/C++ compiler with utilities, development
           libraries, and source code. It generates full 32-bit programs
           and supports full virtual memory with paging to disk.''

           Gnuplot - from the 0readme file -
           ``Gnuplot is a command-line driven interactive function
           plotting utility for UNIX, MSDOS, and VMS platforms.  The
           software is copyrighted but freely distributed.
           Copyright (C) 1986-1993 Thomas Williams, Colin Kelley''


           BY USING MATCOM YOU AGREE TO ALL OF THE ABOVE.


                                          6

           What is MATCOM?


           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 is a Matlab(R) to C++ translator and support library.

           Features

           o  highly compatible with the Matlab dialect
           o  readable and efficient C++ produced
           o  may be integrated with your routines/libraries
           o  speed up factors of x10 achieved
           o  all C++ code and executable produced are free for any use

           Release notes

           This is the third release for PC, first for SunOS. Your
           comments, wishes and bug-reports are most welcome.


                                          7

           Requirements


           Platform and OS

           PC and Sparc compatibles are supported.
           Operating systems support for the PC include:

           o Windows
           o Win32
           o GO32 (Extended DOS)

           On the Sparc,  SunOS is supported.

           C++ compiler

           The following compilers are supported:

           o  Windows: Borland C++ 3.1, Borland C++ 4.0/4.5, Visual C++
           1.X
           o  Win32: Borland C++ 4.0/4.5
           o  GO32: DJGPP C++
           o  SunOS: GNU C++

           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.


                                          8

           Installation


           PC Release

           1. Create a directory where you want MATCOM installed.

           2.  Unzip matcom.zip in the directory selected.

           3. In Windows, From the File menu, select Run. In the Command
           Line: box, type the MATCOM directory followed by setup.exe.
           Example:

           C:\MATCOM\SETUP.EXE

           4. Select the C++ compiler you have. You must have one of the
           supported compilers to use MATCOM. Click on OK.

           5. If Matlab is installed, enter the Matlab directory. Click on
           OK.

           6. Matsetup compiles matlabrc.m. When compilation is done,
           press any key to continue.

           7. Matsetup runs matlabrc. When finished running, close the
           matlabrc window. Installation continues only after the matlabrc
           window is closed.

           8. Installation complete. See `Compiling Matlab Files'.

           If you do not have Windows

           Follow SunOS installation steps, below. Skip steps 3-4.

           SunOS Release

           1. Create a directory where you want MATCOM installed.

           2. Unzip matcom.zip in the directory selected.

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

           set term

           at the Gnuplot command prompt.

           4. 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


                                          9

           5. Run matcom.

           6. Select GNU C++ compiler.

           7. Answer if Matlab is installed.

           8. MATCOM runs Matlab with a short script file.

           9. If MATCOM failed running Matlab and it is installed, enter
           Matlab directory.

           10. MATCOM compiles matlabrc.m.

           11. MATCOM runs matlabrc.

           12. Installation complete. See `Compiling Matlab Files'.

           Testing the installation

           1. Run MATCOM.

           2. At the source file name prompt enter sample.m.

           3. MATCOM translates sample.m and grad.m.

           4. MATCOM compiles sample.cpp and grad.cpp.

           5. Run sample.exe (SunOS:sample).

           If  you see a dipole force-line graph, installation is OK.

           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). The Gnuplot filename is listed in
           `Which files 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.

           Low DOS memory?

           C++ tools require lots of memory. Also, try to maximize the
           available low memory: 590K is needed for translating large .m
           files.


                                          10

           Compiling Matlab files


           MATCOM project manager

           To automate the creation of applications, a project manager is
           provided. Under Windows, an icon is placed in the MATCOM
           program group.
           The script source file may be specified to MATCOM in one of two
           ways:

           o  as a command line argument
           o  Entered at the prompt

           The .m extension is optional. MATCOM translates the functions'
           source files needed for the application and runs the C++
           compiler. Translation/compilation is based on file dates in
           make-like fashion.
           After running it, a ready to run executable will be found. The
           executable will be named according to operating system
           conventions.

           Example

           To compile the example provided, run

           MATCOM speed.m

           And

           speed

           Gnuplot must be installed to see the plot.

           The mpath file

           The mpath file, created during the installation contains list
           of directories MATCOM searches for .m files, one directory per
           line.
           Example mpath:

           c:\matlab\toolbox\local
           c:\matlab\toolbox\matlab\datafun
           c:\matlab\toolbox\matlab\elfun
           c:\matlab\toolbox\matlab\elmat
           c:\matlab\toolbox\matlab\funfun
           c:\matlab\toolbox\matlab\general
           c:\data\mfiles\
           c:\exp-1-95

           The mfile may be edited with any text editor such as Windows
           notepad.

           Debug version

           MATCOM can create programs with symbolic debug information.
           Such programs may be debugged with a C++ debugger which comes
           with the compiler.  Under Windows, an icon is placed in the
           MATCOM program group.


                                          11

           From the command line, add the switch -g to create the symbolic
           information.

           Example

           MATCOM example.m -g

           The program may be debugged, using Borland C++ :

           tdw example.exe

           Scalar Mode

           A scalar-only function does not use

           o any vector/matrix
           o indexing
           o complex arithmetic

            MATCOM provides special support for those cases, translating
           the datatype into C double, resulting in much faster
           processing.
           Scalar mode is selected per source file by including the
           comment

           % pragma double

           in the source file, before any other code. The code resulting
           from a scalar-mode translation does not use the matlib library
           and hence portable across C++ compilers and OS.

           Example

           The following, when compiled with pragma double, shows a x40
           speed-up:

           % pragma double
           function r=isp(x)

           r=0;
           if (x/2)==ceil(x/2) & (x>2) | (x<0) | (x~=ceil(x))
             return;
           end
           q=ceil(sqrt(x));
           for d=3:2:q
             t=x/d;
             if t==ceil(t)
               return
             end
           end
           r=1;
           return


           mat2cpp translator

           mat2cpp translates .m files into C++ files. It is used by
           MATCOM as needed. There is no need to run it directly.

           matcom.ini


                                          12


           matcom.ini file contains the configuration information for
           MATCOM. It is created by the setup program. It may be changed
           by any text editor while keeping the exact format:

           [Settings]
           Compiler=Borland C++
           Version=4.5
           Target=Win32


                                          13

           Limitations


           Matrix size

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

           Graphics

           Handle graphics, Matlab 4 style, are not 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:

           & 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.

           diary

           Not implemented.

           disp

           Only one format (simliar to compact) is used.

           exist

           Not implemented: variables always exist.

           eval, feval

           No 'eval'/'feval' function: No support can be given to those
           (useful!) functions.

           format

           See disp.

           help

           Not implemented.

           isglobal

           Not implemented.

           keyboard

           Not implemented: no interpreter.

           lasterr

           Not implemented.


                                          15

           load

           First variable in file will be loaded, named as the filename.
           Syntax: load filename [-ascii]

           lookfor

           Not implemented.

           pack

           Not implemented.

           save

           One variable will be saved.
           Synatx: save filename varname [-ascii]

           unix

           Not implemented.

           what

           Not implemented.

           which

           Not implemented.

           who

           Not implemented.

           whos

           Not implemented.


                                          16

           Performance


           Matrix mode

           Performance imporvement in matrix depends on the type of
           operations done in the program. Vector operations generally
           shows no improvement. For/while loops and if statements show
           the greatest improvement, achieving upto x5 speed-up.

           Scalar mode

           Programs and functions which comply with scalar mode
           restrictionss shows a speed-ups of x10-x50.

           Tips

           Preallocate variables

           Whenever posssible, preallocate vectors and matrix to final
           size. For example, add

           x=zeros(100,1);

           before

           for i=1:100
             x(i)=rand*i;
           end

           Scalar mode

           Scalar-mode function run at near native C code speed. If your
           function comply with the scalar-mode restrictions, add

           % pragma double

           in the function code to enable scalar mode.

           Use vector operations

           If your function is too complex for scalar mode restrictions,
           vectorize it where possible. Vector operations are very
           efficient compared to looping.

           Inline small functions

           The overhead for calling small (one-two lines) functions can
           exceed the time spent inside the function. Consider writing the
           function in-line.


                                          17

           Other


           Which files needed for the executable created?

           If graphics are not used, only the executable file is needed.

           To support graphics, the Gnuplot files are required:

           o Windows/Win32: wgnuplot.exe, wgnuplot.dll, wgnuplot.mnu
           o  DJGPP: gnuplotx.exe
           o  Unix: gnuplot files

           How to run MATCOM from different directory?

           From this release, MATCOM will work correctly when run from any
           directory.

           Executable size

           The initial overhead of the library is several hundred KB. Add
           to this the created code size.

           MEX files

           MATCOM does not create MEX files since Matlab does not support
           the neccassery programming hooks.

           Where to get DJGPP

           DJGPP can be ftp'ed from
           ftp://omnigate.clarkson.edu/pub/msdos/djgpp
           ftp://ftp.coast.net/SimTel/vendors/djgpp

           Where to get Gnuplot

           Gnuplot can be ftp'ed from
           ftp://ftp.dartmouth.edu/pub/gnuplot
           ftp://ftp.coast.net/SimTel/msdos/plot
           File names are gpt*.

           Where to get MATCOM

           A short article is posted to comp.soft-sys.matlab and
           sci.math.num-analysis when a new release is available.

           MATCOM can be ftp'ed from

           ftp://ftp.funet.fi/pub/sci/math/matlab
           ftp://ftp.eeng.dcu.ie/pub/matlab/MATCOM
           ftp://ftp.technion.ac.il/contrib/mswin

           PC release is named matcom.zip.
           SunOS release is named matcom-sunos.zip.

           WWW home page

           I'm looking for Web server space for a MATCOM home page. If you
           can spare it, please e-mail me.


                                          18

           How to reach me

           e-mail: yak@techunix.technion.ac.il


                                          19

           Appendix A : matlib library


           This section is not needed for the use of MATCOM. C++ knowledge
           is assumed.

           Introduction

           matlib is the C++ library used by MATCOM. It includes matrix,
           file i/o, graphics, string and text i/o functions. matlib is
           supplied for the supported compilers.

           The M Matrix Class

           Most matlib fucntions accept and return matrices. The matrix
           class in matlib is called M. It is a class of full complex
           matricess. Operators are redefined to work correctly on the
           class.

           Features of matlib

           o Portable across the supported OS and compilers
           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: library only 400KB
           o May be freely used

           Short Library Reference

           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.

           Constructors

           The only constructor used in translated programs is

           M var_name(char* var_name, 0.0);

           where var_name is the variable name and 0.0 the initial value.
           The variable name is used when displayed.
           Other constructors are also available:

           M var_name(char* var_name, double real_value, double
           imag_value);
           M var_name(char* var_name, char* text_value);
           M var_name(double real_value);
           M var_name(int number_of_rows, int number_of_cols);


           Class functions

           Selected member functions:

           int rows() - return number of rows
           int cols() - return number of cols


                                          20

           double *addr() - return address of real part
           double *addi() - return address of imag part

           See matlib.h for a full list of member functions.

           Allocation/Deallocation

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

           Calling functions

           Usual C syntax for calling functions:

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

           More than one return values

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

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

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

           InitM() and ExitM()

           Upon entering the program, InitM() must be called. Before
           exiting, call ExitM(). Failure to call these functions will
           result in reduced functionality of matlib.

           Operators

           The <, >, <=, >=, ==, !=, ||, &&, +, -, !, -, *, / operators
           are overloaded for the class M. The equivalent of .* is the
           function dot_mul.

           Matrix functions

           Many mathematical functions are implemented.
           Examples: abs, acos, sin, cos, fix, floor, tril, triu, diag,
           linspace, rot90, size, chol, qr, eig, hess, inv, svd, find.
           Full list is in matlib.h.

           Scalar access functions

           double scalar(M& X) returns real(X(1,1) )
           double scalar(M& X, int idx) returns real(X(idx))
           double scalar(M& X, int row, int col) returns real(X(row, col))

           The scalai functions return the imaginary part when called with
           same syntax.

           setr(M& X, double r) sets real(X(1,1)) to r
           setr(M& X, double r, int idx) sets real(X(idx)) to r
           setr(M& X, double r, int row, int col) sets real(X(row, col))
           to r


                                          21

           The seti functions sets the imaginary part.

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

           Text I/O functions

           clc, disp, home, input, menu, pause are included. The <<
           operator for cout is overloaded to display matrix correctly.
           disp accepts an optional second parameter specifying the output
           stream.

           File I/O functions

           load and save are implemeted but limited - see `Compatibilty'.
           Matrix versions of fopen, fread, fwrite, fclose, ferror,
           fprintf, fseek, frewind, ftell are implemeted.

           Graphics functions

           2D and 3D graphics are supported using high-level functions
           such ad plot, mesh, title.

           Using the library with your programs

           Example1

           The files magic.cpp, magicsum.m and makefile demonstrate how to
           compile and link .m files together with C++ code. To compile
           the example, run BC 4.5 make. To run it, run magic.exe.

           Example2

           The source uselib.cpp:

           #include "matlib.h"

           main() {
           // solve x-cos(x)==0 using 4 iterations
             M x("x",1.0);
             initM();

             cout<<x;
             x=cos(x);
             x=cos(x);
             x=cos(x);
             x=cos(x);
             cout<<x;

             exitM();
             return 0;
           }

           is compiled using Borland C++ 4.x with the command

           bcc -w- -x -ml -A -WE mlibbc4w.lib uselib.cpp

           Creates uselib.exe.

           Compiler switches


                                          22


           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 mlibbc4w.lib
           Meaning: No warnings, no exceptions, ANSI mode, Windows app,
           Link with mlibbc4w.lib.

           Visual C++
           Flags: /f /G2 /YX /Mq /AL
           Meaning: Fast compiler,  286 code, QuickWin support, Large
           memory model.

           DJGPP
           Flags: mlibgnu.a -lgpp -lm
           Meaing: link with matlib, C++ and math libraries.

           Gnu C++/SunOS
           Flags: mlibgnu.a -lg++ -lm
           Meaing: link with matlib, C++ and math libraries.


                                          23

           Appendix B : Files included


           PC Release

           readme.1st, file_id.diz - Documents
           matlib.def - Define file for Windows applications
           vbrun300.dll - Support file for setup (not in SimTel release)
           mat2cpp.exe - mat2cpp translator
           matcom.exe - matcom project manager
           setup.exe - configuration of MATCOM (Windows program)
           wcommand.exe, wcommand.pif - Helper files
           matlib.h - Header file of matlib
           mlibbc3w.lib - matlib for Borland C++ 3.1/Windows
           mlibbc4w.lib - matlib for Borland C++ 4,4.5/Windows
           mlibbc32.lib - matlib for Borland C++ 4,4.5/Win32
           mlibvc1w.lib - matlib for Visual C++/Windows
           mlibgnu.a - matlib for DJGPP/GO32
           *.m, *.cpp, makefile - sample files
           matcom.doc - this document in Word 6 format
           matcom.wri - this document in Write format
           matcom.txt - this document in ASCII format

           SunOS Release

           readme.1st, file_id.diz - Documents
           mat2cpp - mat2cpp translator
           matcom - matcom project manager
           matlib.h - Header file of matlib
           mlibgnu.a - matlib for gcc
           *.m, *.cpp, makefile - sample files
           matcom.txt - this document in ASCII format