---

name: matlab-upgrade-mex-ic description: > Upgrade C, C++, and Fortran MEX source files from the Separate Complex (SC) API to the Interleaved Complex (IC) API. Use when converting mxGetPr/mxGetPi to mxGetComplexDoubles, migrating MEX files to -R2018a, adding MX_HAS_INTERLEAVED_COMPLEX guards for SC/IC guarded builds, or modernizing legacy MEX code that uses mxGetData/mxSetData/mxGetImagData/mxSetImagData. Covers C (.c), C++ (.cpp, .cxx), and Fortran (.F, .f90) MEX functions. Triggers on: interleaved complex, IC MEX, mex upgrade, mex migration, separate complex, mxGetPi, mxGetPr replacement, -R2018a, complex MEX, Fortran MEX, .F MEX file, C++ MEX, .cpp MEX file, MEX performance, MEX slow complex, MEX call overhead, improve MEX performance complex. license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "1.0"

Upgrade MEX Files to Interleaved Complex API

Convert C, C++, and Fortran MEX source files from the Separate Complex (SC) API to the Interleaved Complex (IC) API, following the MathWorks upgrade workflow with guardrails for SC/IC guarded builds using MX_HAS_INTERLEAVED_COMPLEX, required vs recommended changes, and verification.

When to Use

• User has a C, C++, or Fortran MEX file using mxGetPr/mxGetPi, mxGetData/mxGetImagData, or mxSetPr/mxSetPi
• User wants to build with mex -R2018a
• User asks about interleaved complex, IC MEX, or modernizing MEX code
• User has legacy MEX code from File Exchange, GitHub, or pre-R2018a era
• User has a C++ MEX file (.cpp, .cxx) using the C Matrix API (mxGetPr/mxGetPi, etc.)
• User has a Fortran MEX file (.F, .f90) using mxGetPr/mxGetPi via %val() pointers
• User reports a MEX function is slow on large complex arrays (call overhead, not loop)
• User asks how to improve MEX performance for complex data

When NOT to Use

• Writing a new MEX function from scratch — no conversion needed, but advise the user to use IC APIs (mxGetDoubles, mxGetComplexDoubles, etc.) from the start for better performance on complex data and modern, type-safe data access instead of legacy mxGetPr/mxGetPi
• C++ MEX API (matlab::mex::Function) — different API entirely; this skill covers C++ files that use the C Matrix API (mex.h), not the MATLAB Data API for C++ and C++ Engine
• MEX file already uses typed accessors (mxGetDoubles, mxGetComplexDoubles, etc.) — already IC-compatible, no conversion needed

Workflow

Follow these 7 steps in order. Do NOT skip steps.

Step 1: Pre-Upgrade Verification

Before changing anything, understand the current state:

1. Read the source file completely
2. Identify all SC API calls (see Key API Mappings)
3. Note which data types the MEX handles (double, single, int32, etc.)
4. Note whether it handles complex data (mxGetPi, mxIsComplex, mxCOMPLEX)

Report to the user:

• Number of SC API calls found
• Whether file processes complex numbers (complex arrays in SC mode incur deinterleave/re-interleave overhead)
• Performance impact: If the file handles complex data, note that SC MEX calls incur O(n) deinterleave/re-interleave copies at the MATLAB boundary. For large arrays, IC conversion eliminates this overhead entirely (see Performance Benefits).
• Any other issues noticed (missing error checking, etc.)

Step 2: Output File Decision

ASK the user before proceeding:

"Where should I write the converted code?

• New file — creates a separate file (e.g., <name>_ic.c or <name>_dual.c), preserving the original untouched
• Modify in place — edits the original file directly. Choose this if the file is under version control and you can revert if needed."

If user chooses new file, use these naming defaults (or a user-specified name):

• IC-only: <name>_ic.c / <name>_ic.F
• SC/IC guarded: <name>_dual.c / <name>_dual.F

If user chooses modify in place, confirm the file is recoverable (e.g., "This file is tracked by git — you can revert with git checkout <file> if needed."). Then edit the original directly.

Tell the user which file you're writing to and why.

