Issue with ctLoad on MacOS

[santoshshanbhogue]

Problem description
The experimental MATLAB toolbox has a few fixable bugs, that as of now lead to Cantera being installed incorrectly. The fix on my machine is to run the following commands before ctLoad

clibConfiguration('ctMatlab','ExecutionMode','inprocess')

(ctBuildInterface claims to do this, but it ends up not being the case)

Steps to reproduce

Run the following commands in the MATLAB editor:

ctSourceRoot = '/Users/santosh1/packages/canteraSource';
ctInstalledDir = '/Users/santosh1/packages/ct_dev_version/';

ctToolboxDir = fullfile(ctSourceRoot, "interfaces/matlab_experimental");

ctCLibIncludeDir = fullfile(ctInstalledDir,"include");
ctLibDir = fullfile(ctInstalledDir, "lib");

clc;
ctBuildInterface(ctToolboxDir, ctCLibIncludeDir, ctLibDir);

Paths used in the build process:
Cantera Toolbox Root: /Users/santosh1/packages/canteraSource/interfaces/matlab_experimental
Include Directory: /Users/santosh1/packages/ct_dev_version/include
Cantera Library: /Users/santosh1/packages/ct_dev_version/lib
Output Folder: /Users/santosh1/packages/canteraSource/interfaces/matlab_experimental/cantera
MEX configured to use 'Xcode Clang++' for C++ language compilation.
C++ compiler set to 'Xcode Clang++'.
Definition file definectMatlab.m contains definitions for 428 constructs supported by MATLAB.

• 324 constructs are fully defined.
• 104 constructs partially defined and commented out.

To include the 104 undefined constructs in the interface, uncomment and complete the definitions in definectMatlab.m.
To build the interface, call build(definectMatlab).
Building interface file 'ctMatlabInterface.dylib' for clib interface 'ctMatlab'.
Build Log:
/usr/bin/xcrun -sdk macosx26.0 clang++ -c -fno-common -arch arm64 -mmacosx-version-min=12.0 -fexceptions -isysroot /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX26.0.sdk -fwrapv -ffp-contract=off -fobjc-arc -std=c++14 -stdlib=libc++ -O2 -DNDEBUG -I"/Users/santosh1/packages/ct_dev_version/include" -I"/Applications/MATLAB_R2024b.app/extern/include" "/Users/santosh1/packages/canteraSource/interfaces/matlab_experimental/cantera/ctMatlab/ctMatlabInterface.cpp" -o "/Users/santosh1/packages/canteraSource/interfaces/matlab_experimental/cantera/ctMatlab/ctMatlabInterface.o"

/usr/bin/xcrun -sdk macosx26.0 clang++ -Wl,-twolevel_namespace -arch arm64 -mmacosx-version-min=12.0 -Wl,-syslibroot,/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX26.0.sdk -framework Cocoa -bundle -stdlib=libc++ "/Users/santosh1/packages/canteraSource/interfaces/matlab_experimental/cantera/ctMatlab/ctMatlabInterface.o" "/Users/santosh1/packages/ct_dev_version/lib/libcantera_shared.3.2.0.dylib" "/Applications/MATLAB_R2024b.app/extern/bin/maca64/libMatlabDataArray.dylib" -Wl,-rpath,@loader_path/ -O -o "/Users/santosh1/packages/canteraSource/interfaces/matlab_experimental/cantera/ctMatlab/ctMatlabInterface.dylib" -sectcreate __TEXT us_resources "/Users/santosh1/packages/canteraSource/interfaces/matlab_experimental/cantera/ctMatlab/ctMatlab.zip"

---

Interface file 'ctMatlabInterface.dylib' built in folder '/Users/santosh1/packages/canteraSource/interfaces/matlab_experimental/cantera/ctMatlab'.

To use the library, add the interface file folder to the MATLAB path.
addpath('/Users/santosh1/packages/canteraSource/interfaces/matlab_experimental/cantera/ctMatlab')
Execution mode 'ctMatlab' set to 'inprocess'. To modify, call clibConfiguration('ctMatlab','ExecutionMode','outofprocess').
 Copied 1 run-time library files to '/Users/santosh1/packages/canteraSource/interfaces/matlab_experimental/cantera/ctMatlab'
/Users/santosh1/packages/ct_dev_version/lib/libcantera_shared.3.2.0.dylib

 Run-time dependencies copied to interface library folder.

clibConfiguration("ctmatlab")

ans =

  CLibraryConfiguration for ctmatlab with properties:

