readme

student teacher and proferssor llove this project,this a very important exmple

README file for matlab2fmex.m

CONTENTS:
 0. DISCLAIMER
 1. OBJECTIVE
 2. MOTIVATION
 3. BUG REPORTS and WISH LIST
 4. MATLAB2FMEX CAPABILITIES
 5. MATLAB2FMEX LIMITATIONS
 6. HOW TO US MATLAB2FMEX
 7. EXAMPLES
 8. REVISION HISTORY

0. DISCLAIMER: Matlab is a trademark of the Mathworks company and is
   owned by them. The author makes no guarantee express or implied of
   any kind as to the applicability, usefulness, efficacy,
   bug-freeness, or the accuracy of the ensuing results from using
   matlab2fmex.

   The author bears no responsibility for any unwanted effect
   resulting from the use of this program. The author is not
   affiliated with the Mathworks.  The source code is given in full in
   the hopes that it will prove useful. Devlopment is done through
   sourceforge at matlab2fmex.sourceforge.net.

1. OBJECTIVE: matlab2fmex.m is a small translator which converts 
   numerical Matlab m-files to Fortran90 mex files and then compiles 
   with Matlab's mex.

2. MOTIVATION: 
   1) Matlab is becoming ubiquitous in the engineering and scientific
communities for its ease of use coupled with its powerful
libraries. Yet the biggest disadvantage to Matlab is that it is
__slow__ when compared to optimized and compiled languages such as C
and especially Fortran. With the recent 6.5+ release, Matlab execution
speed has been improved, but compiled fortran is almost always at
least a few times faster.

   2) While Matlab provides a built-in compiler (mcc), this, too, seems slow and in fact
many times produces executables whose performance is similar or worse to their parent
m-file (see examples below). If one is willing to forgo some of the fancier things of
Matlab like cells, structs, variable retyping, variable resizing, etc., while still
maintaining Matlab's algorithm devolpment environment, then significant speedups can be
achieved. 
          The intent of matlab2fmex is to retain the advantages of both languages: use
Matlab for development and debugging, then convert the numerically intensive routines to
mex files for speed.

   3) Fortran90/95/2000/etc syntax is growing closer to Matlab's and
vice versa.

3. BUG REPORTS and WISH LIST:
   For all bug reports, a wish list for matlab2fmex, and suggestions,
   see http://matlab2fmex.sourceforge.net/
   or email [e-mail]
      Also see hints file accompanying this distribution for other tips.

   Even though matlab2fmex is and always will be open and free
   (under GPL) for the using, I would like to ask that those who find
   it useful and are able to make a contribution to please do
   so commesurate with use ***. These can be made via my PayPal at the 
   sourceforge project webpage.

   *** Specifically, companies with employees who use matlab2fmex
   should consider a contribution.

4. MATLAB2FMEX CAPABILITIES: matlab2fmex is aimed at converting
   computationally intensive numerical functions to Fortran90
   mex-files. As such, only basic data types and constructions are
   recommended. matlab2fmex can handle:

   integer, real, and complex scalars and 2-D arrays
   loop and branch constructs
   array indexing
   mathematical operations
   simple math functions using Fortran intrinsics, e.g. trig functions etc. 
   Many Matlab functions using Fortran90 generic interfaces
   Most other Matlab functions by calling Matlab at execution time. 
     (callback are slow, however)
   variable size inputs and outputs
     (see below for restrictions***)
   logical operator conversion
   multiple functions (helper functions => Fortran subroutines)
   Integral colon expressions __must have brackets [ and ] around them__