Step 3: Decision Point — IC-Only or SC/IC Guarded?

What is "SC/IC guarded"? A single source file that uses #if MX_HAS_INTERLEAVED_COMPLEX preprocessor guards to compile under both the Separate Complex API (mex -R2017b) and the Interleaved Complex API (mex -R2018a). The compiler defines MX_HAS_INTERLEAVED_COMPLEX=1 in IC mode and 0 in SC mode, so the guards select the correct code path at build time.

ASK the user before proceeding:

"Do you need this MEX file to compile under both the old SC API and the new IC API?

• SC/IC guarded — wraps code in #if MX_HAS_INTERLEAVED_COMPLEX / #else guards so the same source builds with both mex -R2017b file.c (SC mode) and mex -R2018a file.c (IC mode). Choose this if you support multiple MATLAB versions.
• IC-only — converts fully to IC API. Requires mex -R2018a to build. Simpler code but only works on R2018a+."

If user chooses SC/IC guarded, use the #if MX_HAS_INTERLEAVED_COMPLEX preprocessor pattern:

C/C++ files:

#if MX_HAS_INTERLEAVED_COMPLEX
    /* IC code path */
    mxComplexDouble *pc = mxGetComplexDoubles(prhs[0]);
#else
    /* SC code path */
    double *pr = mxGetPr(prhs[0]);
    double *pi = mxGetPi(prhs[0]);
#endif

Fortran files (.F preprocessed source):

#if MX_HAS_INTERLEAVED_COMPLEX
      mwPointer mxGetComplexDoubles
      complex*16, pointer :: pc(:)
      call mxGetComplexDoubles(prhs(1), pc)
#else
      mwPointer mxGetPr, mxGetPi
      mwPointer pr, pi
      pr = mxGetPr(prhs(1))
      pi = mxGetPi(prhs(1))
#endif

Fortran note: SC/IC guarded Fortran files MUST use .F extension (uppercase) so the MEX compiler invokes the C preprocessor. The .f or .f90 extension skips preprocessing and #if guards will not work. For .f90 files that cannot use preprocessor guards, use IC-only conversion.

If user chooses IC-only, convert directly without guards.

Step 4: Iterative Refactoring

All legacy data-access APIs are REQUIRED to be converted for a complete IC upgrade. Convert every pattern in this table:

| Legacy Pattern | Replacement | Reason | |----------------|-------------|--------| | mxGetPi(arr) for data access | mxGetComplexDoubles(arr) + .imag | Does not exist in IC | | mxSetPi(arr, ptr) | mxSetComplexDoubles(arr, ptr) | Does not exist in IC | | mxGetImagData(arr) | Type-specific complex accessor | Does not exist in IC | | mxSetImagData(arr, ptr) | Type-specific complex setter | Does not exist in IC | | mxGetPi(arr) != NULL for complexity check | mxIsComplex(arr) — works in both SC and IC | Does not exist in IC | | mxGetPr(arr) | mxGetDoubles(arr) | Wrong results on complex arrays in IC; untyped | | mxSetPr(arr, ptr) | mxSetDoubles(arr, ptr) | Wrong results on complex arrays in IC; untyped | | mxGetData(arr) + void* cast | Type-specific accessor (mxGetDoubles, mxGetInt32s, etc.) | Wrong results on complex arrays in IC; untyped | | mxSetData(arr, ptr) | Type-specific setter (mxSetDoubles, mxSetInt32s, etc.) | Wrong results on complex arrays in IC; untyped |

Why all REQUIRED? mxGetPr/mxGetData on complex arrays in IC mode return a pointer to interleaved data (real and imaginary interleaved) — iterating as if it were real-only gives wrong results silently. On real-only arrays they still work, but are untyped (void* or always double*). When upgrading to IC, convert everything in one pass for correctness and type safety.

See references/pitfalls.md for common conversion mistakes (complexity checks, output allocation, buffer sizing, Fortran interleaved layout).

Reducing Code Duplication in SC/IC Guarded Mode

In SC/IC guarded mode, minimize duplication by guarding only the accessor calls, not entire logic blocks.

C/C++ files:

