Matlab is a great programming language/environment because of its ease of use, great visualization, and rapid prototyping abilities. Raw speed is not one of its strong suits. MEX (Matlab Executables) are the answer. These functions allow you to program in C or C++ (ultra fast languages), but be able to call and use them from Matlab programs. This post is a short intro to mex files which should get you up and running.

What This Post Teaches

In this post, I show how to create a mex file, how to set up inputs and outputs, how to get access to Matlab objects, and how to manipulate them. I also give a skeleton mex program that might be helpful. There is a lot more to learn, and I’d refer you to the mex manual regardless.

What You Should Already Know

I’m going to assume you already know how to program in C, and already know how to program in Matlab. This post does not teach either language, but will show you how to use them together to get the best of both worlds.

Hello world!

Lets get started. First, type:
>>mex -setup
Then go through the menus to select a compiler that you have installed on your system. I use gcc on linux, visual studios on windows, and mexopts on mac. Now, create a file called, “helloworld.cpp” and we’ll start coding. In this first example, pay attention to the signature of the mexFunction. This signature is always the same.


#include <math.h>
#include <matrix.h>
#include <mex.h>

void mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[])
{
  mexPrintf("Hello World!\n");
}

Save the file, and in the Matlab prompt type,
>>mex helloworld.cpp
If all goes well, you should get the following when you run helloworld:
>>helloworld
>>Hello World!

Setting Up Inputs and Outputs

Now that we have a working program, the next step is to get inputs and outputs going so we can do something useful. The mxArray pointers plhs and prhs represent a pointer to the left hand sside and a pointer to the right hand sside respectively. The left hand side are the outputs and the right hand side are the inputs.

put something like this in the top of mexFunction:


  //declare variables
  mxArray *a_in_m, *b_in_m, *c_out_m, *d_out_m;
  const mwSize *dims;
  double *a, *b, *c, *d;
  int dimx, dimy, numdims;
  
  //associate inputs
  a_in_m = mxDuplicateArray(prhs[0]);
  b_in_m = mxDuplicateArray(prhs[1]);
  
  //figure out dimensions
  dims = mxGetDimensions(prhs[0]);
  numdims = mxGetNumberOfDimensions(prhs[0]);
  dimy = (int)dims[0]; dimx = (int)dims[1];
  
  //associate outputs
  c_out_m = plhs[0] = mxCreateDoubleMatrix(dimy,dimx,mxREAL);
  d_out_m = plhs[1] = mxCreateDoubleMatrix(dimy,dimx,mxREAL);

Accessing and Manipulating Matlab Objects

To access the variables, you need to associate a pointer to the data in the mxArray. Once you do this, accessing the variables is very simple.


  a = mxGetPr(a_in_m);
  b = mxGetPr(b_in_m);
  c = mxGetPr(c_out_m);
  d = mxGetPr(d_out_m);

