Re-implement the Matlab interface

[bryanwweber]

Idea

We currently have a MATLAB interface to the C++ core library, based on the mex extension interface, but it is difficult to maintain. We would like to look at ways of replacing this interface. Options under consideration include using the loadlibrary interface to more directly call Cantera's C wrapper functions, by using MATLAB to import/call the Python interface, or by using the direct C++ support in MATLAB (added in R2019a, https://www.mathworks.com/help/releases/R2019a/matlab/call-cpp-library-functions.html).

In all of these cases, we would like to support some level of autogeneration of the interface to help maintainability.

Other tasks:

• Redesign the interface using new-style classes, and use the 'loadlibrary' interface to the Cantera library instead of the 'ctmethods' MEX interface. Proof of concept
• Eliminate the incomplete Matlab 1D toolbox
• Make the Matlab test suite more comprehensive (ideally as part of redesigning the Matlab interface)

Difficulty

Hard

Required Knowledge

C/C++/Matlab or Matlab/Python, depending on which option is pursued

Mentors

@decaluwe

References

Related issues link at Cantera/cantera. Supersedes #7.

[ischoegl]

As a friendly amendment, I am providing more detail to “import/call the Python interface” (copied verbatim from #7)

Completely replace the existing CLIB solution with a solution where MATLAB calls Python instead of a compiled MEX function that is routed through a C layer. This will require a complete rewrite of MATLAB classes to wrap the interface, preferably using the modern implementation of MATLAB classes.

[bryanwweber]

Thanks for the links Ingmar and for copying them here!

[speth]

I would strongly recommend the approach laid out in #39, which would help keep all of the language interfaces feature-complete.

[speth]

While the initial advocacy for using loadlibrary was mine, I'm less convinced of that solution at present. For one, it seems to still require a compiler to be present and uses that on the fly, which I suspect will be a source of errors depending on how users' systems are configured. In addition, I think it would be impossible to implement some of the "callback" type functionality which should be possible with the mex interface that would allow us to reduce reliance on the Func1 class for user-supplied functions, like what has been done in the Python interface.

Calling the Python package is an interesting idea, but I am concerned about the difficulty for users of configuring this all the parts correctly. You can see how often this occurs by searching the Users' Group for ct2ctml_string -- someone posts about it at least every couple of months, and I'm sure there are many more users who have problems but never get as far as posting about them.

[ischoegl]

As a very brief summary of how MATLAB could use Cantera's Python interface, I am attaching the following code snippet:

% MATLAB is started from within a conda environment
% with Cantera installed

% load Cantera's Python module
ct = py.importlib.import_module("cantera");

% create solution object
gas = ct.Solution('gri30.cti');

% obtain number of species - returns Python int
gas.n_species

% number of species in default MATLAB numeric format
double(gas.n_species)

% mole fractions - returns Python ndarray
gas.X

% mole fractions in native MATLAB (one of several ways)
double(py.array.array('d', py.numpy.nditer(gas.X)))

I.e. the only difference are number formats, which should be relatively straight-forward to handle. MATLAB can create class methods dynamically, so there may be a way to automatically generate all required wrappers (maybe based on Python PEP 484 __annotations__?).

[ischoegl]

@rwest … I believe this is now becoming work-in-progress?

[rwest]

Yes, thanks for bringing this issue and discussion to my attention! Tagging @ssun30 who is undertaking this work.

[ssun30]

I've been experimenting with MATLAB's direct C++ integration recently. It should be a lot easier to maintain and faster to run than the current approach using a MEX interface.

[ischoegl]

The current implementation has quite a few limitations; I believe that auto-generation as well as a modern class structure would be ideal. If you want to engage the community in your work, I’d recommend opening a discussion.

[rwest]

Just linking this enhancement issue to discussion #102 (because I came here looking for what is in fact over there)

[ssun30]

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