/* Guard only the pointer acquisition — logic stays shared */
double *pr_in, *pr_out;

#if MX_HAS_INTERLEAVED_COMPLEX
    pr_in = mxGetDoubles(prhs[0]);
#else
    pr_in = mxGetPr(prhs[0]);
#endif

plhs[0] = mxCreateDoubleMatrix(m, n, mxREAL);

#if MX_HAS_INTERLEAVED_COMPLEX
    pr_out = mxGetDoubles(plhs[0]);
#else
    pr_out = mxGetPr(plhs[0]);
#endif

/* Shared logic — no duplication */
for (i = 0; i < numElements; i++) {
    pr_out[i] = pr_in[i] * factor;
}

Fortran files (.F):

c     Guard only the pointer acquisition
#if MX_HAS_INTERLEAVED_COMPLEX
      pr_in = mxGetDoubles(prhs(1))
#else
      pr_in = mxGetPr(prhs(1))
#endif

c     Shared logic — no duplication
      call mxCopyPtrToReal8(pr_in, data, numElements)
      do i = 1, numElements
          data(i) = data(i) * factor
      end do

For complex data, the layout differs between modes (interleaved struct vs separate arrays), so full #if/#else blocks around the logic are unavoidable.

Rule of thumb:

• Real data paths — guard only the accessor, share the loop
• Complex data paths — guard the entire block (different data layouts require different loop bodies). See references/api-mappings.md § "SC/IC Guarded Pattern" for full complex loop examples in C, C++, and Fortran.

See references/api-mappings.md for the complete function mapping table.

Step 5: Build

Provide the exact build commands (adjust extension for language):

% C/C++ files
mex -R2018a <filename>.c       % Explicit IC mode
mex -R2017b <filename>.c       % Explicit SC mode
mex <filename>.c               % Default (version-dependent)
% For C++: same flags with .cpp or .cxx extension
mex -R2018a <filename>.cpp     % Explicit IC mode

% Fortran files (.F with preprocessor guards)
mex -R2018a <filename>.F       % Explicit IC mode
mex -R2017b <filename>.F       % Explicit SC mode
mex <filename>.F               % Default (version-dependent)

If the file is SC/IC guarded, remind the user to test all three build modes: -R2017b (SC), -R2018a (IC), and default (no flag).

Fortran: Files must use .F (uppercase) extension for preprocessor guards to work. If the source is .f or .f90, rename to .F or .F90 when adding #if guards.

Step 6: Verify

Provide MATLAB test commands that compare the converted MEX against the original.

For IC-only conversions (separate source files):

%% Build original with SC, converted with IC
mex -R2017b originalFile.c -output func_sc    % Explicit SC build
mex -R2018a convertedFile_ic.c -output func_ic % Explicit IC build

%% Compare outputs
Z = complex(rand(4,4), rand(4,4));
assert(isequal(func_sc(Z), func_ic(Z)), 'Output mismatch!');

For SC/IC guarded files (same source, three build modes):

%% Build same source in all three modes
mex -R2017b convertedFile.c -output func_sc       % Explicit SC (forces separate complex)
mex -R2018a convertedFile.c -output func_ic       % Explicit IC (forces interleaved complex)
mex convertedFile.c -output func_default           % Default (no API flag)

%% Compare outputs — all three must match
Z = complex(rand(4,4), rand(4,4));
out_sc = func_sc(Z);
out_ic = func_ic(Z);
out_default = func_default(Z);
assert(isequal(out_sc, out_ic), 'SC vs IC mismatch!');
assert(isequal(out_sc, out_default), 'SC vs default mismatch!');

Always test with:

• Complex inputs (if the MEX handles complex data)
• Real inputs (if the MEX handles real data)
• Edge cases: empty arrays, scalars, large arrays
• All three build modes: -R2017b (SC), -R2018a (IC), and default (no flag)
• The original source file still compiles with mex -R2017b (confirms it was not modified)

Step 7: Document

Add build information to the converted file's header comment:

/*
 * Compile (Interleaved Complex API, R2018a+):
 *   mex -R2018a filename.c
 *
 * Original (Separate Complex API):
 *   mex or