Announce

PukiWiki contents have been moved into SONOTS Plugin (20070703)

Matlab C Library Matrix Operations

Table of Contents

Matlab C Library Matrix Operations

#include <matrix.h>

Type/Structure

mwIndex (C and Fortran)	Type for index values
mwPointer (Fortran)	Declare appropriate pointer type for platform
mwSize (C and Fortran)	Type for size values
mxArray (C and Fortran)	Type for a MATLAB array

Getters

mxGetCell (C and Fortran)	Get contents of mxArray cell
mxGetChars (C)	Get pointer to character array data
mxGetClassID (C and Fortran)	Get class of mxArray
mxGetClassName (C and Fortran)	Get class of mxArray as string
mxGetData (C and Fortran)	Get pointer to data
mxGetDimensions (C and Fortran)	Get pointer to dimensions array
mxGetElementSize (C and Fortran)	Get number of bytes required to store each data element
mxGetEps (C and Fortran)	Get value of eps
mxGetField (C and Fortran)	Get field value, given field name and index into structure array
mxGetFieldByNumber (C and Fortran)	Get field value, given field number and index into structure array
mxGetFieldNameByNumber (C and Fortran)	Get field name, given field number in structure array
mxGetFieldNumber (C and Fortran)	Get field number, given field name in structure array
mxGetImagData (C and Fortran)	Get pointer to imaginary data of mxArray
mxGetInf (C and Fortran)	Get value of infinity
mxGetIr (C and Fortran)	Get ir array of sparse matrix
mxGetJc (C and Fortran)	Get jc array of sparse matrix
mxGetLogicals (C)	Get pointer to logical array data
mxGetM (C and Fortran)	Get number of rows in mxArray
mxGetN (C and Fortran)	Get number of columns in mxArray
mxGetNaN (C and Fortran)	Get value of NaN (Not-a-Number)
mxGetNumberOfDimensions (C and Fortran)	Get number of dimensions in mxArray
mxGetNumberOfElements (C and Fortran)	Get number of elements in mxArray
mxGetNumberOfFields (C and Fortran)	Get number of fields in structure mxArray
mxGetNzmax (C and Fortran)	Get number of elements in ir, pr, and pi arrays
mxGetPi (C and Fortran)	Get imaginary data elements in mxArray
mxGetPr (C and Fortran)	Get real data elements in mxArray
mxGetProperty (C and Fortran)	Get property value of MATLAB class object
mxGetScalar (C and Fortran)	Get real component of first data element in mxArray
mxGetString (C and Fortran)	Copy string mxArray to C-style string 

Setters

mxSetCell (C and Fortran)	Set value of one cell of mxArray
mxSetClassName (C)	Convert structure array to MATLAB object array
mxSetData (C and Fortran)	Set pointer to data
mxSetDimensions (C and Fortran)	Modify number of dimensions and size of each dimension
mxSetField (C and Fortran)	Set structure array field, given field name and index
mxSetFieldByNumber (C and Fortran)	Set structure array field, given field number and index
mxSetImagData (C and Fortran)	Set imaginary data pointer for mxArray
mxSetIr (C and Fortran)	Set ir array of sparse mxArray
mxSetJc (C and Fortran)	Set jc array of sparse mxArray
mxSetM (C and Fortran)	Set number of rows in mxArray
mxSetN (C and Fortran)	Set number of columns in mxArray
mxSetNzmax (C and Fortran)	Set storage space for nonzero elements
mxSetPi (C and Fortran)	Set new imaginary data for mxArray
mxSetPr (C and Fortran)	Set new real data for mxArray
mxSetProperty (C and Fortran)	Set value of property of MATLAB class object

Is

