matlab/matlab-agentic-toolkit / skills-catalog/matlab-external-language-interfaces/matlab-upgrade-mex-ic
matlab-upgrade-mex-ic
VerifiedUpgrade 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 19.0 KB |
| manifest.yaml | config | 496 B |
| references/api-mappings.md | markdown | 7.5 KB |
| references/pitfalls.md | markdown | 7.2 KB |
references/api-mappings.md
View on GitHub# SC to IC API Function Mappings
Complete mapping of Separate Complex API functions to their Interleaved Complex replacements. These mappings apply to both C and Fortran MEX files — the function names are identical in both languages.
## Required Replacements (Breaking in IC Mode)
These functions do not exist or behave differently in IC mode. Code using them will not compile with `mex -R2018a`.
### Complex Data Accessors
| SC Function | IC Replacement | Notes |
|-------------|---------------|-------|
| `mxGetPi(arr)` | `mxGetComplexDoubles(arr)` → access `.imag` | Returns NULL in IC; must use typed accessor |
| `mxSetPi(arr, ptr)` | `mxSetComplexDoubles(arr, ptr)` | Single interleaved buffer replaces separate imag |
| `mxGetImagData(arr)` | Type-specific complex accessor | See typed accessors below |
| `mxSetImagData(arr, ptr)` | Type-specific complex setter | See typed setters below |
### Complexity Checking
| SC Pattern | IC Replacement | Notes |
|------------|---------------|-------|
| `mxGetPi(arr) != NULL` | `mxIsComplex(arr)` | `mxIsComplex` works in both SC and IC |
## Required Replacements — Wrong Results on Complex Arrays; Untyped
These functions still compile in IC mode on real-only arrays, but return **wrong data on complex arrays** (pointer to interleaved buffer interpreted as real-only). They are also untyped (`double*` or `void*`). Always convert when upgrading to IC.
### Real/Generic Data Accessors
| SC Function | IC Replacement | Why required |
|-------------|---------------|--------------|
| `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)` | Type-specific accessor (see below) | Wrong results on complex arrays in IC; `void*` cast unsafe |
| `mxSetData(arr, ptr)` | Type-specific setter (see below) | Wrong results on complex arrays in IC; `void*` cast unsafe |
## Type-Specific Accessors (IC Mode)
### Real Data
| Data Type | Accessor | Setter | Return Type |
|-----------|----------|--------|-------------|
| double | `mxGetDoubles` | `mxSetDoubles` | `mxDouble*` |
| single | `mxGetSingles` | `mxSetSingles` | `mxSingle*` |
| int8 | `mxGetInt8s` | `mxSetInt8s` | `mxInt8*` |
| uint8 | `mxGetUint8s` | `mxSetUint8s` | `mxUint8*` |
| int16 | `mxGetInt16s` | `mxSetInt16s` | `mxInt16*` |
| uint16 | `mxGetUint16s` | `mxSetUint16s` | `mxUint16*` |
| int32 | `mxGetInt32s` | `mxSetInt32s` | `mxInt32*` |
| uint32 | `mxGetUint32s` | `mxSetUint32s` | `mxUint32*` |
| int64 | `mxGetInt64s` | `mxSetInt64s` | `mxInt64*` |
| uint64 | `mxGetUint64s` | `mxSetUint64s` | `mxUint64*` |
### Complex Data
| Data Type | Accessor | Setter | Return Type |
|-----------|----------|--------|-------------|
| complex double | `mxGetComplexDoubles` | `mxSetComplexDoubles` | `mxComplexDouble*` |
| complex single | `mxGetComplexSingles` | `mxSetComplexSingles` | `mxComplexSingle*` |
| complex int8 | `mxGetComplexInt8s` | `mxSetComplexInt8s` | `mxComplexInt8*` |
| complex uint8 | `mxGetComplexUint8s` | `mxSetComplexUint8s` | `mxComplexUint8*` |
| complex int16 | `mxGetComplexInt16s` | `mxSetComplexInt16s` | `mxComplexInt16*` |
| complex uint16 | `mxGetComplexUint16s` | `mxSetComplexUint16s` | `mxComplexUint16*` |
| complex int32 | `mxGetComplexInt32s` | `mxSetComplexInt32s` | `mxComplexInt32*` |
| complex uint32 | `mxGetComplexUint32s` | `mxSetComplexUint32s` | `mxComplexUint32*` |
| complex int64 | `mxGetComplexInt64s` | `mxSetComplexInt64s` | `mxComplexInt64*` |
| complex uint64 | `mxGetComplexUint64s` | `mxSetComplexUint64s` | `mxComplexUint64*` |
## Complex Data Struct Layout (IC Mode)
```c
/* Each complex element is a struct with .real and .imag fields */
typedef struct {
double real;
double imag;
} mxComplexDouble;
typedef struct {
float real;
float imag;
} mxComplexSingle;
typedef struct {
int32_T real;
int32_T imag;
} mxComplexInt32;
/* ... similar for all numeric types */
```
## SC/IC Guarded Pattern (`#if MX_HAS_INTERLEAVED_COMPLEX`)
Use `#if MX_HAS_INTERLEAVED_COMPLEX` to support both APIs in one source.
### C Example
```c
#if MX_HAS_INTERLEAVED_COMPLEX
/* IC path: single interleaved buffer */
mxComplexDouble *pc = mxGetComplexDoubles(prhs[0]);
for (i = 0; i < n; i++) {
result[i].real = pc[i].real * scale;
result[i].imag = pc[i].imag * scale;
}
#else
/* SC path: separate real and imaginary arrays */
double *pr = mxGetPr(prhs[0]);
double *pi = mxGetPi(prhs[0]);
for (i = 0; i < n; i++) {
result_r[i] = pr[i] * scale;
result_i[i] = pi[i] * scale;
}
#endif
```
### Fortran Example (`.F` file)
```fortran
#if MX_HAS_INTERLEAVED_COMPLEX
c IC path: interleaved complex*16 buffer
pc = mxGetComplexDoubles(prhs(1))
call mxCopyPtrToComplex16(pc, zdata, n)
do i = 1, n
zdata(i) = zdata(i) * scale
end do
#else
c SC path: separate real and imaginary arrays
pr = mxGetPr(prhs(1))
pi = mxGetPi(prhs(1))
call mxCopyPtrToReal8(pr, xr, n)
call mxCopyPtrToReal8(pi, xi, n)
do i = 1, n
xr(i) = xr(i) * scale
xi(i) = xi(i) * scale
end do
#endif
```
### Build Commands
| Language | SC mode | IC mode |
|----------|---------|---------|
| C | `mex file.c` | `mex -R2018a file.c` |
| Fortran | `mex file.F` | `mex -R2018a file.F` |
## Fortran-Specific Considerations
### File Extension Requirements
| Extension | Preprocessor? | SC/IC guarded? |
|-----------|--------------|-----------------|
| `.F` (uppercase) | Yes | Yes — `#if` guards work |
| `.F90` (uppercase) | Yes | Yes — `#if` guards work |
| `.f` (lowercase) | No | No — must use IC-only |
| `.f90` (lowercase) | No | No — must use IC-only |
### Fortran Data Copy Functions
Fortran MEX files use `mxCopyPtrTo*` and `mxCopy*ToPtr` for data transfer between MATLAB arrays and Fortran variables:
| SC Pattern | IC Replacement | Notes |
|-----------|---------------|-------|
| `mxCopyPtrToReal8(mxGetPr(a), x, n)` | `mxCopyPtrToReal8(mxGetDoubles(a), x, n)` | Real double data |
| `mxCopyPtrToReal4(mxGetPr(a), x, n)` | `mxCopyPtrToReal4(mxGetSingles(a), x, n)` | Real single data |
| `mxCopyPtrToReal8(mxGetPi(a), x, n)` | Use `mxCopyPtrToComplex16(mxGetComplexDoubles(a), z, n)` | Complex: copy interleaved, then extract imag |
| `mxCopyReal8ToPtr(x, mxGetPr(a), n)` | `mxCopyReal8ToPtr(x, mxGetDoubles(a), n)` | Write real double data |
| `mxCopyComplex16ToPtr(z, ptr, n)` | `mxCopyComplex16ToPtr(z, mxGetComplexDoubles(a), n)` | Write complex data (IC) |
### Fortran Complex Data Pattern
In SC mode, Fortran MEX files access real and imaginary parts separately:
```fortran
c SC Fortran pattern
mwPointer mxGetPr, mxGetPi
pr = mxGetPr(prhs(1))
pi = mxGetPi(prhs(1))
call mxCopyPtrToReal8(pr, xr, n)
call mxCopyPtrToReal8(pi, xi, n)
```
In IC mode, complex data is interleaved and can be copied directly to a Fortran `complex*16` array:
```fortran
c IC Fortran pattern
mwPointer mxGetComplexDoubles
pc = mxGetComplexDoubles(prhs(1))
call mxCopyPtrToComplex16(pc, zdata, n)
c zdata is complex*16 — real and imag parts are together
```
## Build Flags Reference
| Flag | API Mode | Macro Value | Notes |
|------|----------|-------------|-------|
| (none) | Depends on MATLAB version | Varies | Default changed to IC in R2018a |
| `-R2017b` | Separate Complex | 0 | Forces SC mode |
| `-R2018a` | Interleaved Complex | 1 | Forces IC mode |
----
Copyright 2026 The MathWorks, Inc.
----
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |