MATLAB Support for Interleaved Complex API in MEX Functions

When a matrix of complex numbers is represented in computer memory, there are several choices for the location and order of storage. Before MATLAB^® Version 9.4 (R2018a), MATLAB used a separate storage representation. The real and the imaginary parts of the numbers were stored separately. MATLAB uses an interleaved storage representation for C and Fortran language MEX files, where the real and imaginary parts are stored together. Interleaved complex refers to this representation.

Since many mathematical libraries use an interleaved complex representation, using the same representation in your MEX functions eliminates the need to translate data. This simplifies your code and potentially speeds up the processing when large data sets are involved.

This change does not affect the MATLAB language. You can continue to use the functionality described in Complex Numbers without any modification of your functions and scripts.

Separate Complex API and Interleaved Complex API

There are two versions of the C Matrix API and Fortran Matrix API.

The separate complex API contains the C and Fortran Matrix API functionality in MATLAB R2017b and earlier.
The interleaved complex API contains the C Matrix API functionality as of MATLAB R2018a and the Fortran Matrix API functionality as of MATLAB R2018a Update 3.

To build MEX files with the interleaved complex API, use the mex release-specific build option -R2018a. To build MEX files with the separate complex API, use the -R2017b build option. The mex command uses the separate complex API by default. However, in a future version of MATLAB, mex will use the interleaved complex API (-R2018a option) by default and then you need to modify your build command. Therefore, to ensure the desired behavior across versions of MATLAB, add the -R2017b option to your existing build scripts. To write code to support both APIs, see Add MX_HAS_INTERLEAVED_COMPLEX to Support Both Complex Number Representations.

Note

To run a Fortran MEX file built with the interleaved complex API in R2018a, you must use R2018a Update 3.

Matrix API Changes Supporting Interleaved Complex

The following changes to the C and Fortran Matrix APIs support interleaved complex.

New typed data access functions. For more information, see Typed Data Access in C MEX Files.

MATLAB `mxArray` Types	C Typed Data Access Functions	Fortran Typed Data Access Functions
`mxDOUBLE_CLASS`	`mxGetDoubles` `mxSetDoubles` `mxGetComplexDoubles` `mxSetComplexDoubles`	`mxGetDoubles` `mxSetDoubles` `mxGetComplexDoubles` `mxSetComplexDoubles`
`mxSINGLE_CLASS`	`mxGetSingles` `mxSetSingles` `mxGetComplexSingles` `mxSetComplexSingles`	`mxGetSingles` `mxSetSingles` `mxGetComplexSingles` `mxSetComplexSingles`
`mxINT8_CLASS`	`mxGetInt8s` `mxSetInt8s` `mxGetComplexInt8s` `mxSetComplexInt8s`	`mxGetInt8s` `mxSetInt8s` `mxGetComplexInt8s` `mxSetComplexInt8s`
`mxUINT8_CLASS`	`mxGetUint8s` `mxSetUint8s` `mxGetComplexUint8s` `mxSetComplexUint8s`	`mxGetUint8s` `mxSetUint8s` `mxGetComplexUint8s` `mxSetComplexUint8s`
`mxINT16_CLASS`	`mxGetInt16s` `mxSetInt16s` `mxGetComplexInt16s` `mxSetComplexInt16s`	`mxGetInt16s` `mxSetInt16s` `mxGetComplexInt16s` `mxSetComplexInt16s`
`mxUINT16_CLASS`	`mxGetUint16s` `mxSetUint16s` `mxGetComplexUint16s` `mxSetComplexUint16s`	`mxGetUint16s` `mxSetUint16s` `mxGetComplexUint16s` `mxSetComplexUint16s`
`mxINT32_CLASS`	`mxGetInt32s` `mxSetInt32s` `mxGetComplexInt32s` `mxSetComplexInt32s`	`mxGetInt32s` `mxSetInt32s` `mxGetComplexInt32s` `mxSetComplexInt32s`
`mxUINT32_CLASS`	`mxGetUint32s` `mxSetUint32s` `mxGetComplexUint32s` `mxSetComplexUint32s`	`mxGetUint32s` `mxSetUint32s` `mxGetComplexUint32s` `mxSetComplexUint32s`
`mxINT64_CLASS`	`mxGetInt64s` `mxSetInt64s` `mxGetComplexInt64s` `mxSetComplexInt64s`	`mxGetInt64s` `mxSetInt64s` `mxGetComplexInt64s` `mxSetComplexInt64s`
`mxUINT64_CLASS`	`mxGetUint64s` `mxSetUint64s` `mxGetComplexUint64s` `mxSetComplexUint64s`	`mxGetUint64s` `mxSetUint64s` `mxGetComplexUint64s` `mxSetComplexUint64s`

Matrix API functions added to the -R2018a API:
- mxMakeArrayComplex (C) and mxMakeArrayComplex (Fortran)
- mxMakeArrayReal (C) and mxMakeArrayReal (Fortran)
Matrix API functions not supported in the -R2018a API:
The behavior of these Matrix API functions changes in the -R2018a API. In addition, these functions are to be phased out.
- mxGetPr (C) and mxGetPr (Fortran)
- mxSetPr (C) and mxSetPr (Fortran)
The behavior of these Matrix API functions changes in the -R2018a API:
The behavior of these Fortran Matrix API functions changes in the -R2018a API:

Writing MEX Functions with Interleaved Complex API

To learn how to write MEX functions using the interleaved complex API, see Handle Complex Data in C MEX File in C applications or Handle Complex Fortran Data.

MEX Functions Created in MATLAB R2017b and Earlier

If you already build MEX functions, MEX S-functions, or standalone MATLAB engine and MAT-file applications, then you should review the Do I Need to Upgrade My MEX Files to Use Interleaved Complex API? topic. To help transition your MEX files and S-functions to the interleaved complex API, MATLAB maintains a compatibility interface. To build MEX files with the compatibility interface, use the mex -R2017b flag. If your code processes complex numbers, you might notice a performance impact as MATLAB adapts your data to the interleaved complex format.

The mex command uses the -R2017b API by default. However, in a future version of MATLAB, mex will use the interleaved complex API -R2018a by default and then you need to modify your build command. Therefore, to ensure the desired behavior across versions of MATLAB, add the compatibility flag -R2017b to your build scripts.