InterfaceLibraryPath: "/Users/santosh1/packages/canteraSource/interfaces/matlab_experimental/cantera/ctMatlab/ctMatlabInterface.dylib"
           Libraries: "libcantera_shared.3.2.0.dylib"
              Loaded: 0
       ExecutionMode: inprocess

ctLoad
Unable to load interface library:
'/Users/santosh1/packages/canteraSource/interfaces/matlab_experimental/cantera/ctMatlab/ctMatlabInterface.dylib'.
Reason: The specified module could not be found.
Ensure the C++ dependent libraries for the interface library are added to run-time path.

Error in ctString

Error in ctVersion (line 9)
v = ctString('ct_version');
^^^^^^^^^^^^^^^^^^^^^^
Error in ctLoad (line 32)
fprintf('Cantera %s is ready for use (%s mode).\n', ctVersion, mode);
^^^^^^^^^
Related documentation

ctLoad('inprocess')
Unable to load interface library:
'/Users/santosh1/packages/canteraSource/interfaces/matlab_experimental/cantera/ctMatlab/ctMatlabInterface.dylib'.
Reason: The specified module could not be found.
Ensure the C++ dependent libraries for the interface library are added to run-time path.

Error in ctString

Error in ctVersion (line 9)
v = ctString('ct_version');
^^^^^^^^^^^^^^^^^^^^^^
Error in ctLoad (line 32)
fprintf('Cantera %s is ready for use (%s mode).\n', ctVersion, mode);
^^^^^^^^^
Related documentation

clibConfiguration('ctMatlab','ExecutionMode','inprocess')

ans =

  CLibraryConfiguration for ctMatlab with properties:

InterfaceLibraryPath: "/Users/santosh1/packages/canteraSource/interfaces/matlab_experimental/cantera/ctMatlab/ctMatlabInterface.dylib"
           Libraries: "libcantera_shared.3.2.0.dylib"
              Loaded: 0
       ExecutionMode: inprocess

ctLoad
Cantera 3.2.0a5 is ready for use (outofprocess mode).
gas = Solution('gri30.yaml')

gri30:

   temperature   300 K
      pressure   1.0133e+05 Pa
       density   0.081894 kg/m^3

mean mol. weight 2.016 kg/kmol
phase of matter gas

                      1 kg             1 kmol     
                 ---------------   ---------------
      enthalpy             26469             53361  J

internal energy -1.2108e+06 -2.441e+06 J
entropy 64910 1.3086e+05 J/K
Gibbs function -1.9447e+07 -3.9204e+07 J
heat capacity c_p 14311 28851 J/K
heat capacity c_v 10187 20536 J/K

                  mass frac. Y      mole frac. X     chem. pot. / RT
                 ---------------   ---------------   ---------------
            H2                 1                 1           -15.717
 [  +52 minor]                 0                 0  

Behavior

System information

• Cantera version: 2054d5e
• OS: Mac OS 15.6.1
• Python/MATLAB/other software versions: Python 3.10.19
• MATLAB 2024b

Attachments

Additional context

[ischoegl]

@santoshshanbhogue ... I cannot reproduce it on my macOS installation. Did you add the folders, i.e.

cantera/interfaces/matlab_experimental/README.md

Lines 32 to 46 in 274cad3

	3. **Add toolbox to MATLAB path**
	* **Windows/MacOS:** Launch MATLAB, navigate to the toolbox folder using *Browse for Folder*, and add it (including subfolders) to the MATLAB search path.
	Example:
	```
	/path/to/cantera/interfaces/matlab_experimental
	```
	* **Linux:** Configure MATLAB to use the system C++ library instead of MATLAB’s built-in version:
	```bash
	export LD_PRELOAD=/path/to/system/C++/library
	```
	Then launch MATLAB and add the toolbox path as above.

[santoshshanbhogue]

@ischoegl yes I did. I just double checked my path. Why I feel there is a bug is because, if I open up MATLAB afresh and run these commands with a breakpoint in Line 22, see the output. I am explicitly loading ctLoad via:

ctLoad('inprocess')

yet, within ctLoad.m it shows the mode as 'outofprocess'. The sequence of commands that reproduce this behavior is below. Notice the 'outofprocess' mode despite my explicity request. Hence my suggestion that if a user executes ctLoad and gets the error, they should rerun clibConfiguration('ctMatlab','ExecutionMode','inprocess')

ctLoad
Unable to load interface library:
'/Users/santosh1/packages/canteraSource/interfaces/matlab_experimental/cantera/ctMatlab/ctMatlabInterface.dylib'.
Reason: The specified module could not be found.
Ensure the C++ dependent libraries for the interface library are added to run-time path.

