MATLAB MEX-files

• Download source files - 4.65 Kb
• Download demo project - 55.3 Kb

Introduction

MATLAB is a powerful tool for engineering purposes but because of its nature, is very slow in executing functions that take a long time to execute.

For solving this problem, Mathworks provides a toolbox to compile m-files to executable ones. For this reason you can write a script and compile it to an executable with exe extension. But what about functions? Functions could be compiled to other executables called MEX-files. MEX-files in Microsoft Windows have dll extension. Therefore if you have a function like ComputePrimes that computes prime numbers and store them in a matrix, you can compile it to ComputePrimes.dll. Now MATLAB executes this function in less time. MEX-files in other operating systems have other extensions.

As you know, DLL is an abbreviation of dynamic link library and contains variables, functions and classes that are dynamically loaded by the operating system or in this situation by MATLAB. Because they are compiled, they are executed very fast.

Creating MATLAB MEX-file

To create executable files from m-files, you can use MCC. MCC is MATLAB to C/C++ compiler. It can compile m-files to executable files with exe or dll extension. For example:

Make a C translation and a MEX-file for myfun.m:

mcc -x myfun

Make a C translation and a stand-alone executable for myfun.m:

mcc -m myfun

Make a C++ translation and a stand-alone executable for myfun.m:

mcc -p myfun

Make a C MEX wrapper file from myfun1.m and myfun2.m:

mcc -W mex -L C libmatlbmx.mlib myfun1 myfun2

Make a C translation and a stand-alone executable from myfun1.m and myfun2.m (using one MCC call):

mcc -m myfun1 myfun2

But there is another way to create MEX files. In this way you have full control of every function that you created and can optimize their speed, memory, size etc.

The components of a C MEX-file

The source code for a MEX-file consists of two distinct parts:

• A computational routine that contains the code for performing the computations that you want implemented in the MEX-file. Computations can be numerical computations as well as inputting and outputting data.
• A gateway routine that interfaces the computational routine with MATLAB by the entry point mexFunction and its parameters prhs, nrhs, plhs, nlhs, where prhs is an array of right-hand input arguments, nrhs is the number of right-hand input arguments, plhs is an array of left-hand output arguments, and nlhs is the number of left-hand output arguments. The gateway calls the computational routine as a subroutine.

In the gateway routine, you can access the data in the mxArray structure and then manipulate this data in your C computational subroutine. For example, the expression mxGetPr(prhs[0]) returns a pointer of type double* to the real data in the mxArray pointed to by prhs[0]. You can then use this pointer like any other pointer of type double* in C. After calling your C computational routine from the gateway, you can set a pointer of type mxArray to the data it returns. MATLAB is then able to recognize the output from your computational routine as the output from the MEX-file.

The following C MEX cycle figure shows how inputs enter a MEX-file, what functions the gateway routine performs, and how outputs return to MATLAB.

Creating MEX-files in Visual C++

Run Visual C++, select New... from File menu. In opened dialog, select "Win32 Dynamic-Link Library". In wizard, select "A DLL that exports some symbols" and press finish. Now everything is ready for building a MEX-file!

Add following lines to main source code:

#include "Matlab.h"    //MATLAB API

#pragma comment(lib, "libmx.lib")
#pragma comment(lib, "libmat.lib")
#pragma comment(lib, "libmex.lib")
#pragma comment(lib, "libmatlb.lib")

Add MATLAB_MEX_FILE preprocessor to project settings (Project -> Settings -> C/C++ -> General -> Preprocessor definitions).

Create a text file and rename it to your_project.def. your_project is name of your MEX-file. your_project.def is a definition file for exporting symbols. In this situation, you must export mexFunction. Here is an example:

; mexFunction.def : Declares the module parameters for the DLL.

LIBRARY      "ComputePrimes"
DESCRIPTION  'ComputePrimes Windows Dynamic Link Library'

EXPORTS
    ; Explicit exports can go here
    mexFunction

Now you must add following compiler switch to your project (Project -> Settings -> Link -> General -> Project Options):

/def:".\mexFunction.def"

Example

In this example, input argument is an integer non-complex scalar (n) and output is a vector containing first n prime numbers. Name of MEX-file is ComputePrimes. Syntax:

y = ComputePrime(n)

Final Work:

#include "stdafx.h"
#include "Matlab.h"
#include "mexFunction.h"

#pragma comment(lib, "libmx.lib")
#pragma comment(lib, "libmat.lib")
#pragma comment(lib, "libmex.lib")
#pragma comment(lib, "libmatlb.lib")

//return TRUE if n is a prime number
BOOL IsPrime(int n)
{
    for (int i=2; i<=n/2; i++)
    {
        if (n%i==0)
            return FALSE;
    }

    return TRUE;
}

void ComputePrimes(double* y, int n)
{
    int index=0, i=2;


    while (index!=n)
    {
        if (IsPrime(i))
        {
            y[index]=i;
            index++;
        }

        i++;
    }
}

void mexFunction(int nlhs, mxArray* plhs[], int nrhs, const mxArray* prhs[])
{
    if (nrhs != 1) 
    {
        mexErrMsgTxt("One input required.");
    } 
    else if (nlhs > 1) 
    {
        mexErrMsgTxt("Too many output arguments");
    }    

    /* The input must be a noncomplex scalar integer.*/
    int mrows, ncols;
    mrows = mxGetM(prhs[0]);
    ncols = mxGetN(prhs[0]);
    
    if (!mxIsDouble(prhs[0]) || mxIsComplex(prhs[0]) || 
        !(mrows == 1 && ncols == 1)) 
    {
        mexErrMsgTxt("Input must be a noncomplex scalar integer.");
    }

    double x, *y;
    /*
        e.g.   
                *x=4,
                *y=2, 3, 5, 7
    */
    
    x = mxGetScalar(prhs[0]);
        
    /* Create matrix for the return argument. */
    plhs[0] = mxCreateDoubleMatrix(mrows /* 1 */, (int) x, mxREAL);

    y = mxGetPr(plhs[0]);
    
    //call ComputePrimes subroutines to fill vector of primes
    ComputePrimes(y, (int) x);    
}

Further reading

For more information about MATLAB API, refer to my articles:

• Solving Engineering Problem Using MATLAB C API
• Solving Engineering Problem Using MATLAB C++ Math Library
• MATLAB Engine API

Enjoy!