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

Migrate "Science" docs #1647

Merged
merged 16 commits into from
Jan 9, 2024
Merged

Migrate "Science" docs #1647

merged 16 commits into from
Jan 9, 2024

Conversation

speth
Copy link
Member

@speth speth commented Nov 20, 2023

Changes proposed in this pull request

  • Migrate content from the cantera-website "Science" section into the versioned Sphinx documentation
  • Significantly revise "species thermo" documentation
    • document all SpeciesThermoInterpType models (e.g. NASA polynomials), models derived from PDSS (e.g. temperature-dependent density), and models where the parameters are processed directly by the ThermoPhase model (e.g. Peng-Robinson).
    • Try to bridge the gap between the typical definition of "standard state" and Cantera's mixed usage of "reference state" and "standard state".
  • Reorganize reactor network docs to split out a tutorial (now in the "User Guide" section) and a description of the CVODES inner workings (now in the "Develop" section).

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

Continues work on Cantera/enhancements#178
Closes Cantera/cantera-website#249

If applicable, provide an example illustrating new features this pull request is introducing

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

@speth
Copy link
Member Author

speth commented Nov 20, 2023

Requesting @decaluwe's review specifically for the updates to the "species thermo" and "standard state" docs.

@decaluwe
Copy link
Member

Thanks @speth --will get to it! Excited to see this come through (and wish I had done more to help get it there).

@speth speth requested a review from a team December 6, 2023 15:40
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 for all this work @speth! I'm probably not going to have time to review this all again, so please feel free to incorporate or discard these comments at your discretion. If you have any questions, I'm happy to help clarify 😸

doc/sphinx/develop/reactor-integration.md Outdated Show resolved Hide resolved
doc/sphinx/develop/reactor-integration.md Outdated Show resolved Hide resolved
doc/sphinx/develop/reactor-integration.md Outdated Show resolved Hide resolved
doc/sphinx/develop/reactor-integration.md Show resolved Hide resolved
doc/sphinx/develop/reactor-integration.md Outdated Show resolved Hide resolved
doc/sphinx/userguide/reactor-tutorial.md Outdated Show resolved Hide resolved
doc/sphinx/userguide/reactor-tutorial.md Outdated Show resolved Hide resolved
doc/sphinx/userguide/reactor-tutorial.md Outdated Show resolved Hide resolved
doc/sphinx/userguide/reactor-tutorial.md Outdated Show resolved Hide resolved
doc/sphinx/userguide/reactor-tutorial.md Outdated Show resolved Hide resolved
Copy link
Member

@decaluwe decaluwe left a comment

Choose a reason for hiding this comment

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

Thanks @speth for this massive undertaking. I've added a number of thoughts. The two most relevant:

  1. The phase thermo sections have a lot less detail than the kinetics sections. I think my preference would be to get this merged before adding more on top, but if you'd rather add it in now (assuming you want to at all), lmk and I can help.
  2. The reference vs. standard state. I added some thoughts to tune the wording. Long term, I think we can get rid of the non-standard use of standard state in RedlichKwong and PengRobinson, assuming I am correct that they are the only two that use it. In those two is it just a minor mathematical convenience and can be pretty easily removed/adjusted. That said I do like "reference state" better than "standard state," generally, since a little digging shows that there is no single "standard" that applies across fields. The user provided info really is just a reference: "We know the properties well at this one condition." But that is a different windmill for a different day, I suppose.

doc/sphinx/develop/reactor-integration.md Outdated Show resolved Hide resolved
doc/sphinx/reference/kinetics/rate-constants.md Outdated Show resolved Hide resolved
doc/sphinx/reference/kinetics/rate-constants.md Outdated Show resolved Hide resolved
doc/sphinx/reference/kinetics/rate-constants.md Outdated Show resolved Hide resolved
doc/sphinx/reference/thermo/phase-thermo.md Show resolved Hide resolved
doc/sphinx/reference/thermo/phase-thermo.md Outdated Show resolved Hide resolved
doc/sphinx/reference/thermo/species-thermo.md Outdated Show resolved Hide resolved
doc/sphinx/reference/thermo/species-thermo.md Show resolved Hide resolved
doc/sphinx/reference/thermo/species-thermo.md Show resolved Hide resolved
speth and others added 15 commits January 5, 2024 18:54
Expand the description to cover both the calculation of standard-state
cp/h/s and the models that provide parameters affecting the equation
of state.

Also try to provide a description of the difference between the typical
definition of standard state and the distinction that Cantera sometimes
tries to make between "reference state" and "standard state" properties.
Split among science reference, an introductory tutorial, and more
detailed information in the developer guide.
Able to update now that MyST-NB 1.0 has been released

Also build docs with a newer version of Python
Co-authored-by: Bryan Weber <bryan.w.weber@gmail.com>
Co-authored-by: Steven C. DeCaluwe <steven.decaluwe@gmail.com>
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.

Thank you, @speth! All good from my side. As I didn’t do heavy lifting to review, it’s not my place to approve though.

@speth speth merged commit fb53e96 into Cantera:main Jan 9, 2024
49 checks passed
@speth speth deleted the science-docs branch July 23, 2024 15:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

'piecewise-Gibbs' missing from Science section
4 participants