Now it is possible to access the arrays with standard C or C++ [] notation. There are three important things to remember though:

  • You use 0-based indexing as always in C
  • You still use column-first indexing like in Matlab, though
  • To access the arrays, you use linear indexing (you can’t use [x][y], you have to use [y+x*dimy]

With those three things in mind, go crazy. You can use standard C libraries (as long as you include them). You can use for loops as much as your heart desires, and your code will be much, much faster than its Matlab equivalent.

Downloads

Download this starter file (demo.cpp). This has all of the features discussed in this post, and should be a good primer for any mex function. Give it a try. Tell me what you think, and let me know if any improvements are needed.

demo.cpp

To run the demo, download the .cpp file, then at the prompt run:

  >>mex demo.cpp
  >>a = round(rand(2)*10)
  >>b = round(rand(2)*10)
  >>[c,d] = demo(a,b)

38 thoughts on “A Short MEX Tutorial and Demo

  1. Thank you for your short MEX tutorial

    If I have 10 file.c connect between them, what will be written in the MATLAB command to compile the file that I want to execute.
    for example for one file you have written “mex demo.cpp”

    Thank you

  2. im using ubuntu 9.04 jaunty. gcc only failed to compile the *.cpp because it needs g++ compiler. so i installed the compiler and it worked well. thx

  3. Hi lankton:
    Your briefly written tutorial is very helpful, but I believe that you had missed something: “Free up the dynamically located memory.” which is:
    mxDestroyArray(a_in_m);
    mxDestroyArray(b_in_m);

  4. @Dongcai su
    Great addition.
    mxFree is used in conjunction with mxCalloc
    mxDestroyArray is used in conjunction with Array objects such as those created by mxCreateDoubleArray.

  5. Hi Shawn, Why if Matlab stores matrices as column major is the ‘linear’ scheme to address specific values of a matrix in row major fashion; e.g. [x][y], you have to use [y+x*dimy], assuming x = Nrows and y = Ncols.

  6. I have written a code to add two numbers in mex. but the code complies successfully but cannot run it can some help me
    thanks in regard

    #include
    #include “mex.h”
    #define a_IN prhs[0]
    #define b_IN prhs[1]
    #define c_OUT plhs[0]
    void mexFunction( int nlhs, mxArray *plhs[],
    int nrhs, const mxArray*prhs[] )
    {
    double *a,*b,*c;
    a = mxGetPr(a_IN);
    b = mxGetPr(b_IN);
    c = mxGetPr(c_OUT);
    *c = *a + *b;
    return;
    }

  7. Though matlab successfully done the mex setup still there an error appears
    ??? Error using ==> mex at 208
    Unable to complete successfully.

  8. The URL to the mex manual is broken. Can you re-link to a correct URL if you know one? Else, do you have a local copy that you can share? Will just save a quick Google. :)

  9. It was excellent demo.Just give details for running mex file.I struggled lot gor first time.
    procesure:
    1)first save demo.cpp file in current working directory as we save images.
    2)type mex -setup on MATLAB command prompt.
    3)follow the procedure and select your version(like visual studio)
    4)then type, mex demo.cpp ans press enter
    5)your file will compile now.
    6)now give input like a=[1 2 3;4 5 6;7 8 9]; and b=[1 2 3;4 5 6;7 8 9];
    7)type [c d]=demo(a,b) and see magic of SHAWN.
    Thanks a lot SHAWN again.

  10. >> tic; [c,d] = helloworld(a,b); toc
    element[0][0] = 8.000000
    element[1][0] = 9.000000
    element[0][1] = 1.000000
    element[1][1] = 9.000000
    Elapsed time is 0.000605 seconds.
    >> tic; [c,d] = helloworld_m(a,b); toc
    element[1][1] = 8
    element[2][1] = 9
    element[1][2] = 1
    element[2][2] = 9
    Elapsed time is 0.002685 seconds.

    Takes 22.53% of the time spent with the same code in a .m function. Definitely gonna use it from now on.

  11. I ve been trying the given code but it compiles and nothing happens .

    >>demo.cpp
    >>

    other program
    >>helloworld.cpp
    >>

    I tried again and again but no output.

  12. Hello Sir,I have a mex function(FMReDistSDF_mex.c)
    I have to compile this and use it as matlab function in another program.I am nt exactly getting the steps to do dis..plz help me out..

  13. Hello Shawn, how to find an array’s size inside Mex. i have something like i add some value into an array if a criteria is fulfilled.
    Myarray is int array
    i tried mxGetNumberOfElements(Myarray) but i get an error like
    “assignment of pointer to const incomplete struct mxArray_tag defined at line number to pointer to int”

  14. Thank you very much for all the helps… I’d like to know how to call in MatLab a *.dll library written and compiled in C++ and another in java. Thanks.

  15. Is there any way to connect Keil uvision5 with MATLAB directly. i want to get input from Keil to MATLAB.
    Thanks in advance..

  16. Hi, thanks for the tutorial ! . Any idea why my function gets stuck ? It seems to be the same issue that in the following link, but I am using mxDestroyArray, and memory doesn’t seems to free. Cheers.

    http://www.mathworks.com/matlabcentral/newsreader/view_thread/241020

    #include
    #include
    #include “mex.h”
    #include “matrix.h”
    #include

    void mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[])
    {
    mxArray *x_in_m,*y_in_m, *time_out_m ;
    double *x, *y,*time ;
    int N ,i ;
    x_in_m = mxDuplicateArray(prhs[0]);
    y_in_m = mxDuplicateArray(prhs[1]);
    x = mxGetPr(x_in_m);
    y = mxGetPr(y_in_m);
    N = mxGetNumberOfElements(prhs[0]);
    time_out_m = plhs[0] = mxCreateDoubleMatrix(N,1,mxREAL);
    time = mxGetPr(time_out_m);
    for(i = 0; i < N ; i ++ ) { time[i] = (double)i;}
    mxDestroyArray(x_in_m);
    mxDestroyArray(y_in_m);
    mxDestroyArray(time_out_m);
    return;
    }

  17. Hello,
    I need to call from Matlab a C++ method that receives as input a C++ object, specifically, I’ve got a C++ code that uses the ITK library (in C++) and receives as input an itk::Image (N-dimensional) object.
    All the code I’ve seen so far passes standard C typed arguments from Matlab to C++ and viceversa, so is it possible to do what I have proposed earlier, that is, convert Matlab object (e.g. Matlab image) to C++ objects?
    Thank you very much.
    Kind regards.
    /Paco

  18. Hi
    Shawn – I’m a real newcomer to this but I have a problem. I have some C code which compiles fine with the gcc compiler using
    gcc -lstdc++ program.c -o program
    But when I use mex I can’t see how to link in the c++ library
    Any help much apreciated
    Thaknks
    Terry

Leave a Reply

Your email address will not be published.