Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Matlab toolbox revamp #1182

Merged
merged 65 commits into from
May 11, 2023
Merged

Matlab toolbox revamp #1182

merged 65 commits into from
May 11, 2023

Conversation

ssun30
Copy link
Contributor

@ssun30 ssun30 commented Jan 21, 2022

Changes proposed in this pull request

  • Change the Matlab interface to the modern Matlab structure and syntaxes for OOP.
  • Replace MEX interface with directly calling from Cantera Clib.
  • Re-adapt examples to the new interface.

If applicable, fill in the issue number this pull request is fixing

Closes Cantera/enhancements#32

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 ssun30 closed this Jan 21, 2022
@ssun30 ssun30 reopened this Jan 24, 2022
@ssun30 ssun30 changed the title Matlab toolbox Matlab toolbox revamp (WIP) Jan 24, 2022
@bryanwweber bryanwweber marked this pull request as draft January 24, 2022 22:40
@bryanwweber
Copy link
Member

@ssun30 I converted this to a "draft" pull request since you put WIP in the title. If that wasn't correct, please feel free to click the "Ready for review" button near the bottom of the page (right above the "Checks" box) whenever you want us to take a detailed look at this 😄

@ischoegl
Copy link
Member

Linking #379

Copy link
Member

@ischoegl ischoegl left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @ssun30 ... great to see this moving along! While this is still WIP, I decided to leave a brief comment as I'm not sure that the automatic figure generation should make it into the updated toolbox.

Beyond, there are missing empty lines at the end of many files, as well as some spurious Windows line-breaks (shown below as ^M) that you're likely already aware of. There likely is a setting in your code editor that can take care of these minor formatting issues. I'm definitely looking forward to seeing the final PR!

PS: I’m also not certain that the XML_node.m needs to be implemented as XML/CTI is completely replaced by YAML, with the former being discontinued after the 2.6 release.

interfaces/Matlab_Toolbox_Revamp/Class/Kinetics.m Outdated Show resolved Hide resolved
interfaces/Matlab_Toolbox_Revamp/Class/Kinetics.m Outdated Show resolved Hide resolved
@rwest
Copy link
Member

rwest commented Feb 16, 2022

I think this is now ready for reviewers' eyes?

@bryanwweber
Copy link
Member

@rwest @ssun30 If so, please hit the "Ready for review" button! 😄

@ssun30 ssun30 marked this pull request as ready for review February 16, 2022 14:21
@bryanwweber
Copy link
Member

Beyond, there are missing empty lines at the end of many files, as well as some spurious Windows line-breaks (shown below as ^M) that you're likely already aware of. There likely is a setting in your code editor that can take care of these minor formatting issues. I'm definitely looking forward to seeing the final PR!

@ssun30 Please see this comment from @ischoegl above and address those comments before we move further with the review! Thanks 😄

@ssun30
Copy link
Contributor Author

ssun30 commented Mar 2, 2022

Beyond, there are missing empty lines at the end of many files, as well as some spurious Windows line-breaks (shown below as ^M) that you're likely already aware of. There likely is a setting in your code editor that can take care of these minor formatting issues. I'm definitely looking forward to seeing the final PR!

@ssun30 Please see this comment from @ischoegl above and address those comments before we move further with the review! Thanks 😄

These should be resolved now.

Copy link
Member

@ischoegl ischoegl left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ssun30 … thanks for addressing!

could you please fix the commits pertaining to libexecstream (this is an external package; it looks like you accidentally added/changed something there)?

@ssun30
Copy link
Contributor Author

ssun30 commented Mar 2, 2022

@ssun30 … thanks for addressing!

could you please fix the commits pertaining to libexecstream (this is an external package; it looks like you accidentally added/changed something there)?

It doesn't seem I changed these files in libexecstream and data/gri30_highT.cti. What's really weird is whenever I commit some changes, I see these specific files are modified even though I didn't do anything to them.

I want to fix the commit but I'm running into a consistent problem with letter capitalization that I couldn't recall how I resolved last time. I'll ask Chris who knows the solution.

@ssun30 ssun30 force-pushed the matlab_toolbox branch 2 times, most recently from e4711e9 to c7a6f18 Compare March 4, 2022 21:34
@ssun30
Copy link
Contributor Author

ssun30 commented Mar 4, 2022

@ssun30 … thanks for addressing!

could you please fix the commits pertaining to libexecstream (this is an external package; it looks like you accidentally added/changed something there)?

Fixed!

Copy link
Member

@bryanwweber bryanwweber left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ssun30 Thanks for all your work on this so far! I've left a few comments here that I think will apply to the entire set of changes. I didn't get a chance to look through all the files yet. I'll try to do some more over time, but you should get started on the changes I've got here now and keep updating the PR. Thanks!

interfaces/Matlab_Toolbox_Revamp/Class/Domain1D.m Outdated Show resolved Hide resolved
interfaces/Matlab_Toolbox_Revamp/Class/Domain1D.m Outdated Show resolved Hide resolved
interfaces/Matlab_Toolbox_Revamp/Class/Domain1D.m Outdated Show resolved Hide resolved
interfaces/Matlab_Toolbox_Revamp/Class/FlowDevice.m Outdated Show resolved Hide resolved
interfaces/Matlab_Toolbox_Revamp/Class/FlowDevice.m Outdated Show resolved Hide resolved
interfaces/Matlab_Toolbox_Revamp/Class/Mixture.m Outdated Show resolved Hide resolved
interfaces/Matlab_Toolbox_Revamp/Class/Mixture.m Outdated Show resolved Hide resolved
interfaces/Matlab_Toolbox_Revamp/Class/Mixture.m Outdated Show resolved Hide resolved
interfaces/Matlab_Toolbox_Revamp/Class/Reactor.m Outdated Show resolved Hide resolved
interfaces/Matlab_Toolbox_Revamp/Class/Reactor.m Outdated Show resolved Hide resolved
Copy link
Member

@ischoegl ischoegl left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ssun30 ... like @bryanwweber I appreciate your continued efforts on this PR!

I have two comments:

  1. Could you update your toolbox path? interfaces/Matlab_Toolbox_Revamp is ok for work-in-progress, but it probably should be renamed
  2. More importantly, one of my main questions is about how you have been testing the toolbox thus far - do you have any test files already implemented?

Regarding my second question, I am asking as much of Cantera is covered by extensive unit tests. Since the previous MATLAB toolbox was implemented (which has some rudimentary tests), Mathworks has come up with much better testing frameworks, see here. While I have not checked into this, Mathworks also supports runners on GitHub, see run-matlab-tests action. Overall, from a maintenance perspective, it would be great if you could add some basic testing. It doesn't have to be highly detailed, but even a relatively basic test suite would go a long way.

As an aside, there are many open issues for the existing MATLAB toolbox, see list of open MATLAB issues. It would be great if you could reference those that can be closed based on your ongoing work.

@bryanwweber
Copy link
Member

2. More importantly, one of my main questions is about how you have been testing the toolbox thus far - do you have any test files already implemented?

Thanks @ischoegl! @ssun30 I forgot to mention this point in my comment earlier. I'm having a hard time seeing how the new interface will work. Can you update a couple of the old samples to use the new syntax? It doesn't have to be all of them at the moment, but 2-3 would be great to see how the new interface compares to the other.

As far as adding some tests, the existing tests are here: https://github.com/Cantera/cantera/tree/main/test/matlab You can run them locally by doing scons test-matlab. If you add a new folder there, perhaps called matlab-new with similar tests, that'd be great. I can help you work out how to set it up in SCons.

@rwest
Copy link
Member

rwest commented Mar 5, 2022

I thought you had rewritten all the examples @ssun30. Are they not in this PR?

@ischoegl
Copy link
Member

ischoegl commented Mar 5, 2022