mxIsCell (C and Fortran)	Determine whether input is cell mxArray
mxIsChar (C and Fortran)	Determine whether input is string mxArray
mxIsClass (C and Fortran)	Determine whether mxArray is member of specified class
mxIsComplex (C and Fortran)	Determine whether data is complex
mxIsDouble (C and Fortran)	Determine whether mxArray represents data as double-precision, floating-point numbers
mxIsEmpty (C and Fortran)	Determine whether mxArray is empty
mxIsFinite (C and Fortran)	Determine whether input is finite
mxIsFromGlobalWS (C and Fortran)	Determine whether mxArray was copied from MATLAB global workspace
mxIsInf (C and Fortran)	Determine whether input is infinite
mxIsInt16 (C and Fortran)	Determine whether mxArray represents data as signed 16-bit integers
mxIsInt32 (C and Fortran)	Determine whether mxArray represents data as signed 32-bit integers
mxIsInt64 (C and Fortran)	Determine whether mxArray represents data as signed 64-bit integers
mxIsInt8 (C and Fortran)	Determine whether mxArray represents data as signed 8-bit integers
mxIsLogical (C and Fortran)	Determine whether mxArray is of type mxLogical
mxIsLogicalScalar (C)	Determine whether scalar mxArray is of type mxLogical
mxIsLogicalScalarTrue (C)	Determine whether scalar mxArray of type mxLogical is true
mxIsNaN (C and Fortran)	Determine whether input is NaN (Not-a-Number)
mxIsNumeric (C and Fortran)	Determine whether mxArray is numeric
mxIsSingle (C and Fortran)	Determine whether mxArray represents data as single-precision, floating-point numbers
mxIsSparse (C and Fortran)	Determine whether input is sparse mxArray
mxIsStruct (C and Fortran)	Determine whether input is structure mxArray
mxIsUint16 (C and Fortran)	Determine whether mxArray represents data as unsigned 16-bit integers
mxIsUint32 (C and Fortran)	Determine whether mxArray represents data as unsigned 32-bit integers
mxIsUint64 (C and Fortran)	Determine whether mxArray represents data as unsigned 64-bit integers
mxIsUint8 (C and Fortran)	Determine whether mxArray represents data as unsigned 8-bit integers

Alloc/Free

mxCalloc (C and Fortran)	Allocate dynamic memory for array using MATLAB memory manager
mxCreateCellArray (C and Fortran)	Create unpopulated N-D cell mxArray
mxCreateCellMatrix (C and Fortran)	Create unpopulated 2-D cell mxArray
mxCreateCharArray (C and Fortran)	Create unpopulated N-D string mxArray
mxCreateCharMatrixFromStrings (C and Fortran)	Create populated 2-D string mxArray
mxCreateDoubleMatrix (C and Fortran)	Create 2-D, double-precision, floating-point mxArray initialized to 0
mxCreateDoubleScalar (C and Fortran)	Create scalar, double-precision array initialized to specified value
mxCreateLogicalArray (C)	Create N-D logical mxArray initialized to false
mxCreateLogicalMatrix (C)	Create 2-D, logical mxArray initialized to false
mxCreateLogicalScalar (C)	Create scalar, logical mxArray
mxCreateNumericArray (C and Fortran)	Create unpopulated N-D numeric mxArray
mxCreateNumericMatrix (C and Fortran)	Create numeric matrix and initialize data elements to 0
mxCreateSparse (C and Fortran)	Create 2-D unpopulated sparse mxArray
mxCreateSparseLogicalMatrix (C)	Create unpopulated 2-D, sparse, logical mxArray
mxCreateString (C and Fortran)	Create 1-by-N string mxArray initialized to specified string
mxCreateStructArray (C and Fortran)	Create unpopulated N-D structure mxArray
mxCreateStructMatrix (C and Fortran)	Create unpopulated 2-D structure mxArray
mxDestroyArray (C and Fortran)	Free dynamic memory allocated by mxCreate* functions
mxDuplicateArray (C and Fortran)	Make deep copy of array
mxFree (C and Fortran)	Free dynamic memory allocated by mxCalloc, mxMalloc, or mxRealloc
mxMalloc (C and Fortran)	Allocate dynamic memory using MATLAB memory manager
mxRealloc (C and Fortran)	Reallocate memory
mxRemoveField (C and Fortran)	Remove field from structure array

Others

mxAddField (C and Fortran)	Add field to structure array
mxArrayToString (C)	Convert array to string
mxAssert (C)	Check assertion value for debugging purposes
mxAssertS (C)	Check assertion value without printing assertion text
mxCalcSingleSubscript (C and Fortran)	Offset from first element to desired element
mxChar (C)	Type for string mxArray
mxClassID (C)	Enumerated value identifying class of mxArray
mxComplexity (C)	Flag specifying whether mxArray has imaginary components

Examples

Create a mxArray

double mat[] = {
    11, 21,
    12, 22,
    13, 23,
    14, 24
};
int nRow = 2; // M = 2;
int nCol = 4; // N = 4;
// Allocate memory. mxCOMPLEX for complex array
mxArray* X = mxCreateDoubleMatrix(nRow, nCol, mxREAL);
// Assign
memcpy(mxGetPr(X), mat, nRow*nCol*sizeof(double));
mxDestroyArray(X);

mxSetPr