5. MATLAB2FMEX LIMITATIONS: matlab2fmex was not made for replacing
   Matlab's extensive non-numerical capabilities. Thus, functionality
   for GUIs, debugging, java, objects, etc. are not included.  As a
   general rule, only core numeric code should be attempted to be
   converted.  Things to be avoided:

   cells
   structs
   strings (exception: in disp() and error() statements)
   sparse data
   uintxx
   intxx
   objects
   the same uppercase and lowercase variable names 
       (e.g. both INDEX and index as variables)
   inline functions
   java anything
   anything but 2-D doubles (but can be real or complex)
   dynamic array resizing for local variables
     (see below for restrictions***)
   *.m-file function conversion with no outputs
   statements separated by commas instead of semicolons
   loading and saving *.mat files (on wish list)

*** Inputs and outputs may change in size, but variables local to the
    m-file may not _unless_ their dimension(s) are the same size as an
    input variables' dimension(s). No variable is allowed to change in
    size after function instantiation.

6. HOW TO USE MATLAB2FMEX: There are 2 steps required to convert a
     Matlab m-file(s) to a mex-able Fortran90 file.  

     1) matlab2fmex needs to find a *.mat data file which contains a
     typical workspace generated by the function which is being
     converted. This is easily constructed by inserting a keyboard
     command at the end of the *.m file, then, at the k>> prompt
     simply type "save *" where * is the name of the *.m file without
     the .m extension.  matlab2fmex uses this workspace to make
     decisions which depend on the variables in the *.m file, such as
     real or complex. Accordingly, if an variable may be complex, it
     is best to cause that variable to be complex when the workspace
     is saved so that the *.f90 file will be as robust as possible. 
        When converting multiple *.m files (a main function and helper
     functions), a separate *.mat file must exist for each function.
        Alternatively, you can use matlab2fmex_save to save a typical
     workspace file. Simply execute:
     matlab2fmex_save('function_call_string'); and the workspace file
     will be saved for you. (See below for some examples and further 
     explanation.)

     2) The second step is to call matlab2fmex. The format is the
     following: 
	
	matlab2fmex({'filename1' 'filename2' ...},{[compiler
     flags for main routine (filename1)],[compiler flags for
     subroutine 1 (filename2)],...}); 
     
     The result will be a fortran mex file filename1.f90 along with the
     compiled mex function filename1.mex. This mex function should be
     callable with the same syntax as the original function.

When sizing output and local variables, the converter looks for any
input variable dimension which happens to be the same as each output
or local variable dimension. That dimension of the local variable is
then assigned that dimension of that input variable. Upon failing to
find an input variable with the same dimensional size, the converter
declares that dimension of the local variable to be the _static_ size
it is is the saved workspace.

There are a few parameters which the user can specify as well:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
want_kb=0;%want_kb --> 0 Do not stop after each step, compile file. (default)
                  %--> 1 Enter Matlab keyboard after each step.(for debugging)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
want_ss=0;%want_ss%-->-1 No subscript vectorization. (for mostly scalar operations)
                  %--> 0 Relaxed subscript interpreting. (default)
                  %--> 1 Stricter subscripting (slower, for variable subscripts)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
want_op=0;%want_op%-->-1 No operator replacement (use when want_ss=-1)
                  %--> 0 Don't replace +, -, or scalar * and / operators. (default)
                  %--> 1 Replace all math operators with interface calls. (slower)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
want_fb=0;%want_fb --> 0 Don't display progress throughout compilation. (default)
                  %--> 1 Display feedback information. (potentially annoying)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
