MATLAB Interface Discussion

[ssun30]

I will be posting questions regarding implementing a new MATLAB interface based on direct C++ library integration introduced in MATLAB 2019a.

Questions I have as of 06/03/21:

1. I would like to know if I understand the current implementation correctly:

In the MATLAB toolbox there are .m functions that the user directly interact with.
These .m functions are often single-line scripts that call .m objects defined in each class folder.
Those .m objects then call methods in the private directory of each class.
Those .m methods are directed to a MEX file called ctmethods which interfaces with the C++ libraries.

2. What makes the ctmethods MEX file difficult to maintain?

3. Is there a self-contained module of cantera that I could use to test direct C++ integration? Currently I'm working with a very small experimental library I wrote myself (only two header files) which doesn't give me a good idea of the complexity and scale of integrating a large library.

4. Another way is to re-write each C++ function into MEX which obviously we are not going to do. But one major advantage of coding in MEX is that it could use MATLAB's powerful vectorization capability to drastically speed up vector and matrix operations (I'm seeing at least 10x and potentially more with GPU). On the other hand MATLAB is extremely slow with sequential operations (like FOR loops). Is there some part of cantera that could benefit from parallelization but could not be easily vectorized in C++? If so then I think at least these could benefit from having a native MEX code for MATLAB to call directly.

[ischoegl]

@ssun30 ... thank you for starting the discussion! I am not using the MATLAB interface much, but will try to answer. I also apologize that some of my working knowledge dates back to MEX files as they stood in the early 2000's. (Which is, however, consistent with what is used in the current MATLAB implementation). I am responding to the first two questions here; the other questions are better served in separate threads here.

1. I would like to know if I understand the current implementation correctly:

• In the MATLAB toolbox there are .m functions that the user directly interact with.
• These .m functions are often single-line scripts that call .m objects defined in each class folder.
• Those .m objects then call methods in the private directory of each class.
• Those .m methods are directed to a MEX file called ctmethods which interfaces with the C++ libraries.

What you see is a legacy structure of MATLAB classes (they since have moved to a newer implementation, see here), which are organized as a folder/file structure where @ indicates that this is a class. This implementation creates a relatively awkward handling of objects (you have to pass the object for class methods). As an example, the density of a gas is rho0 = density(gas);, where a conventional class would use rho0 = gas.density;.

You are correct about ctmethods (as defined in cantera/src/matlab/ctmethods.cpp); it does, however, interface with clib (via include/cantera/clib/ct.h) which corresponds to the Cantera C interface; that interface then interacts with the actual C++ code.

2. What makes the ctmethods MEX file difficult to maintain?

In a nutshell, the execution is anything but straight-forward. Let's pick density.m (which is defined in @ThermoPhase):

function rho = density(tp)
% DENSITY  Get the density.
% rho = density(tp)
% :param tp:
%     Instance of class :mat:func:`ThermoPhase` (or another
%     object that derives from ThermoPhase)
% :return:
%     Mass density. Units: kg/m**3
%

rho = phase_get(tp.tp_id, 2);

which calls into the private phase_get.m, i.e.

function i = phase_get(n, job, a, b)
if nargin == 2
    i = ctmethods(30, n, job);
elseif nargin == 3
    i = ctmethods(30, n, job, a);
else
    i = ctmethods(30, n, job, a, b);
end

As is immediately clear, it's pretty hard to know what's going on (everything is handled by a single interface: ctmethods). Overall, it illustrates that everything that is done is governed by magic numbers that ensure that clib knows what to do.

To look into details for this example: per ctmethods.cpp, the 30 corresponds to const int PHASE_CLASS = 30;, which then redirects to a call phasemethods(nlhs, plhs, nrhs, prhs);, which then calls into clib via iok = thermo_setDensity(ph,*ptr); (note that the job id is 2!) as CANTERA_CAPI int thermo_setDensity(int n, double rho); (see cantera/include/cantera/clib/ct.h). Finally, in cantera/src/clib/ct.cpp, you see that this calls ThermoCabinet::item(n).setDensity(rho);, which finally links to the underlying C++ object.

In short: the current MATLAB interface has no idea that the Cantera core code uses objects at all. Interactions use magic numbers and integer object ID's, which is not intuitive and hard to expand on and/or to maintain. It would be obviously much easier to interact with C++ objects directly; it probably would also make sense to move the syntax to something that is clearly recognizable as an object-oriented approach, e.g. allowing for the rho0 = gas.density mentioned above (while properly deprecating the old syntax).

The way forward has two main options:

