



























                                        MATCOM

                            A Matlab(R) to C++ translator

                                  March 1996 release


                                          2



           TABLE OF CONTENTS




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


           Legal stuff - MUST READ ......................................3

           Copyright ....................................................3
           Disclaimer ...................................................3
           Trademarks ...................................................3

           What is MATCOM? ..............................................4

           Introduction .................................................4
           Features .....................................................4
           Release notes ................................................4
           Thanks .......................................................4

           Requirements .................................................5


           Installation .................................................6

           MATCOM LIBRARY Installation ..................................6
           Upgrade notes ................................................6
           PC Release ...................................................6
           Unix Release .................................................6
           Testing the installation .....................................7
           Runtime troubleshooting ......................................8
           Compiling MATCOM for other systems ...........................9

           Compiling Matlab files ......................................10

           MATCOM project manager ......................................10
           The mpath file ..............................................10
           MATCOM Switches .............................................11
           Fast code - D Mode ..........................................12
           matcom.ini ..................................................13
           Examples ....................................................14

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


           Performance .................................................17

           Matrix mode .................................................17
           D mode ......................................................17
           Tips ........................................................17

           Compatibility ...............................................19


           Runtime error messages ......................................19


                                          3

           Other .......................................................20

           Which files needed for the executable created? ..............20
           How to run MATCOM from different directory? .................20
           Including C/C++ source inside .m files ......................20
           matcom.win vs. matcom.dos ...................................21
           Executable size .............................................21
           MEX files ...................................................21
           Where is ... ................................................21
           Bug reports .................................................21
           Technical Support ...........................................22


                                          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 may be distributed for a nominal distribution
           fee and may be included in a CD-ROM collection. MATCOM may not
           be re-selled or included with other products except:

           APPLICATIONS, EXECUTABLES, OBJECTS, LIBRARIES, SOURCE CREATED
           WITH MATCOM INCLUDING THE MATLIB 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 YOU AGREE TO ALL OF THE ABOVE.


                                          5

           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) language translator to the C++ MATCOM
           LIBRARY matrix class and a project manager.

           Features

           o Highly compatible with the Matlab 4 language dialect.
           o The translator creates C++ code from Matlab code, than
           compiles it.
           o C++ functions can be conveniently hand-coded using Matlab-
           like syntax.
           o Matlab algorithms may be included in C++ projects using auto
           translation.
           o All code and binaries produced are free for any purpose.

           Release notes

           This is the fifth public release for PC, third for Unix. Your
           comments, wishes and bug-reports are most welcome.

            Thanks

           My thanks to all who helped, the list now is too large to
           include (and un-managable).


                                          6

           Requirements


           MATCOM requirements are detailed in matlib.doc.


                                          7

           Installation


           MATCOM LIBRARY Installation

           First, follow the MATCOM LIBRARY installation instructions in
           matlib.doc.

           Upgrade notes

           o All C++ source from previous release must be retranslated (-
           force option) and recompiled.
           o Previous objects will not link correctly with the new matlib
           library.
           o Do not mix MATCOM versions or generated code

           PC Release

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

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

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

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

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

           6. Installation is complete. See `Compiling Matlab Files'.

           Unix Release

           MATCOM is supplied in source form which must be compiled.

           Compiling MATCOM

           1. Find the makefile name using the procedure outlined in
           matlib.doc.

           2. Run the selected makefile using the install script:

           sh install selected_makefile_name

           (with .mak extension)

           3. All of the MATCOM files 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.


                                          8

           Configuring MATCOM

           1. Run matcom.

           2. Select C++ compiler.

           3. Answer if Matlab is installed.

           4. MATCOM runs Matlab with a short script file.

           5. MATCOM compiles the joinug.m example.

           6. You are asked to join the the MATCOM Users Group by e-mail.
           Join!

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

           8. matcom directory may be added to the path.  In this case,
           set the matcom enviroment variable to that directory.
           Example:

           setenv matcom ~/work/matcom

           9. When testing matcom, the filename test.m and try.m should be
           avoided, as test is a unix command and try is a reserved C++
           keyword.

           Testing the installation

           1. Run matcom.

           matcom

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

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

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

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

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


                                          9

           Runtime troubleshooting

           Low DOS memory?

           C++ tools require lots of memory. Try to maximize the available
           low memory: 450K is needed for translating and compiling large
           .m files. If more low memory  can not be obtained, try one of
           those solutions:

           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.

           ``Unknown token'', ^M in output

           If the translator fails on ``Unknown token'' error and you see
           ^M in the output C++ file, the input file was a DOS text file.
           Most C libraries on Unix can not read such files. Use a
           translating tool
           such as dos2unix to fix the input files.

           startup.m not found

           The file startup.m was called but not found. Create an empty
           startup.m file.

           Too much global data

           Use a 32 bit compiler instead of a 16 bit one.

           Compiler not found with Turbo C++ 3.1

           Copy the file c:\bc\bin\tcc.exe to bcc.exe.

           ld: Unresolved: s_wsfe, s_stop, ... when using BLAS libraries

           See the compilers switches section in matlib.doc. Add -lftn to
           the LDFLGAS entry in matcom.ini. Example:

           LDFLAGS= -lg++ -lmlib -lblas -lftn -lm


                                          10

           Compiling MATCOM for other systems

           MATCOM 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 to another platform/OS/compiler, please contact
           me.


                                          11

           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.

           The matcom command may be run from the system or Matlab command
           line.

           Only script files or functions which take no arguments may be
           given as a main file.

           The mpath file

           The mpath file (not mpath.m!), 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 mpath file may be edited with any text editor such as
           Windows notepad or Unix vi. Additional mpath file may be
           specified by setting the mpath enviroment variable.
           Example:

           setenv mpath ~/mpath-sig


                                          12

           MATCOM Switches

           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.
           From the command line, add the switch -g to create the symbolic
           information.

           Reconfiguring

           Run:

           matcom -c

           Translation only

           The -x switch causes matcom to translate the input files
           without compiling.

           Example:

           matcom eigface.m -x

           Creating makefiles

           Matcom can create makefiles instead of compiling. This switch
           can be used in low-memory situations. Use the -make switch.

           Example:

           matcom filter14.m -make
           make -f filter14.mak

           In order to use the created makefile with WATCOM compiler, use
           the /u flag:

           wmake /u /f filter14.mak

           mat2cpp mode

           The -mat2cpp switch forces matcom to translate one file only.

           Force retranslation

           Retranslation can be forced by using the -force switch.

           Quiet operation

           MATCOM will not display its logo if the -nologo switch is
           specified.

           Fast code - D Mode

           A special scalar mode can be used with functions adhering to:

           o All indexing returns a real scalar
           o No growing matrices


                                          13


           If you are not sure if the function complies with D mode, try
           it. Failed compliation with D mode when it was successful
           without means the function can not work with D mode.

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

           %MATCOM% Dmode

           in the source file as the first line.

           The created code will execute much faster.

           Example - isp.m

           The following, when compiled with D mode, shows a x40 speed-up:

           %MATCOM% Dmode

           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

           matcom.ini

           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
           Matlab=d:\matlab
           CPPFLAGS= -w -L./ -I./
           LDFLAGS= -lmlib -lm

           You may keep various configurations under different names. To
           use another configuration, copy the ini file over matcom.ini.
           CPPFLAGS and LDFLAGS are used only with Unix compilers ; you
           may modify those to tailor  MATCOM operation for specific
           configuration, for example, a shared library implementation.


                                          14

           Examples

           D mode - speed.m

           Run

           matcom speed.m

           And then

           speed

           Gnuplot must be installed to see the plot.

           Debug mode

           MATCOM example.m -g

           The program may be debugged.

           Using Borland C++ :

           tdw example.exe

           Using gcc:

           gdb example

           feval usage - fmaxtest.m

           This script file calls the fmax.m function, demonstrating how
           feval can be used. The function name fmax was added to the end
           of the matcom.rsv file.

           image - mandel.m

           The mandel script generates a Mandelbrot fractal and displays
           it by the use of an external viewer.

           sound - modem.m

           modem.m creates a Bell103 (300 baud) modem sound and plays it
           by the means of an external player.

           ulam.m

           ulam.m and hailpath.m let you test "Ulam's Conjecture", see the
           files for details.


                                          15

           Limitations


           The library limitations are detailed in matlib.doc, limitations
           section.


                                          16

           Performance


           Matrix mode

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

           D mode

           Programs and functions which comply with D mode restrictions
           show 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

           D mode

           If your function comply with the D mode restrictions, add

           %MATCOM% Dmode

           in the function code to enable D mode.

           Use vector operations

           If your function is too complex for scalar mode restrictions,
           vectorize it where possible. Vector operations are more
           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.

           Integrate C++ code

           Critical, small functions may be coded in C++. This will
           achieve speed benefit without the need to code the whole
           program in C++.

           Hand optimization of generated code

           If matrix index always returns a real scalar, you can use the
           .r( ) access function documented in matlib.doc.


                                          17


           Real scalar variable declaration may be replaced by
           D(0,0,''variable_name''). The D datatype is scalar-only real
           variable.


                                          18

           Compatibility


           Please see the compatibility section in matlib.doc.



           Runtime error messages


           Please see the runtime error messages section in matlib.doc.


                                          19

           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

           To use the sound command, a .wav file player is needed.

           To use the image command, a .bmp file viewer is needed.

           How to run MATCOM from different directory?

           MATCOM will work correctly when run from any directory, after
           setting the MATCOM enviroment variable.

           Including C/C++ source inside .m files

           C/C++ source may be included inside .m files by prepending it
           with %MATCOM% C=.
           Example (samp_dsp.m):

           L=1024; % 1024 samples
           a=zeros(L,1);
           %MATCOM% C=for (int j=1;j<=1000;j++) {
           %MATCOM% C=  a.r(j)=dsp_read();
           %MATCOM% C=}
           plot(abs(fft(a)))

           Translate this example by:

           matcom samp_dsp /x


                                          20

           matcom.win vs. matcom.dos

           The project manager is supplied with two versions:

           o a DOS executable: matcom.dos
           o an Windows executable: matcom.win

           The setup program selects the most appropriate compiler for the
           compiler, renaming it to matcom.exe.
           The windows version does not suffer from the 640K limitation.
           However, it has to spawn a dos session each time a dos-based
           compiler is run, making it slower for those compilers. If  the
           windows version of the matocm project manager is used the
           following procedure is needed:

           1. Load the PIF editor.
           2. Open the file _default.pif from the \windows directory.
           3. Change The KB Limit value in the XMS Memory: line to 8192.
           4. Save the modified pif file

           If the file _default.pif was not found on a Windows 95 system,
           do not perform the change. If the file was not found on a
           Windows 3.1/Windows NT system, copy the file dosprmpt.pif to
           _default.pif and then perform the change.

           When matcom.win finish running, the program window will stay
           open until closed.

           Executable size

           The initial overhead of the library is 250KB-1.5MB (platfrom
           depended). Add to this the created code size.

           MEX files

           MATCOM does not create MEX files yet.

           Where is ...

           Please see the file where-is.txt.

           Bug reports

           Bug reports should include the following information:

           o MATCOM 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'.

           Technical Support

           Use the e-mail:


                                          21

           yak@techunix.technion.ac.il