// Prepare data
double mat[] = {
 11, 21,
 12, 22,
 13, 23,
 14, 24
};
// mxSetPr requires dynamic array mxCalloc/mxMalloc/mxRealloc
double* matmat = mxCalloc(nRow*nCol, sizeof(double));
memcpy(matmat, mat, nRow*nCol*sizeof(double));

mwSize nRow = 2; // M = 2;
mwSize nCol = 4; // N = 4;
mxArray* X = mxCreateDoubleMatrix(nRow, nCol, mxREAL);
// Free before mxSetPr because mxSetPr allocates new memory
mxFree(mxGetPr(X));
mxSetPr(X, matmat);
mxDestroyArray(X);
// mxCalloc/mxMalloc/mxRealloc are freed via mxFree
mxFree(matmat);
double mat[] = {
 11, 21,
 12, 22,
 13, 23,
 14, 24
};
// mxSetPr requires dynamic array mxCalloc/mxMalloc/mxRealloc
double* matmat = mxCalloc(nRow*nCol, sizeof(double));
memcpy(matmat, mat, nRow*nCol*sizeof(double));

mwSize nRow = 2; // M = 2;
mwSize nCol = 4; // N = 4;
// Do not allocate memory yet not to free as above
mxArray* X = mxCreateDoubleMatrix(0, 0, mxREAL);
mxSetM(nRow);
mxSetN(nCol);
mxSetPr(X, matmat);
mxDestroyArray(X);
mxFree(mat);

Access to mxArray

mwSize row, col; // mwSize is int 
// When using the mex -largeArrayDims switch, mwSize is equivalent to size_t
mwSize nRow = mxGetM(xData); 
mwSize nCol = mxGetN(xData);
double *xValues = mxGetPr(xData);

for(row = 0; row < nRow; row++) {
    for(col = 0; col < nCol; col++) {
        printf("%lf, *xValues[nRow * col + row]);
    }
    printf("\n");
}

Create a cell array

mwSize ndim = 1;
mwSize dims[] = {2};
mxArray* cell = mxCreateCellArray(ndim, dims);
mxArray* X1 = mxCreateDoubleMatrix(3, 4, mxREAL);
mxArray* X2 = mxCreateDoubleMatrix(1, 5, mxREAL);
mxSetCell(cell, (mxIndex)0, X1); // this allocates memory
mxSetCell(cell, (mxIndex)1, X2);
// destroy before re-set
mxDestroyArray(mxGetCell(cell, 0)); // does not free X1
mxDestroyArray(mxGetCell(cell, 1));
mxArray* Y1 = mxCreateDoubleMatrix(3, 4, mxREAL);
mxArray* Y2 = mxCreateDoubleMatrix(1, 5, mxREAL);
mxSetCell(cell, (mxIndex)0, Y1);
mxSetCell(cell, (mxIndex)1, Y2);
mxDestroyArray(X1);
mxDestroyArray(X2);
mxDestroyArray(Y1);
mxDestroyArray(Y2);
mxDestroyArray(cell);

Print a 3-D array

void cvmxPrintMatrix(const mxArray* mxarr)
{
    int nDim;
    const int *dims;
    int row, col, z;
    mxClassID classid;
    classid = mxGetClassID(mxarr);
    nDim = mxGetNumberOfDimensions(mxarr);
    dims = mxGetDimensions(mxarr);

    if (classid == mxUINT8_CLASS) {
        unsigned char *mxData = mxGetData(mxarr);
        for (z = 0; z < dims[2]; z++) {
            for (row = 0; row < dims[0]; row++) {
                for (col = 0; col < dims[1]; col++) {
                    printf("%d ", mxData[
                        dims[0] * dims[1] * z + dims[0] * col + row]);
                }
                printf("\n");
            }
            printf("\n");
        }
    } else if (classid == mxDOUBLE_CLASS) {
        double *mxData = mxGetData(mxarr);
        for (z = 0; z < dims[2]; z++) {
            for (row = 0; row < dims[0]; row++) {
                for (col = 0; col < dims[1]; col++) {
                    printf("%lf ", mxData[
                        dims[0] * dims[1] * z + dims[0] * col + row]);
                }
                printf("\n");
            }
            printf("\n");
        }
    } else if (classid == mxSINGLE_CLASS) {
        float *mxData = mxGetData(mxarr);
        for (z = 0; z < dims[2]; z++) {
            for (row = 0; row < dims[0]; row++) {
                for (col = 0; col < dims[1]; col++) {
                    printf("%lf ", mxData[
                        dims[0] * dims[1] * z + dims[0] * col + row]);
                }
                printf("\n");
            }
            printf("\n");
        }
    }
}

References