Error in ctString

Error in ctVersion (line 9)
v = ctString('ct_version');
^^^^^^^^^^^^^^^^^^^^^^
Error in ctLoad (line 32)
fprintf('Cantera %s is ready for use (%s mode).\n', ctVersion, mode);
^^^^^^^^^
Related documentation

clibConfiguration("ctmatlab")

ans =

  CLibraryConfiguration for ctmatlab with properties:

InterfaceLibraryPath: "/Users/santosh1/packages/canteraSource/interfaces/matlab_experimental/cantera/ctMatlab/ctMatlabInterface.dylib"
           Libraries: "libcantera_shared.3.2.0.dylib"
              Loaded: 0
       ExecutionMode: inprocess

ctLoad("inprocess")
22 global ct
K>> ct

ct =

  CLibraryConfiguration for ctMatlab with properties:

InterfaceLibraryPath: "/Users/santosh1/packages/canteraSource/interfaces/matlab_experimental/cantera/ctMatlab/ctMatlabInterface.dylib"
           Libraries: "libcantera_shared.3.2.0.dylib"
              Loaded: 0
       ExecutionMode: outofprocess

[ischoegl]

This is odd. I see

>> ctLoad('inprocess')
Cantera 3.2.0a5 is ready for use (inprocess mode).
>> gas = Solution('gri30.yaml')

  gri30:

       temperature   300 K
          pressure   1.0133e+05 Pa
           density   0.081894 kg/m^3
  mean mol. weight   2.016 kg/kmol
   phase of matter   gas

                          1 kg             1 kmol     
                     ---------------   ---------------
          enthalpy             26469             53361  J
   internal energy       -1.2108e+06        -2.441e+06  J
           entropy             64910        1.3086e+05  J/K
    Gibbs function       -1.9447e+07       -3.9204e+07  J
 heat capacity c_p             14311             28851  J/K
 heat capacity c_v             10187             20536  J/K

                      mass frac. Y      mole frac. X     chem. pot. / RT
                     ---------------   ---------------   ---------------
                H2                 1                 1           -15.717
     [  +52 minor]                 0                 0  

>> 

Your MATLAB version is older than mine, though.

[santoshshanbhogue]

There may be an ambiguity in my reply above. If I start MATLAB afresh and run ctLoad('inprocess'), then things work fine. But if I run MATLAB afresh, and

1. run ctLoad
2. I will get an error
3. run ctLoad("inprocess") I still get an error

Changing the code starting at

cantera/interfaces/matlab_experimental/Utility/ctLoad.m

Line 24 in 274cad3

if isMATLABReleaseOlderThan("R2025a") || strcmp(mode, "inprocess")

to the statements below fixes things for me

if isempty(ct)
    if isMATLABReleaseOlderThan("R2025a") || strcmp(mode, "inprocess")
        ct = clibConfiguration("ctMatlab", ExecutionMode=mode);
    else
        ct = clibConfiguration("ctMatlab", ExecutionMode=mode, ...
                               OutOfProcessEnvironmentVariables=pathVar);
    end
else
    if strcmp(mode, "inprocess")
        ct = clibConfiguration("ctMatlab", ExecutionMode=mode);
end

[ischoegl]

OK, I looked into this further and saw similar issues for subsequent unloading/loading, as ct will exist and nothing happens.

I believe this is fixed in #2031. Could you confirm?

Fwiw, I added a ctExecutionMode helper function, and get

>> ctUnload
Cantera has been unloaded
>> ctLoad
Cantera 3.2.0b1 is ready for use (outofprocess mode).
>> ctUnload
Cantera has been unloaded
>> ctLoad("inprocess")
Cantera 3.2.0b1 is ready for use (inprocess mode).
>> ctExecutionMode

ans = 

  [ExecutionMode](matlab:helpPopup('matlab.cppclient.ExecutionMode')) enumeration

    inprocess

[santoshshanbhogue]

@ischoegl what works is if I start MATLAB afresh and use ctLoad("inprocess") to load the toolbox

What doesn't work is if I start MATLAB afresh and simple execute ctLoad or ctLoad("outofprocess")
I think #2031 also changed the default execution mode when the toolbox is being compiled. Previously I think the default mode was "inprocess"

let me know if you want me to test anything else

[ischoegl]

outofprocess has been the default since #1868. What I found out in #2031 is that it's impossible to unload inprocess.

[santoshshanbhogue]