1. Map the C++ structure to MATLAB (in a similar fashion as what is already done for Python). This means that any change in C++ would require an update of the interface.
2. Use code generation to automatically create the interface (@speth has some comments to that end in Use code generation to provide interfaces for C, Fortran, Matlab, Julia, etc. #39)

[bryanwweber]

while properly deprecating the old syntax

I suspect that deprecation is going to mean having the existing and the new interfaces simultaneously present and removing the old one at some point in the future, similar to what was done for the Python interface

[ischoegl]

[...] similar to what was done for the Python interface

Hopefully less intrusive, as the change from Python 2 Cantera to Python 3 cantera was breaking. (I lost a lot of code.) Edit: I believe the new interface could provide for the old syntax with appropriate deprecation warnings.

[bryanwweber]

Hopefully less intrusive

Hopefully, but IMO this should be a lower priority than generating maintainable code.

[decaluwe]

Agreed - there are some pretty drastic changes that imho are on the table (including making the matlab interface function calls the same as the python, which would break... well, everything) that would be super-painful but are still worth considering, if they make for a more useful Matlab interface for the users, long-term.

[ischoegl]

there are some pretty drastic changes that imho are on the table (including making the matlab interface function calls the same as the python, which would break... well, everything) that would be super-painful but are still worth considering, if they make for a more useful Matlab interface for the users, long-term.

👍 ... couldn't agree more. Making the interfaces as similar as possible would be great indeed.

At the same time, backporting the new interface to the old syntax would be trivially easy, so users would have a smooth (non-breaking) transition. Be that as it may, the most difficult task here is how to access the C++ core from MATLAB.

[ischoegl]

4. Another way is to re-write each C++ function into MEX which obviously we are not going to do. But one major advantage of coding in MEX is that it could use MATLAB's powerful vectorization capability to drastically speed up vector and matrix operations (I'm seeing at least 10x and potentially more with GPU). On the other hand MATLAB is extremely slow with sequential operations (like FOR loops). Is there some part of cantera that could benefit from parallelization but could not be easily vectorized in C++? If so then I think at least these could benefit from having a native MEX code for MATLAB to call directly.

This depends. You are absolutely correct that loops have to be avoided at all cost (I believe the speedups are even larger than what you reported). For handling of multiple states, have a look at Python SolutionArray, which is how this is handled there. Unfortunately there isn't a native C++ implementation for this yet. There are probably applications beyond, so there is room for discussion.

[ischoegl]

3. Is there a self-contained module of cantera that I could use to test direct C++ integration? Currently I'm working with a very small experimental library I wrote myself (only two header files) which doesn't give me a good idea of the complexity and scale of integrating a large library.

I would assume yes, although I'm not familiar with MATLAB's C++ integration. For a general approach, look at Makefile / SConstruct content for C++ examples in the cantera/samples/cxx folder. You'd presumably tap into the same libraries / headers for a C++ integration. Details may be to some extent compiler / OS dependent.

[ischoegl]