want_ct=1;%want_ct --> 0 Don't mex *.f90 upon completion.
                  %--> 1 mex the resulting *.f90 file. (default)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 want_0=0;%want_mf --> 0 Don't zero all vars
                  %--> 1 Set all vars = 0 before computational routine
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
want_br=0;%want_br --> 0 Use (/ and /) instead of [ and ] (all Fortran 90's)
                  %--> 1 Use [ and ] (Some Fortran 90's)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
want_sb=0;%want_sb --> 0 Convert as a full mex-file
                  %--> 1 Convert as a subroutine (sets want_ct to 0).
		  %--> 2 Convert as a function (one output, sets want_ct to 0).
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
want_in=1;%want_in --> 0 Don't allow local vars to be integers
                  %--> 1 Allow local vars to be integers (default)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
want_cs=0;%want_in --> 0 Assume all sqrt's are of real, positive numbers
                  %--> 1 Assume all sqrt's are complex
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Shown here are the default flag settings.

Note: Sometimes it is useful to modify the resulting *.f90 to improve
performance.

Another Note: In your mexopts.sh, you must set the default to double
precision or 8 bytes for 1 real. Check your Fortran90 compiler flags
for how to do this and add this option to the appropriate 'FFLAGS=' in
mexopts.sh. Important: do not set integers to double size, only real
and complex data types.

7. EXAMPLES: A few examples from the ~MATLAB/extern/examples/compiler/
   from your Matlab distribution with performance comparisons along
   with some other examples. The following computation times are from
   a PC running RedHat Linux 9.0 with 1.5GB of RAM and the
   Intel Fortran90 compiler.

All of the following examples can be run by running the script TESTING
from the examples directory in the full distribution. If you do not
have the Matlab compiler, set the have_mcc flag in the TESTING script
to 0.

These examples were run under 6.5.1. 

Further examples adapted from the Falcon/Majic project:
http://polaris.cs.uiuc.edu/~galmasi/majic/majic.html can be run by
executing the TESTING_uoi.m script in the testsuite_m2f directory. A
bar graph comparing execution times will result from the tests.

First example:

Original file myfunc.m:
function z = myfunc(x) 
% Doc example.  Chapter 4.
% $Revision: 1.1 $
temp1 = x .* 10 .* sin(x); 
z = round(temp1);

Use matlab2fmex_save (see below) to save a sample workspace:
matlab2fmex_save('z=myfunc(rand(3,3));');

When running native matlab:
>> x=rand(2000);
>> t=cputime;z=myfunc(x);cputime-t
ans =
   1.25

Evem when we compile using mcc, the performance does not improve:
>> mcc -x myfunc.m
>> t=cputime;z=myfunc(x);cputime-t
ans =
   1.25999999999999
>>

Now convert it to a mex-file using matlab2fmex:
>> matlab2fmex('myfunc');
Converting --- myfunc.m  ==>  myfunc.f90  ==>  myfunc.mex

Original:
  function z = myfunc(x) 
  temp1 = x .* 10 .* sin(x);
  z = round(temp1);
 
  putting decimal points etc. ....................... m finished 
  fixing bracketed assignments ...................... a finished 
  fixing bracketed assignments II ................... t finished 
  operator changeover ............................... l finished 
  making 2 subscripts ............................... a finished 
  fixing logical operators .......................... b finished 
  subscript vectorizing ............................. 2 finished 
  fixing if, for, etc keywords ...................... f finished 
  fixing colon expressons ........................... m finished 
  performing word conversion ........................ e finished 
  fixing assignments ................................ x finished 
     2 lines
  Setting the size of output var z equal to the input var x.
  Setting the size of local var temp1 equal to the size of input var x.

Finished writing myfunc.f90:
  temp1 = x_f * 10.0 * sin(x_f);
  z_f = ANInt(temp1);
 
Starting compilation of myfunc.f90
Calling mex to compile the output at myfunc.f90
 ==> mex -v myfunc.f90  
/mit/matlab_v6.5.1/distrib
-L/mit/matlab_v6.5.1/distrib/bin/Undetermined -lmx -lmex -lmat
/mit/matlab_v6.5.1/distrib
-L/mit/matlab_v6.5.1/distrib/bin/glnx86 -lmx -lmex -lmat
-> mexopts.sh sourced from directory (DIR = $HOME/.matlab/R13)
>> 

 
And myfunc.f is:
      temp1 = x_f * 10.0 * sin(x_f)
      z_f = ANInt(temp1)
(with appropriate supporting gateway and subroutine code before and after)

now execute the same call to myfunc:
>> t=cputime;z=myfunc(x);cputime-t
ans =
   0.42