WIP: Reorganize Science section. #179

decaluwe · 2022-03-22T10:41:09Z

Related to Cantera/enhancements#6 and Cantera/enhancements#68.

Change the structure of the Science section so we can more easily add important details.

Putting this general structure out here now for comment. If people are on board, it will be relatively straightforward to first re-populate this with what the Science section already has. After that, we will have a more intuitive place and structure for adding more details.

ischoegl · 2022-03-22T12:38:27Z

Thanks, @decaluwe! Two thoughts:

On the upside, having the science section exactly map Thermo / Kinetics / Transport would be nice as it neatly maps the C++ core implementation (as well as other API's).
On the flipside, it isn't entirely clear to me that differentiating thermo-aspects and transport aspects of Species is necessarily intuitive.

From a user perspective, the differentiation in (1) is not obvious as this really only happens 'under the hood'. The thought-process in (2) circles back to what is currently already in place.

Ultimately, a user mostly sees Solutions, which are built from Species and Reaction, so it makes sense to feature them at the top level. Personally, I view Solution mostly equivalent to Phase (if it weren't for PureFluid, which imho really should be Mixture). ~~So I'd vote to stick with the current organization.~~ Just my 2 cents of course!

PS: As an afterthought, the two viewpoints are not mutually exclusive. I do appreciate the thermo/kinetics classification after all, especially as it would help shed light on the differentiation of SpeciesThermo and ThermoPhase.

PPS: To expand on my point above ... if you explain how species and reactions (which are aspects of how things are implemented) map to Thermo / Kinetics / Transport on the main landing page, I'd support (1) after all as this is how the Science aspect actually works.

bryanwweber

Thanks @decaluwe! I like this reformatting to be around the scientific topics rather than the implementation details. I agree with @ischoegl that we need to include the relationship to the implementation somewhere although I'm fine with deferring the decision about where that should end up exactly. The line comments below are hopefully more general thoughts (other than the few typos) that I hope can be applied going forward.

pages/science/index.rst

pages/science/thermodynamics.rst

decaluwe · 2022-03-22T22:32:05Z

Thanks, @ischoegl and @bryanwweber! @ischoegl I agree that there will be certain redundancies, in talking about species - phase interactions between transport and thermo. But I think that burden falls on the author, while not really burdening a reader. My thought for this is sort of like a companion to the API documentation, but for the theory. Somebody consulting this will be seeking out a specific bit of theory for a calculation they are doing. Organizing it by thermo / kinetics / transport, I think, gives them an intuitive way to downselect/filter.

I'd actually like to make what is currently there a little less like the content at https://cantera.org/tutorials/input-files.html, and make this a stopping point purely for those wanting to know the theory. Some of the stuff at the top of the "species" page, in particular, doesn't really qualify as "theory," to me...

@bryanwweber thanks for the input and helpful suggestions! Some of the comments about wanting more specific info I'm a little ambivalent on - the intent is to have the users click on the cards for the actual explanation, but just wanted to give them an overview, here. But I'll take a crack at it and see if I can address your concerns. Regarding P-v-T, I can add more detail, but to me an EoS does two things that are somewhat loosely related: (i) an overall governing equation for how P, v (or rho), and T are related, which most would actually call the equation of state, and (ii) a set of relationships for more "thermo-y" properties (u, h, s, mu, etc.).

My gut reaction is that I really want the details here to be independent of software implementation (i.e. the reader of this section doesn't care how we store data, organize C++ objects, and pass values around). Thinking about it more, though, we definitely should help the reader relate this theory to the inputs they provide in input files, and to what the software outputs, so it should not be completely divorced.

Anyway, I'll put some more work into this today and see where I get. My goal for now is to recreate what we have in Science in this new structure, and make future additions the subject of their own PRs, providing opportunity for comment along the way.

decaluwe · 2022-03-23T05:17:51Z

Lol, ended up adding much more detail than I thought I would. @ischoegl and @bryanwweber, LMK what you think. If 👍 I'll move forward with repopulating these sections with existing content.

bryanwweber

Thanks @decaluwe! I like where this is heading, looking forward to seeing more 😄

dev-docs.tar.bz2

bryanwweber · 2022-03-23T13:20:23Z

pages/science/thermodynamics.rst

+
+Example: The Ideal Gas Model
+============================
+For a simple example: in the Ideal Gas model, one might use 7-parameter NASA polynomials to specify the species thermodynamics.  These would be used to calculate the reference molar enthalpy :math:`h_k^\circ(T)` and entropy :math:`s_k^\circ(T)` for a given species :math:`k` as a function of temperature :math:`T`:


I love this example! It clarifies quite a bit about what a reader can expect in this section. A few comments about the content:

Should clarify that this is the species ideal gas model.

I think it would also be good to make this more concrete and less hypothetical/passive:

As one example, the Ideal Gas species model and Ideal Gas phase model are a compatible pair. The Ideal Gas species model often uses the 7-parameter NASA polynomials to specify the reference molar enthalpy :math:... and entropy :math:... for a given species as a function of temperature.

At the phase level, the Ideal Gas Law provides the P-v-T relationship, called an equation of state. Maxwell's relations are used to determine other properties from the equation of state. For the Ideal Gas phase model, these reduce to simplified forms: ...

Maybe mentioning Maxwell's relations is too far, I'm not sure... Anyway, something like that is the direction I was thinking.

I think rather than showing the equations here for the NASA polynomials, this can be shortened by linking to that section in the docs elsewhere.

We need to agree on a convention for representing molar-basis vs. mass-basis quantities. In Moran & Shapiro's book, they use \overline{} to represent molar-basis quantities, that is, \overline{u} = \sum_k \overline{u}_k X_k. I see that's what you've done for the gas constant, but then other properties don't have the \overline{}. An alternative is to use R_{u} for the Universal gas constant, but them I'm not sure how to differentiate between mass-basis and molar-basis for other properties... One can tell from whether mass- or mole-fractions are used in the relationship, but that's not always super obvious.

As far as Cantera is concerned, I don't think there is such a thing as an "ideal gas species model", though -- we have the NASA polynomial model for reference state thermodynamic properties, but that is also used for condensed phase species and species in non-ideal gases.

I agree that this would be a good time to settle on a preferred notation for molar quantities, and to document that choice.

Chemically Reacting Flow, which we of course reference frequently, uses capital letters, but I feel like that risks confusion with extensive properties like the total enthalpy of a system (for instance, as used in the reactor model documentation). On the plus side, this notation is the most readable when you're looking at a docstring rather than HTML documentation.

I learned thermo using \hat{} for molar quantities, so have a bit of a soft spot for that option, though I'm not sure what textbooks follow that convention.

For \overline{}, one issue is that it's a lot of extra characters in an expression. For instance, I think even in the example given, this would be \overline{u} = \sum_k \overline{u}_k X_k. And there's also the confusion with the shorter \bar that usually doesn't look as good when actually typeset. Last, I know there are instances where we use bar/overline to indicate an "average" quantity, such as \overline{W} for the mean molecular weight of a mixture.

All of these are used in various places in the Cantera docs.

As far as Cantera is concerned, I don't think there is such a thing as an "ideal gas species model", though

Hmmm, fair enough. Maybe we should choose a different example here, which may work if we limit the equations? Perhaps R-K or P-R?

For instance, I think even in the example given, this would be \overline{u} = \sum_k \overline{u}_k X_k

Yeah, thanks, that was a typo on my part 🤦

I learned thermo using \hat{} for molar quantities, so have a bit of a soft spot for that option, though I'm not sure what textbooks follow that convention.

I like this option. Another thing we can do is configure Mathjax with a macro \molar so this is only defined in one place when we inevitably change our minds sixteen million times.

@bryanwweber -- re: using R-K or P-R.

a. Those would also rely on NASA polynomials, most frequently.

b. My intent here was for simplicity. Show that the species model is used to find the "reference state" properties, and that the phase model uses this reference properties to then find the actual properties. I feel like Ideal Gas is both the most familiar and computationally "cleanest" way to demonstrate this.

However, it seems like you might be after something else - can you clarify?

I'm fine going with \hat. Not sure if I've got the chops to configure Mathjax, but I'll give it a look.

a. Those would also rely on NASA polynomials, most frequently.

Dang.

b. My intent here was for simplicity. Show that the species model is used to find the "reference state" properties, and that the phase model uses this reference properties to then find the actual properties.

That's actually a really good statement of what I think I'm after!

I feel like Ideal Gas is both the most familiar and computationally "cleanest" way to demonstrate this.

Agreed.

However, it seems like you might be after something else - can you clarify?

I'm not totally sure I know, except that I'll know it when I see it 🤪 more seriously, I think this is very close to what I'm thinking of. I think it's tilted a little too far into details in this iteration. My comment was an inaccurate attempt to simplify, and also to connect to the prior point that phase and species thermo models have to be compatible. That last bit, the connection, is probably just asking too much of the text here though, so I think we can drop that attempt. But I do think it needs to be simplified in the direction my comment was trending.

I'll take a look at the configuration for Mathjax when I'm back at my computer in the morning my time 😊 it should be similar to defining a macro in LaTeX, mostly a matter of getting it into the right spot.

Hmm, so does that mean that the molar volume is \hat{v}? That feels... odd, to me, but it technically the consistent approach.

ischoegl

Friendly amendment: I believe Kinetics may be a better top category than Reactions, as some of the kinetics handling goes beyond individual reactions.

pages/science/index.rst

decaluwe · 2022-03-24T03:27:53Z

Okay, I think this stage of what I had in mind is complete, for now.

Please check my ideal gas example. I originally had u_k = u^o_k - PvX_k, but I think the X_k is incorrect/unnecessary (as a check: u for the phase should be recovered from sum_k(u_k * X_k)).
My next step is to move the Transport content out of Thermodynamics/species and into the (currently blank) Transport page. My thinking is that the landing page for Transport will be very similar to what I currently have for Thermo.

decaluwe · 2022-04-06T04:21:43Z

@bryanwweber I think this is ready for a review. Mainly, I don't know if the thermo landing page yet hits the target you had in mind.

As noted in my last commit message, the Transport landing page is a bit underbaked. But as it fully reproduces all the content on the current website, I'd like to stop here, get this PR merged, and then move forward on a fresh PR once the overall structure is approved. This

decaluwe · 2022-04-06T13:00:57Z

I'll resolve the conflict in reactions.rst tomorrow...

bryanwweber · 2022-04-06T14:09:17Z

@decaluwe When you've resolved the conflict can you request a review from me? Thanks 😄

decaluwe · 2022-04-06T18:52:39Z

Hmm, kind of stumped, here, as reactions.rst no longer exists. I've reverted my last commit, locally, to see if the conflict still exists, but can't seem to push the reverted branch to my repo (I just get Everything up-to-date).

Any advice/tips/tricks?

-Slightly more detail on the `Thermodynamics` landing page. -A few small typo fixes - Correcting inconsistencies in the `Species` page with when the `hat` over molar property variables was used. - Replaced the number 0 with `^\circ` to indicate reference properties.

Moves transport property information from the `species` and `phases` pages to the `Transport` landing page. The information on the `Transport` landing page is still insufficient (imho), but as the current changes fully reproduce the information currently on the website, I will address this in a future PR.

speth · 2022-04-06T19:05:28Z

I just rebased this onto the current main branch and pushed it to my fork. You can check that that still has all of your intended changes and then either fetch my branch and do a hard reset of your branch and then force push here, or if you want I can do a force push here and then you can fetch and do the local hard reset.

decaluwe · 2022-04-07T01:05:12Z

Thanks, @speth -- worked like a charm.

Okay, @bryanwweber -- have at it 😉

bryanwweber

Thanks for doing all this @decaluwe! The changes look great so far, just a few typo fixes and minor suggestions for clarity.

pages/science/thermodynamics.rst

pages/science/species-thermo.rst

Update pages/science/thermodynamics.rst Explaining the ideal gas law. - Fix math formatting. - Link to info on Maxwell relations. Update pages/science/species-thermo.rst - Grammar - Fix math formatting. Typo fix on pages/science/transport.rst

decaluwe · 2022-04-08T01:23:08Z

Many thanks, @bryanwweber - just applied all the suggested changes, squashed the commits, and force-pushed. Should be good to go!

bryanwweber · 2022-04-08T02:03:11Z

Wahoo in it goes!

decaluwe · 2022-04-08T02:09:06Z

Awesome! Now on to the next step... 😈

bryanwweber requested changes Mar 22, 2022

View reviewed changes

bryanwweber reviewed Mar 23, 2022

View reviewed changes

ischoegl reviewed Mar 23, 2022

View reviewed changes

pages/science/index.rst Outdated Show resolved Hide resolved

pages/science/index.rst Outdated Show resolved Hide resolved

decaluwe force-pushed the science_update branch from 6ff27c1 to a322132 Compare March 24, 2022 01:45

decaluwe added 5 commits April 6, 2022 15:00

Initial restructure of Science section.

d481521

Copyediting thermodynamics page.

5f70288

Change Reactions page title.

5798b73

decaluwe force-pushed the science_update branch from 1adba69 to fd071f3 Compare April 7, 2022 00:59

decaluwe requested a review from bryanwweber April 7, 2022 01:05

bryanwweber approved these changes Apr 7, 2022

View reviewed changes

decaluwe force-pushed the science_update branch from 81edd0a to 44e1fb4 Compare April 8, 2022 01:22

bryanwweber approved these changes Apr 8, 2022

View reviewed changes

bryanwweber merged commit 1d5ddea into Cantera:main Apr 8, 2022

decaluwe deleted the science_update branch April 8, 2022 02:08

decaluwe mentioned this pull request Apr 8, 2022

Science section re-org Cantera/enhancements#146

Closed

ischoegl mentioned this pull request Apr 24, 2022

Update YAML Sphinx documentation Cantera/cantera#1249

Merged

5 tasks

ischoegl mentioned this pull request May 4, 2022

Version-specific cantera.org release cycle Cantera/enhancements#150

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

WIP: Reorganize Science section. #179

WIP: Reorganize Science section. #179

decaluwe commented Mar 22, 2022

ischoegl commented Mar 22, 2022 •

edited

Loading

bryanwweber left a comment

decaluwe commented Mar 22, 2022 •

edited

Loading

decaluwe commented Mar 23, 2022

bryanwweber left a comment

bryanwweber Mar 23, 2022 •

edited

Loading

speth Mar 23, 2022

bryanwweber Mar 23, 2022 •

edited

Loading

decaluwe Mar 24, 2022

decaluwe Mar 24, 2022

bryanwweber Mar 24, 2022

decaluwe Mar 24, 2022

ischoegl left a comment

decaluwe commented Mar 24, 2022

decaluwe commented Apr 6, 2022 •

edited

Loading

decaluwe commented Apr 6, 2022

bryanwweber commented Apr 6, 2022

decaluwe commented Apr 6, 2022

speth commented Apr 6, 2022

decaluwe commented Apr 7, 2022

bryanwweber left a comment

decaluwe commented Apr 8, 2022

bryanwweber commented Apr 8, 2022

decaluwe commented Apr 8, 2022

WIP: Reorganize Science section. #179

WIP: Reorganize Science section. #179

Conversation

decaluwe commented Mar 22, 2022

ischoegl commented Mar 22, 2022 • edited Loading

bryanwweber left a comment

Choose a reason for hiding this comment

decaluwe commented Mar 22, 2022 • edited Loading

decaluwe commented Mar 23, 2022

bryanwweber left a comment

Choose a reason for hiding this comment

bryanwweber Mar 23, 2022 • edited Loading

Choose a reason for hiding this comment

speth Mar 23, 2022

Choose a reason for hiding this comment

bryanwweber Mar 23, 2022 • edited Loading

Choose a reason for hiding this comment

decaluwe Mar 24, 2022

Choose a reason for hiding this comment

decaluwe Mar 24, 2022

Choose a reason for hiding this comment

bryanwweber Mar 24, 2022

Choose a reason for hiding this comment

decaluwe Mar 24, 2022

Choose a reason for hiding this comment

ischoegl left a comment

Choose a reason for hiding this comment

decaluwe commented Mar 24, 2022

decaluwe commented Apr 6, 2022 • edited Loading

decaluwe commented Apr 6, 2022

bryanwweber commented Apr 6, 2022

decaluwe commented Apr 6, 2022

speth commented Apr 6, 2022

decaluwe commented Apr 7, 2022

bryanwweber left a comment

Choose a reason for hiding this comment

decaluwe commented Apr 8, 2022

bryanwweber commented Apr 8, 2022

decaluwe commented Apr 8, 2022

ischoegl commented Mar 22, 2022 •

edited

Loading

decaluwe commented Mar 22, 2022 •

edited

Loading

bryanwweber Mar 23, 2022 •

edited

Loading

bryanwweber Mar 23, 2022 •

edited

Loading

decaluwe commented Apr 6, 2022 •

edited

Loading