Thanks @bryanwweber … regarding the old unit tests, I believe it will make sense to move away from matlab_xunit (or at least upgrade), as it is 10 years old / several versions behind, and is not necessarily recommended, see comment here.

@ischoegl
Copy link
Member

ischoegl commented Mar 5, 2022

I thought you had rewritten all the examples @ssun30. Are they not in this PR?

From what I can tell (caveat: I don’t have MATLAB installed), samples in the Examples folder do use the new syntax, so I assume that running these will hit some of the core features. But ideally, there should be a mechanism that re-executes essential bits every time a PR is tested. That way, there won’t be any nasty surprises.

On a different note regarding deprecations, it probably makes sense to eliminate everything that is already deprecated elsewhere in the upcoming Cantera 2.6.

Copy link
Member

@bryanwweber bryanwweber left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @ssun30! Sorry I didn't see these files @rwest. Can these be moved to the samples folder in the root of the repository, in a new directory?

interfaces/Matlab_Toolbox_Revamp/Examples/conhp.m Outdated Show resolved Hide resolved
@ssun30 ssun30 changed the title Matlab toolbox revamp (WIP) Matlab toolbox revamp Mar 7, 2022
Copy link
Member

@ischoegl ischoegl left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wanted to bring up one additional point, which was originally raised by @decaluwe in Cantera/enhancements#102, specifically here: as there already are drastic/breaking changes in the MATLAB toolbox syntax, the following should be given some thought:

  1. Avoid method names where MATLAB follows a convention different from other API's. Example: ThermoPhase.atomicMasses (proposed MATLAB) vs. ThermoPhase.atomic_weights (Python); C++ uses scalar atomicWeight getters.
  2. There is the option to make things completely consistent with the Python API by introducing snake_case property/method names. I pointed out a couple of instances, but this would apply to the entire toolbox.
  3. Beyond, both Python and MATLAB support methods and properties for classes. It would be nice if both API’s would use a consistent approach.

Beyond, as in the 'old' MATLAB toolbox there are still substantial gaps of functionality compared to the Python API. This is to a certain extent a function of an incomplete C API, but should be addressed eventually.

interfaces/Matlab_Toolbox_Revamp/1D/AxiStagnFlow.m Outdated Show resolved Hide resolved
interfaces/Matlab_Toolbox_Revamp/Class/ThermoPhase.m Outdated Show resolved Hide resolved
interfaces/Matlab_Toolbox_Revamp/Class/ThermoPhase.m Outdated Show resolved Hide resolved
@bryanwweber
Copy link
Member

There is the option to make things completely consistent with the Python API by introducing snake_case property/method names. I pointed out a couple of instances, but this would apply to the entire toolbox.

Personally, I think each interface should represent idiomatic code in that language. As such, in my opinion, the Matlab interface should use camelCase as that is the most common recommendation for Java-like code. There is also this unofficial document: https://www.mathworks.com/matlabcentral/fileexchange/45047-matlab-style-guidelines-cheat-sheet which seems to have some good advice.

ssun30 and others added 23 commits May 11, 2023 11:29
…tion guide.

Removed most nested IF statements.
Copy link
Member

@speth speth left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I pushed an update to eliminate a lot of unnecessary "churn" from the commit history, as well as fixing end-of-line whitespace and a number of typos.

I think we can discuss the next steps in the Enhancements repo, either as part of Cantera/enhancements#102 or a new topic.

@speth speth dismissed bryanwweber’s stale review May 11, 2023 18:37

Dismissing per Bryan's request.

@speth speth merged commit 700bf42 into Cantera:main May 11, 2023
@rwest
Copy link
Member

rwest commented May 11, 2023

Wow. Thank you all!

@ischoegl
Copy link
Member

ischoegl commented Jun 2, 2023

Tagging Cantera/enhancements#177

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
No open projects
Development

Successfully merging this pull request may close these issues.

Re-implement the Matlab interface
5 participants