Matlab has a variety of internal helper functions which are used by the main (documented) functions. Some of these helper functions are undocumented and unsupported, but may be helpful in their own right – not just as internal support functions.

In this post I want to present Matlab’s built-in * ismembc* helper function. This function is used within the stock Matlab

*and*

**ismember****functions for fast processing of the core**

*setxor**functionality in “regular” cases: arrays of sorted, non-sparse, non-NaN data in which we’re only interested in the logical membership information (not the index locations of the found members). In such cases,*

**ismember***can be used directly, saving*

**ismembc***‘s sanity-checks overhead.*

**ismember***uses the same interface (two inputs, single logical output) as*

**ismembc***and can be a drop-in replacement for*

**ismember***for these “regular” cases.*

**ismember**The performance improvement may be significant: In a recent post, MathWorks’ Loren Shure presented different approaches for fast data retrieval, highlighting the * ismember* function. Let’s compare:

>> % Initial setup >> n=2e6; a=ceil(n*rand(n,1)); b=ceil(n*rand(n,1)); >> % Runseveral times, to rule-out JIT compilation overheads >> tic;ismember(a,b);toc; Elapsed time is 2.882907 seconds. >> tic;ismember(a,b);toc; Elapsed time is 2.818318 seconds. >> tic;ismember(a,b);toc; Elapsed time is 3.005967 seconds. >> % Now useismember: >> tic;ismembc(a,b);toc; Elapsed time is 0.162108 seconds. >> tic;ismembc(a,b);toc; Elapsed time is 0.204108 seconds. >> tic;ismembc(a,b);toc; Elapsed time is 0.156963 seconds.ismembc

* ismembc* is actually a MEX file (%matlabroot%\toolbox\matlab\ops\ismembc.mexw32). Its source code is included in the same folder (%matlabroot%\toolbox\matlab\ops\ismembc.cpp) and is actually very readable. From the source code comments we learn that the comment in

*about*

**setxor***usage is misleading: that comment stated that the inputs must be real, but the source-code indicates that imaginary numbers are also accepted and that only the real-part should be sorted.*

**ismembc*** ismembc* should not be used carelessly: as noted, its inputs must be sorted non-sparse non-NaN values. In the general case we should either ensure this programmatically (as done in

*) or use*

**setxor***, which handles this for us.*

**ismember**The nice thing about * ismembc* is that its source code (ismembc.cpp) is included, so even if future Matlab releases stop using this function, you can always mex-compile the source code and use it.

Readers interested in * ismembc* might also be interested in its sibling help function,

*, which is also a mex file located (with source-code) in the same folder as*

**ismembc2***. Whereas*

**ismembc***returns an array of logical values,*

**ismembc***returns the index locations of the found members.*

**ismembc2**
Pingback: Datenum performance | Undocumented Matlab

interestingly, it appears that the variable “a” does not have to be sorted for using ismembc(), but the algorithm runs much more quickly if it is.

For ismembc(), the first input needs NOT to be sorted. Follows the heuristic that tests the assertion(terminate execution with CTRL+C):

The same holds true for ismembc2(), i.e. first input needs not to be sorted, IFF we are getting the positions under the ‘legacy’ flag:

The pos output:

To reproduce the same pos as with ismember() in >= R2012b, you do NOT need sorted A, but should have unique and sorted B.

Pingback: Undocumented Matlab at Nordt Blog

It doesn’t work if it’s not sorted. The function stops as soon as it meets a higher value. The given example is bad because the function stops most of the time too early (but ismembc is indeed faster).

@Vivien – the preconditions required by

were indeed mentioned in the article:ismembcshould not be used carelessly: as noted, its inputs must be sorted non-sparse non-NaN values. In the general case we should either ensure this programmatically (as done inismembc) or usesetxor, which handles this for us.ismemberPingback: sprintfc – undocumented helper function | Undocumented Matlab

There is almost no difference in the new 2013b version of Matlab:

@Ramy – I am not sure I understand – you ran the same

command several times, of course it would take a similar amount of time. If you run the same thing withismemberyou’ll see that it’s much faster. On the other hand, remember thatismembcmust have sorted inputs, and your inputs are currently random…ismembc@Yair, unfortunately, that is the same sample data as you use in your article. If you include the sort, ismembc becomes much slower to use. Interestingly, ismember on the older releases is similar to doing a sort of b and then calling ismembc, while in R2018a it has similar timings to a double sort before a call to ismembc. So sorting your own data is worth it (even with calling sort to an already sorted array, it is still faster than ismember).

On my W10x64 machine this returns the following timings:

@Rik – your outputs don’t correspond to your code, so they do not make any sense. Moreover, instead of reporting 3 separate timing instances, it would be better to report the total run-time of a loop of [say] 10-20 iterations.

I’m sorry, I edited my code after I already pasted the code here and forgot to update the code along with the output. The remarks in the posted text still stand though. Below is a 20 iteration version along with the sum timings.

@Rik – in a vast number of real-life use-cases, we already know in advance that either a or b or both are already sorted, and in this case

is still faster thanismembc, to this very day.ismemberEven if you sort the arrays yourself (as in your 3rd usage example),

is still much faster thanismembcfor most Matlab releases and almost as fast even on the latest release.ismemberTo make a long story short, there is very little (or no) down-side to using

, at least from a performance viewpoint, as long as your inputs are non-sparse etc.ismembcIf I’ve understood (and tested) it correctly, Inf-padding at the end of any of the 2 input vectors should not be a problem (sometimes vectors are 0 or NaN padded to preserve certain dimensionality)…

Otherwise, a very nice post, it really helped me a lot!