[MATLAB] Migrate to generated Clib #1997

ssun30 · 2025-10-05T19:43:37Z

Changes proposed in this pull request

This PR updates the experimental MATLAB interface to use the auto-generated Cantera Clib (produced via sourcegen), replacing the previously manually written Clib.

Specifically, this PR:

Updates the interface generation workflow to consume the auto-generated Clib headers instead of the manually curated set.
Adjusts MATLAB definition generation to reflect updated function and class names in the new Clib.
Removes redundant edge-case handling in ctEditLibraryDefinitions that was only required for the manually written Clib.
Re-enables several MATLAB unit tests that were previously excluded due to missing API functions in the old Clib.

Checklist

The pull request includes a clear description of this code change
Commit messages have short titles and reference relevant issues
Build passes (scons build & scons test) and unit tests address code coverage
Style & formatting of contributed code follows contributing guidelines
The pull request is ready for review

ssun30 · 2025-10-05T19:57:30Z

Hi @ischoegl , I've started migrating the MATLAB interface to the generated Clib. It won't work with the generated Clib as-is due to the following two points:

Only ct.h includes <stdint.h>, but several other generated headers in cantera_clib also declare functions using int32_t.
When the MATLAB interface generator (clibgen.generateLibraryDefinition) parses these headers individually, compilation fails with:

/Users/ssun30/cantera/interfaces/clib/include/cantera_clib/ctconnector.h(139): 
error: identifier "int32_t" is undefined'

On my local machine, I got around this issue by adding <stdint.h> to other header files.

Several function docstrings in ct.h contain the substring %Cantera, for example, in ct_version:

/**
 * Returns the %Cantera version.
 */

MATLAB’s clibgen treats % as a comment character in MATLAB syntax. During parsing, the line is truncated at %, producing an unterminated string in the generated definectMatlab.m file and causing:

Error: String is not terminated properly.

Affected functions:
ct_version
ct_gitCommit
ct_getDataDirectories
ct_make_warnings_fatal
ct_getCanteraError

On my local machine, I got around this issue by removing the % symbol from %Cantera.

ischoegl · 2025-10-05T22:49:40Z

@ssun30 ... I pushed some fixes. I can compile things without needing to edit on my machine, and the toolbox loads, but the unit tests fail. Please ensure that you reset your local branch to this one to preserve my edits.

codecov · 2025-10-05T23:30:29Z

Codecov Report

❌ Patch coverage is 0.76336% with 130 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.15%. Comparing base (3e99c4e) to head (63b6408).

Files with missing lines	Patch %	Lines
interfaces/matlab_experimental/Base/ThermoPhase.m	0.00%	21 Missing ⚠️
interfaces/matlab_experimental/Base/Kinetics.m	0.00%	15 Missing ⚠️
interfaces/matlab_experimental/Func/Func1.m	0.00%	15 Missing ⚠️
interfaces/matlab_experimental/OneDim/Domain1D.m	0.00%	9 Missing ⚠️
interfaces/matlab_experimental/Base/Mixture.m	0.00%	8 Missing ⚠️
...ces/matlab_experimental/cantera/ctBuildInterface.m	0.00%	8 Missing ⚠️
interfaces/matlab_experimental/Base/Transport.m	0.00%	6 Missing ⚠️
interfaces/matlab_experimental/Base/Solution.m	0.00%	5 Missing ⚠️
interfaces/matlab_experimental/OneDim/Flow1D.m	0.00%	5 Missing ⚠️
interfaces/matlab_experimental/Base/Interface.m	0.00%	4 Missing ⚠️
... and 25 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1997      +/-   ##
==========================================
- Coverage   75.42%   73.15%   -2.27%     
==========================================
  Files         454      466      +12     
  Lines       56554    56527      -27     
  Branches     9334     9333       -1     
==========================================
- Hits        42654    41353    -1301     
- Misses      10746    12029    +1283     
+ Partials     3154     3145       -9

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

ssun30 · 2025-10-08T23:30:27Z

@ssun30 ... I pushed some fixes. I can compile things without needing to edit on my machine, and the toolbox loads, but the unit tests fail. Please ensure that you reset your local branch to this one to preserve my edits.

Hi @ischoegl , I've fixed most of the issues with the unit tests. But five tests remain and I'll list each of them:

sample ignite.m

Unable to resolve the name 'clib.ctMatlab.kin_getSourceTerms'.

