Mex for Matlab

When to use Mex?

One of Matlab's best assets is that you can quickly produce code for linear algebraic operations. Some of the features that make Matlab good for quick prototyping make some operations slow. This leads to one reason to use Mex to import C, C++, or Fortran:

Use Mex if your algorithm requires that you write a lot of loops

However, before you start writing compiled code, think hard about whether you can re-conceive your problem as a block-matrix problem and use built-in matrix methods. These have been optimized and tested.

Use Mex to import legacy code in a compiled language

Matlab's data import/export and visualization functions make it a great scripting language in some instances.

Getting started in Mex

These notes draw from the Matlab help documents.

The Mex compiler comes with header files and libraries that define functions to transfer data from the Matlab environment to C. Every mex program must implement a special function:

#import <mex.h>

void mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[]){
  // do stuff!
}

Think of mexFunction like "main". It takes two sets of arguments. nrhs and prhs are the number of input arguments (right hand arguments) and a set of pointers to the inputs as arrays. nlhs and plhs are the output arguments.

Get your data

There are special functions defined in mex.h to get data. In this example, we get a pointer to our input and output:

void mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[]){

      int i,j,m,n;
      double *dataIn, *dataOut;
      if (nrhs != nlhs)
              mexErrMsgTxt("The number of inputs and outputs had better be the same!");

      /* NOTE: if the last line was run, this function has returned. */

      for (i=0; i < nrhs; i++){ /* for each input */
              m = mxGetM(prhs[i]); /* get size 1 */
              n = mxGetN(prhs[i]); /* get size 2 */

              plhs[i] = mxCreateDoubleMatrix(m,n,mxREAL); /* create an m by n real matrix. */
              dataIn = mxGetPr(prhs[i]); /* pointer to input. */
              dataOut = mxGetPr(plhs[i]); /* pointer to output (for convenience) */
              for (j = 0; j < m*n; j++)
                      dataOut[j] = 2 * dataIn[j];
      }
}

mxGetN and mxGetM These functions take a pointer to a Matlab array object and return the row and column height, respectively.

mxGetPr returns a pointer to the data in the Matlab array.

mxCreateDoubleMatrix(m,n,<type>) returns a double matrix with two sizes. This is the primary way you create data. Remember: output arrays must be initialized like this!

Other important functions:

mxMalloc, mxCalloc, mxFree, mexMakeMemoryPersistent, mexAtExit, mxDestroyArray, memcpy In mex, you should let Matlab handle memory management. Anything you alloc in the mex environment exists on Matlab's actively managed heap. By using mxMalloc, ect., you alert Matlab' memory management system to the existence of your object.

Compile

You compile mex codes in the Matlab environment by typing

mex mexCopy.c

at the command line. If there are multiple files or libraries, list them all on the same line.

For more information...

For much more information about using Mex on Matlab, see the user guide at http://www.mathworks.com/support/tech-notes/1600/1605.html