Generated MATLAB API

[ischoegl]

Abstract

With the adoption of the generated CLib in Cantera/cantera#1997, it will become possible to generate large portions of the MATLAB API using sourcegen.

Motivation

Describe the need for the proposed change:

• What problem is it trying to solve? ... automatically expose C++ features to MATLAB
• Who is affected by the change? ... MATLAB users
• Why is this a good solution? ... Avoid hand-coding of repetitive methods; docstrings would be added automatically.

Possible Solutions

The following steps would be necessary.

• Ensure that function/method nomenclatures in C++ and MATLAB are consistent
• Ensure that C++ \brief docstrings are appropriate.
• Convert existing MATLAB class definitions to Jinja2 templates (.j2), where applicable
• Add a sourcegen generator to automatically fill in exposed member functions; note that MATLAB toolbox changes CLib signatures cantera#2006 needs to be addressed in some form - the logic in ctEditLibraryDefinitions and sourcegen needs to be consistent.

Example: The Transport.m.j2 file could look as follows:

classdef Transport < handle
    %  Class docstring is MATLAB specific (i.e., not generated)

    properties (SetAccess = protected)

        th % ID of the ThermoPhase object used to create the Transport object.

        trID % ID of :mat:class:`Transport` object.

        {{ protected_properties }}

    end

    properties (SetAccess = public)

        {{ public_properties }}

    end

    methods
        %% Transport Class Constructor

        function tr = Transport(id)
            % Create a :mat:class:`Transport` object.
            ctIsLoaded;

            if ~isnumeric(id)
                error('Invalid argument: constructor requires integer solution ID.')
            end

            tr.trID = ctFunc('soln_transport', id);
            tr.th = ctFunc('soln_thermo', id);
        end

        %% Transport Get Methods

        {{ getter_methods }} 

        %% Transport Set Methods

        {{ setter_methods }} 

        %% Transport Methods

        {{ generic_methods }} 

    end

end

References

• Use code generation to provide interfaces for C, Fortran, Matlab, Julia, etc. #39
• Improve Consistency of Thermo Property Interfaces #219
• To-do List for releasing the MATLAB interface on File Exchange #226 (comment)
• [MATLAB] Migrate to generated Clib cantera#1997
• MATLAB toolbox changes CLib signatures cantera#2006

PS: tagging @ssun30 and @rwest.