Error in [ctArray](matlab:matlab.lang.internal.introspective.errorDocCallback('ctArray', '/Users/ssun30/cantera/interfaces/matlab_experimental/Utility/ctArray.m', 6)) ([line 6](matlab: opentoline('/Users/ssun30/cantera/interfaces/matlab_experimental/Utility/ctArray.m',6,0)))
    iok = clib.ctMatlab.(funcName)(varargin{:}, buf);
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Error in [Kinetics/get.massProdRate](matlab:matlab.lang.internal.introspective.errorDocCallback('Kinetics/get.massProdRate', '/Users/ssun30/cantera/interfaces/matlab_experimental/Base/Kinetics.m', 458)) ([line 458](matlab: opentoline('/Users/ssun30/cantera/interfaces/matlab_experimental/Base/Kinetics.m',458,0)))
            ydot = ctArray('kin_getSourceTerms', nsp, kin.kinID);
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Error in [reactor_ode](matlab:matlab.lang.internal.introspective.errorDocCallback('reactor_ode', '/Users/ssun30/cantera/samples/matlab_experimental/reactor_ode.m', 44)) ([line 44](matlab: opentoline('/Users/ssun30/cantera/samples/matlab_experimental/reactor_ode.m',44,0)))
        ydt = total_mass * gas.massProdRate;

I didn't find the new equivalent function to kin_getSourceTerms in the generated clib.

ssun30 · 2025-10-08T23:31:40Z

The next sample is catacomb.m

Error using [clib.ctMatlab.domain_index](matlab:matlab.lang.internal.introspective.errorDocCallback('clib.ctMatlab.domain_index'))
No method 'clib.ctMatlab.domain_index' with matching signature found.

Error in [ctFunc](matlab:matlab.lang.internal.introspective.errorDocCallback('ctFunc', '/Users/ssun30/cantera/interfaces/matlab_experimental/Utility/ctFunc.m', 5)) ([line 5](matlab: opentoline('/Users/ssun30/cantera/interfaces/matlab_experimental/Utility/ctFunc.m',5,0)))
    output = clib.ctMatlab.(funcName)(varargin{:});
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Error in [Domain1D/get.domainIndex](matlab:matlab.lang.internal.introspective.errorDocCallback('Domain1D/get.domainIndex', '/Users/ssun30/cantera/interfaces/matlab_experimental/OneDim/Domain1D.m', 200)) ([line 200](matlab: opentoline('/Users/ssun30/cantera/interfaces/matlab_experimental/OneDim/Domain1D.m',200,0)))
            i = ctFunc('domain_index', d.domainID) + 1;
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Error in [Boundary1D/massFraction](matlab:matlab.lang.internal.introspective.errorDocCallback('Boundary1D/massFraction', '/Users/ssun30/cantera/interfaces/matlab_experimental/OneDim/Boundary1D.m', 81)) ([line 81](matlab: opentoline('/Users/ssun30/cantera/interfaces/matlab_experimental/OneDim/Boundary1D.m',81,0)))
            if d.domainIndex == 0
               ^^^^^^^^^^^^^
Error in [catcomb](matlab:matlab.lang.internal.introspective.errorDocCallback('catcomb', '/Users/ssun30/cantera/samples/matlab_experimental/catcomb.m', 144)) ([line 144](matlab: opentoline('/Users/ssun30/cantera/samples/matlab_experimental/catcomb.m',144,0)))
    y = inlt.massFraction(k);

The function signature for domain_index has changed:

    /**
     *  Returns the index of the solution vector, which corresponds to component n at grid point j.
     *
     *  Wraps C++ method: `size_t Domain1D::index(size_t, size_t)`
     *
     *  @param handle       Handle to queried Domain1D object.
     *  @param n            component index
     *  @param j            grid point index
     */
    int32_t domain_index(int32_t handle, int32_t n, int32_t j);

ssun30 · 2025-10-08T23:34:00Z

sample surf_reactor.m

Error using [ctFunc](matlab:matlab.lang.internal.introspective.errorDocCallback('ctFunc', '/Users/ssun30/cantera/interfaces/matlab_experimental/Utility/ctFunc.m', 10)) ([line 10](matlab: opentoline('/Users/ssun30/cantera/interfaces/matlab_experimental/Utility/ctFunc.m',10,0)))

*******************************************************************************
CanteraError thrown by Cabinet::as:
Item is not of the correct type.
*******************************************************************************