Ok, then looks like for MATLAB 2024b (or maybe some due to some bad configuring on my part) the only execution mode that works is inprocess. Not a big problem for me per se, as my main functional requirement for MATLAB is calculating gas properties, but for use with hardware with flow control. I do the computationally intensive stuff via python. Looking forward to see how the experimental toolbox performs

[ischoegl]

Interesting - I'll let @ssun30 chime in here.

[ischoegl]

Ok, then looks like for MATLAB 2024b (or maybe some due to some bad configuring on my part) the only execution mode that works is inprocess.

This looks like a bug, then. While I don't use MATLAB enough to know details, it appears that clibgen's In-process/out-of-process capability was introduced in R2023a, meaning that this should work.

The default is based on the arguments block in ctLoad:

    arguments
        mode (1,1) string {mustBeMember(mode, ...
                           ["inprocess", "outofprocess"])} = "outofprocess"
    end

In other words, if your MATLAB does something else, then there's an issue. Fwiw, I'm running on macOS on M2 chips with an ARM version of MATLAB; for that, things work.

[ssun30]

outofprocess has been the default since #1868. What I found out in #2031 is that it's impossible to unload inprocess.

Yes. Once Cantera is loaded in inprocess mode, you must restart MATLAB to unload it. Unloading is only supported for outofprocess mode. These are the intended behavior.

Ok, then looks like for MATLAB 2024b (or maybe some due to some bad configuring on my part) the only execution mode that works is inprocess. Not a big problem for me per se, as my main functional requirement for MATLAB is calculating gas properties, but for use with hardware with flow control. I do the computationally intensive stuff via python. Looking forward to see how the experimental toolbox performs

I think you hit an unintended behavior of ctLoad. The original intention was for MATLAB to automatically set the paths to the correct run-time libraries, according to this documentation.

During testing, I found that (on my Mac computer) the build script didn't create the necessary symbolic links to all the dependencies, an example is libMatlabDataArray, so when MATLAB tries to load it in outofprocess mode, the library could not be found. The user needs to specify the DYLD_LIBRARY_PATH. This is not an issue in inprocess mode since that specific library is loaded within the MATLAB process at launch.

The OutOfProcessEnvironmentVariables parameter for clibConfiguration will set the correct DYLD_LIBRARY_PATH but it's only introduced in R2025a. For older versions, users should set it manually but I missed that part in the README.

A quick fix should be:

DYLD_LIBRARY_PATH=matlabroot/bin/macos:matlabroot/sys/os/macos /matlabexecutable

Replace macos with either maca64 for macOS with Apple silicon or maci64 for macOS with Intel. Set matlabexecutable to the full path to the MATLAB_macos executable inside the MATLAB application bundle. An example of a full path is /Applications/MATLAB_R2023b.app/Contents/MacOS/MATLAB_maca64. (Skip this if you already created a symbolic link for the MATLAB executable).

run this in your terminal when launching MATLAB. Let me know if it fixes the issue.

This looks like a bug, then. While I don't use MATLAB enough to know details, it appears that clibgen's In-process/out-of-process capability was introduced in R2023a, meaning that this should work.

The default is based on the arguments block in ctLoad:

arguments
    mode (1,1) string {mustBeMember(mode, ...
                       ["inprocess", "outofprocess"])} = "outofprocess"
end

In other words, if your MATLAB does something else, then there's an issue. Fwiw, I'm running on macOS on M2 chips with an ARM version of MATLAB; for that, things work.

I think the build process needs to be made more robust by ensuring the symbolic links to libMatlabDataArray are created (and all dependencies in general). Before this is fixed we have to make sure the documentations are more clear with how paths are set.

I didn't get this problem on Windows and Linux because the MATLAB installer should have set the paths already, while the Mac installer dosen't.

[ssun30]

I also think we should make user aware that outofprocess mode can carry significant performance loss if their code makes repeated calls to properties especially arrays. Mathworks also mentioned in their documentation that inprocess mode should be used for performance critical use cases.

[santoshshanbhogue]

@ssun30 Thanks for the detailed explanation. I tried setting DYLD_LIBRARY_PATH and launched MATLAB from the same shell; confirmed that it is set via getenv. But that doesn't change things. I still see the error on my macOS with M1 chip

Its possible that my configuration may be a bit messed up. I'll update to MATLAB 2025 and see if that changes things

I'm comfortable with running it in "inprocess" mode especially since you mentioned that this mode has the least performance penalties. If you want me to run something for help with debugging, I'll be happy to do so