WIP: Reorganize Science section.

[decaluwe]

Related to https://github.com/Cantera/enhancements/issues/6 and https://github.com/Cantera/enhancements/issues/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]

Thanks, @decaluwe! Two thoughts:

1. 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).
2. 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.

[decaluwe]

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]

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.

[decaluwe]

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

1. 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)).
2. 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]

@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]

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

[bryanwweber]

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

[decaluwe]

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?

[speth]

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]

Thanks, @speth -- worked like a charm.

Okay, @bryanwweber -- have at it 😉

[decaluwe]

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

[bryanwweber]

Wahoo in it goes!

[decaluwe]

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