Error in [ReactorSurface/set.area](matlab:matlab.lang.internal.introspective.errorDocCallback('ReactorSurface/set.area', '/Users/ssun30/cantera/interfaces/matlab_experimental/Reactor/ReactorSurface.m', 56)) ([line 56](matlab: opentoline('/Users/ssun30/cantera/interfaces/matlab_experimental/Reactor/ReactorSurface.m',56,0)))
            ctFunc('reactor_setArea', s.id, a);
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Error in [surf_reactor](matlab:matlab.lang.internal.introspective.errorDocCallback('surf_reactor', '/Users/ssun30/cantera/samples/matlab_experimental/surf_reactor.m', 48)) ([line 48](matlab: opentoline('/Users/ssun30/cantera/samples/matlab_experimental/surf_reactor.m',48,0)))
rsurf.area = A;
^^^^^^^^^^

I didn't find the equivalent methods for reactorsurface_area and reactorsurface_setArea in the new clib.

ssun30 · 2025-10-08T23:39:11Z

The final errors are under ctTestThermo.m, in particular testElementalMassFraction and testNAtoms:

    --> The value does not contain the substring.
    
    Actual char:
        <no Cantera error
    Expected Substring:
        No such element

In the legacy clib, the thermo_elementIndex and thermo_speciesIndex methods have hard-coded error handling:

    size_t thermo_elementIndex(int n, const char* nm)
    {
        try {
             size_t k = ThermoCabinet::at(n)->elementIndex(nm);
             if (k == npos) {
                throw CanteraError("thermo_elementIndex",
                                   "No such element {}.", nm);
             }
             return k;
        } catch (...) {
            return handleAllExceptions(npos, npos);
        }
    }

Now the corresponding methods in the generated clib lack those checks, and thus no error message was returned.

Removed unnecessary edge case checks when editing library definitions.

generated clib.

standard class instead of hardcoded values.

ssun30 marked this pull request as draft October 5, 2025 19:43

ischoegl added the Matlab label Oct 5, 2025

ischoegl force-pushed the matlab_clibMigration branch from 2952e2c to c4ea8aa Compare October 5, 2025 23:03

ssun30 force-pushed the matlab_clibMigration branch from c4ea8aa to 0802ddd Compare October 8, 2025 23:23

ischoegl and others added 9 commits October 9, 2025 14:34

[sourcegen] Ensure int32_t is present in all headers

a2d1a0c

[sourcegen] Do not escape Cantera in \brief

632d7ce

[MATLAB] Added generated clib path requirement

005f582

Removed unnecessary edge case checks when editing library definitions.

[MATLAB] Renamed many functions to match the new

bc93a07

generated clib.

[MATLAB] Added physical constants from the ct

8eb1027

standard class instead of hardcoded values.

[MATLAB] Added new Cantera Error Code

ec627bc

[MATLAB] Fixed function names for generated clib

df2e5f1

[MATLAB] Fixed several tests

e711aea

[CI] Fix ctBuildInterface

63b6408

ssun30 force-pushed the matlab_clibMigration branch from 0802ddd to 63b6408 Compare October 9, 2025 18:34

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

[MATLAB] Migrate to generated Clib #1997

[MATLAB] Migrate to generated Clib #1997

Uh oh!

ssun30 commented Oct 5, 2025

Uh oh!

ssun30 commented Oct 5, 2025

Uh oh!

ischoegl commented Oct 5, 2025 •

edited

Loading

Uh oh!

codecov bot commented Oct 5, 2025 •

edited

Loading

Uh oh!

ssun30 commented Oct 8, 2025

Uh oh!

ssun30 commented Oct 8, 2025

Uh oh!

ssun30 commented Oct 8, 2025

Uh oh!

ssun30 commented Oct 8, 2025

Uh oh!

Uh oh!

Uh oh!

[MATLAB] Migrate to generated Clib #1997

Are you sure you want to change the base?

[MATLAB] Migrate to generated Clib #1997

Uh oh!

Conversation

ssun30 commented Oct 5, 2025

Uh oh!

ssun30 commented Oct 5, 2025

Uh oh!

ischoegl commented Oct 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Oct 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

ssun30 commented Oct 8, 2025

Uh oh!

ssun30 commented Oct 8, 2025

Uh oh!

ssun30 commented Oct 8, 2025

Uh oh!

ssun30 commented Oct 8, 2025

Uh oh!

Uh oh!

ischoegl commented Oct 5, 2025 •

edited

Loading

codecov bot commented Oct 5, 2025 •

edited

Loading