Roadmap for Code Generation in CLib API

[ischoegl]

This issue aims to track the progress of the C interface portion of #39 with the objective of a complete transition as early as Cantera 3.2. The traditional CLib interface has been declared experimental in 3.1, while a first replacement prototype was discussed in #39 (comment), although it only created header files.

The roadmap involves the following:

• Create working proof-of-concept for a clib-experimental API ... see Experimental clib from doxygen cantera#1835
• Add remaining access functions and unit tests to reach parity with the traditional CLib API:
  • ThermoPhase, Kinetics and Transport … see Autogenerated clib core objects cantera#1842
  • Implement access to C++ class member variables (needed for port of ctrpath) ... see Sourcegen CLib edge cases cantera#1846
  • Implement remaining APIs for zeroD and oneD
  • Move sourcegen README.md file contents to main documentation (to a page in doc/sphinx/develop so we can have this as part of the HTML documentation and information on how Cantera works in one place).
• Switch dependent APIs to clib-experimental (most functions will have drop-in replacements but include '3' in their name to avoid duplicate symbols):
  • .NET (no change of current approach for code generation)
  • experimental MATLAB (no code generation)
• Rename clib_experimental to clib3 and deprecate (or remove?) the traditional CLib interface. Potentially move clib folder to interfaces. Docstrings should retain the experimental admonition until the API is fully stable (likely in Cantera 3.3).
• Devise SCons/doxygen mechanism so auto-generated CLib docstrings become available in the documentation
• Add new components not available in the traditional CLib, e.g. SolutionArray

[ssun30]

Hi @ischoegl , while the clib revamp is will WIP, is there anything we can do on the MATLAB side to prepare for the switch to code generation for future interfaces? I've listed some near-term goals here: https://github.com/comocheng/wiki/issues/837

[ischoegl]

Hi @ischoegl , while the clib revamp is will WIP, is there anything we can do on the MATLAB side to prepare for the switch to code generation for future interfaces? I've listed some near-term goals here: https://github.com/comocheng/wiki/issues/837

Hi @ssun30 ... thanks for the note! At the moment, having a relatively complete MATLAB test suite is by far the most beneficial step. Regarding the link to your wiki, I cannot view as it may not be part of the public repo? (or it could be a typo)

[ssun30]

Hi @ischoegl , while the clib revamp is will WIP, is there anything we can do on the MATLAB side to prepare for the switch to code generation for future interfaces? I've listed some near-term goals here: comocheng/wiki#837

Hi @ssun30 ... thanks for the note! At the moment, having a relatively complete MATLAB test suite is by far the most beneficial step. Regarding the link to your wiki, I cannot view as it may not be part of the public repo? (or it could be a typo)

Sorry, our group kanban is indeed private. But here are what I covered over there:

Cantera devs have created a road map for code generation for Cantera clib: #220

While we will have to wait for the new experimental clib to become official, several changes on our part could be implemented concurrently:

• Change the Matlab interface to the new C/C++ interface?
• Change the library called by Matlab to the experimental clib now that it's feature complete.

Some ideas that may be implemented for code generation in Matlab:

• Proof-of-concepts automated generation for property getters/setters (lowest hanging fruit).
• Use inputParser to handle methods with variable input arguments. This should make complex methods more "codegen friendly".

[ischoegl]

Sorry, our group kanban is indeed private. But here are what I covered over there [...]

Thanks, @ssun30. From what I understand, the MATLAB C++ interface was far from feature-complete in terms of C++ standards, which is why it hadn't been a workable solution. I'm not sure what has changed since, but the experimental CLib can be used for a feature-complete Cantera API once it's done.

For code generation for MATLAB, the sourcegen approach used by Cantera would be relatively straightforward to implement. I agree that some property getters/setters are the lowest-hanging fruit.