FWIW, relinking a proof of concept posted some time ago (see #32). While this is apparently still calling clib, it does access the shared library directly. There may be some limitations for shared libraries for C++ symbols on windows systems (I believe there need to be some __declspec(dllexport) decorations in the main code), but I am not sufficiently familiar with those details and whatever remarks I recall may not apply here.

[rwest]

Just wanted to cross-link Ingmar's comment on another thread, which seems relevant: #97 (reply in thread)

[speth]

• Is there a self-contained module of cantera that I could use to test direct C++ integration? Currently I'm working with a very small experimental library I wrote myself (only two header files) which doesn't give me a good idea of the complexity and scale of integrating a large library.

I would say start with trying to wrap the classes Solution and ThermoPhase, and the newSolution factory function, and see if you can wrap and use a few member functions of a ThermoPhase object (accessible using the thermo() method of the Solution object. The potential pitfall of using the direct C++ integration is what happens when you find something that's not supported by Matlab. I know that the initial version of this capability said that it didn't include things like smart pointers and std::vector, both of which Cantera makes extensive use of.

[ischoegl]

Linking MATLAB C++ limitations and their workaround pages.

[speth]

Thanks for that link, @ischoegl. A couple of things that are on that list that we use somewhat frequently are std::unique_ptr and std::map.

[rwest]

As this is going to be a backwards-compatibility-breaking API change for MATLAB, I'm wondering what we should do when different interfaces behave differently. Should we try to "unify" them to make them more similar?

For example, setting mole fractions with and without normalization.

MATLAB (currently) there is a single function
setMoleFractions(thermophase, x, norm)
with an optional parameter norm which you can set to 'nonorm' to turn off normalization.
This could be updated to modern class method with minimal changes as thermophase.setMoleFractions(x, norm)

This goes via the C API, where there is a single method thermo_setMoleFractions(int n, size_t leny, double* y, int norm)
where norm is 1 for normalize and 0 don't normalize.

But in Python,
X will set the mole fractions, normalizing them. eg. phase.X = [0.1, 0.4, 0].
And there is a separate method set_unnormalized_mole_fractions to set without normalization: thermophase.set_unnormalized_mole_fractions([0.2, 0.8, 0])

These correspond to (and call directly, via Cython) the two C++ methods Phase::setMoleFractions(const double* const x) and Phase::setMoleFractions_NoNorm(const double* const x)

So MATLAB and C have a single method with a "norm" parameter (in one case a string, in the other an integer), but Python and C++ have two different methods.

If we're aiming for a code-generation approach to interfaces (the MATLAB and potentially Fortran) then presumably a one-to-one mapping of methods would be simplest. But mapping to the C interface or mapping to the C++ interface? (And if mapping to the C interface, should this example case use 0 and 1 or unspecified or any random stuff and 'nonorm' ?)
Should there be emphasis on making all the pseudocode look more similar so documentation and tutorials are easier to write.... ? We probably don't want to be breaking existing APIs (eg the Cython one) without very good reason.

[ischoegl]

@bryanwweber ... thanks for providing context. I (occasionally) had to deal with the MATLAB/C-API and the magic-number based approach is indeed a major pain as everything disappears into a black hole (aka ctmethods). Further, interacting with C++ objects via clib is cumbersome, which would make C++ much easier.

There are indeed limitations in MATLAB, but at least they now offer something that acts like a class in the true sense (not just the folder/file based patchwork from ages ago). Which takes me back to the main concern voiced at the top: different interfaces. Most new Cantera users have a limited background in programming, so the interface is what ultimately counts. Python has created a pretty nice/complete interface at this point, and I believe it's a good template. I'd hate to go back to limitations that are imposed by a C-API that hasn't seen as much work over the years.

Regarding code generation: there is #39 ... but there wasn't much else. It's a worthwhile goal, although getting this right will be non-trivial (documentation, etc.).

[ssun30]

Unfortunately, MATLAB's support for direct C++ interfacing is quite limited as @speth mentioned. So I don't see how to avoid the C-API entirely. One of the things that may not be discussed in this issue at the moment (in part because the work has taken place with a few different students over the last 3-5 years) is whether to directly load the shared object file, or run through a MEX wrapper. Unfortunately, there also seem to be inherent limitations with directly loading the SO (I don't recall exactly what they are at the moment), such that the MEX wrapper is really the best choice.

https://www.mathworks.com/help/matlab/matlab_external/limitations-to-shared-library-support.html
Here is a link to limitations to C shared library in Matlab. I was wary about incompatibility with function pointers and multilevel pointers. The benefit of MEX interface is that the only thing it does is passing data between Matlab and C API so it won't have any compatibility issues. The direct C interface is kind of a black box. That's why I didn't go for it.

That being said I don't see (at least for now) the current cantera_shared.lib violating any of the limitations listed in that link. It works in Matlab and the functions I've tried all work as expected. Since there's only a one-line difference between the direct call approach and the MEX approach in the Matlab script, I've made both variants for Matlab if we decide the direct C interface indeed won't have future compatibility concerns. I would love that to be the case since we could do away with the MEX interface altogether.

[ischoegl]

@ssun30 … Thanks for the clarification - I truly appreciate it. I realize that you probably have run quite a few tests at this point, and from what I can see, there is a desire to keep different interfaces as similar as possible, which is ultimately what counts. I don’t think I have anything to add beyond. All the best, and I am looking forward to this contribution!

[speth]

So I don't see how to avoid the C-API entirely

The MEX function is just a function that is defined as having a C-style linkage. It can contain C++ code as long as that function is defined in an extern "C" { block. Right now, the Matlab interface calls the C interface, but I'm not sure that's actually simpler than just calling the C++ objects directly. The main issues that you have to deal with either way are converting data types -- strings are frequently the biggest pain here -- and catching all C++ exceptions and translating those to Matlab errors. It may be the case at this point that Matlab does have more useful functions for, say, converting std::string to a Matlab string type that would be useful.

What I've been pushing for is write a description of what a Cantera language interface contains in YAML, and use that to generate both the C and Matlab interfaces (as a start). Whether or not the Matlab interface operates through the C interface at that point is more or less irrelevant.

[rwest]

Does Matlab have "setters" in the same way as Python, e.g. gas.X = ...? And if so, would setting the state that way be considered idiomatic in modern Matlab? I think that's the first-order concern in what that interface should look like.

I think so, which is good news (in terms of making the MATLAB inteface similar to the Python interface, which is the current favorite interface) https://www.mathworks.com/help/matlab/matlab_oop/property-set-methods.html

[ssun30]

Here is a link to the Cantera Lite proof of concept: https://github.com/comocheng/CanteraLite.

[bryanwweber]

@ssun30 I'm curious why this is a whole new repository, instead of a new interface in the existing Cantera repository?

[ssun30]

Originally it was only supposed to be tested on a limited scale (with a small subset of Cantera). But now that it includes the full Cantera library it makes sense to make it a new interface in the existing Cantera repository.

[ssun30]

Here's the first proof-of-concept toolbox for testing:
https://github.com/ssun30/enhancements/tree/Matlab_Direct-C

This version of the toolbox directly loads cantera_shared.dll using Matlab's calllib feature. All functions are called directly from the C library. A readme file is included in the 'Utility' folder.

As for using MEX, it is possible to completely get rid of the magic numbers if instead of one MEX interface (ctmethods) encompassing all methods we just make a bunch of individual MEX functions that are private to each class in Matlab. It's just a convention in MEX programming to have a centralized interface routine calling computational routines but doesn't have to be that way.

I've been struggling with compiling MEX code in Matlab (using the built-in mex command and MinGW64). It's frequently throwing the error that it couldn't find the directory of all the dependent header files. How is the current ctmethods MEX file compiled?

[ischoegl]

Fwiw, I noticed that there is now a GH matlab-action that should be useful for testing purposes.