YAML format documentation #91

speth · 2019-10-09T20:59:57Z

Move all CTI-specific documentation out of the Science section and into the CTI guide. The Science docs now link to the CTI docs where appropriate.
Add an analogue to the CTI "Defining Phases" guide for the YAML format
Link from relevant sections of the "Science" docs to the YAML API docs

I have also pushed this PR branch to the testing branch, so this is currently live at https://testing.cantera.org (specifically, https://testing.cantera.org/tutorials/yaml/defining-phases.html)

pages/tutorials/yaml/phases.rst

speth · 2019-12-10T00:31:56Z

I'm having a little trouble with the :ref:-style links to the YAML documentation for cases where there are capital letters in the section name (e.g. pressure-dependent-Arrhenius). It seems that to get the "website" to link to these targets, it's necessary to use all lowercase letters, but the case sensitive name within the Sphinx docs. Any idea if there's an easy fix for this, @bryanwweber?

bryanwweber · 2019-12-10T03:34:44Z

I don't see any str.lowers anywhere 😢 (I assume you checked for those anyways 😂 ). My first guess is that this is buried somewhere deep in the docutils internals. Can you check the cache folder for ref_targets and see how the labelid is saved in there?

speth · 2019-12-10T04:36:12Z

They've already been lowercased at that point.

speth · 2019-12-10T05:03:19Z

Aha, I figured it out - this goes the other way around. According to the Docutils docs (http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#reference-names) the names are supposed to be case insensitive, and be normalized to lowercase. It shouldn't be looking for the capitalized reference name in the first place.

Needed to be updated after setting Doxygen to use subdirectories

speth · 2019-12-13T20:04:24Z

I think this is ready for review. I've also pushed this to the testing branch, so this now corresponds to the content available at https://testing.cantera.org.

@ischoegl I'd like to request your review here as well -- with this documentation completed, this is a good opportunity for feedback on the YAML format in general.

bryanwweber

Looks mostly great, thanks @speth!

pages/tutorials/yaml/defining-phases.rst

pages/tutorials/yaml/phases.rst

pages/tutorials/yaml/yaml-format.rst

ischoegl

As @bryanwweber mentioned, this looks really good.

Just had a couple of comments. Thanks for creating something really useful (both YAML/AnyMap input and great documentation).

pages/science/reactions.rst

ischoegl · 2019-12-20T01:17:39Z

pages/science/reactions.rst

+
+An SRI falloff function may be specified in the CTI format using the
+:cti:class:`SRI` directive, or in the YAML format using the
+:ref:`SRI <sec-yaml-falloff>` field in the entry.

 Chemically-Activated Reactions


I still believe that the minute difference to fall-off doesn't warrant a separate reaction type, see Cantera/cantera#751

Note: Looks like in some instances, the lines I'm referring to appear at the bottom! (apologies)

I'm going to leave this as-is for now. Obviously, depending on the resolution of that issue, this documentation may need to be revised.

ischoegl · 2019-12-20T01:22:18Z

pages/science/reactions.rst

+Chebyshev reactions can be defined in the CTI format using the
+:cti:class:`chebyshev_reaction` entry, or in the YAML format using the
+:ref:`Chebyshev <sec-yaml-Chebyshev>` reaction ``type``.
+
 Surface Reactions


Should there be a mention of electrochemical reactions (see Cantera/cantera#747; I'm still not convinced that automatic detection is a clean implementation, which however was the consensus from Cantera/cantera#750)

Yes, there certainly should, but I'm not trying to resolve all of the deficiencies of the "science" section of the website in this PR.

ischoegl · 2019-12-20T01:39:16Z

pages/science/species.rst

-conversion. The numeric field values should all be entered as pure numbers, with
-no attached units string.
+effect of each species on the transport properties of the phase. Currently,
+ideal-gas transport property models are implemented.


Is this still true? There appears to be a transport model for water ...

Well, the only ones for which species-level transport coefficients are specified are for gases.

ischoegl · 2019-12-20T01:43:20Z

pages/tutorials/input-files.rst

 - Use one of the pre-existing input files provided with Cantera
 - Convert a pre-existing mechanism from Chemkin (CK) format to Cantera (CTI) format
 - Create your own CTI file, either from scratch (not recommended) or by editing an existing file
+- Create your own YAML file from scratch or by editing an existing file *(New in
+  Cantera 2.5)*


Shouldn't conversion from CK to YAML and CTI/XML to YAML be added here as well? (it's described below, but not mentioned here)

Yes, that was missing. I've added a new section with a ck2yaml tutorial, which is essentially a duplicate of the ck2cti tutorial.

ischoegl · 2019-12-20T01:55:04Z

pages/tutorials/yaml/reactions.rst

+    - :ref:`elementary <sec-yaml-elementary>`
+    - :ref:`three-body <sec-yaml-three-body>`
+    - :ref:`falloff <sec-yaml-falloff>`
+    - :ref:`chemically-activated <sec-yaml-chemically-activated>`


see previous comment: I think this could be handled more efficiently by adding a boolean chemically-activated field to falloff reactions.

Pending Cantera/cantera#751

pages/tutorials/yaml/reactions.rst

ischoegl · 2019-12-20T02:00:27Z

pages/tutorials/yaml/species.rst

+=======
+
+A species entry in Cantera is used to specify the name, composition,
+thermodynamic, and transport properties of an individual species.


Should Cantera/enhancements#14 be considered for 2.5.0?

Sure, I'd consider including an implementation if someone made a PR, but I don't think it's a blocker for the release.

pages/tutorials/yaml/species.rst

pages/tutorials/yaml/yaml-format.rst

speth · 2020-01-03T21:19:52Z

I think I've addressed all the issues comments except for a few related to open PRs on Cantera/cantera. I've also pushed the updated branch to https://testing.cantera.org.

pages/compiling/installation-reqs.rst

ischoegl · 2020-01-08T22:43:22Z

One easily addressed comment: I noticed that there's no YAML input file link in the 'Other Documentation' box on the index page.

[Also, searching for yaml does not yield results, although this may be due to testing status.]

speth · 2020-01-08T23:10:28Z

One easily addressed comment: I noticed that there's no YAML input file link in the 'Other Documentation' box on the index page.

[Also, searching for yaml does not yield results, although this may be due to testing status.]

Even on the "testing" site, that main API docs page is for the stable release. If you follow the "Development Version" link further down the page under "Need something else?", the search will find all of the YAML API docs for the development version, and you will see links to YAML documentation under the "Other Documentation" section.

bryanwweber · 2020-03-10T01:48:37Z

@speth Wow! Was definitely not expecting to change all e.g. and i.e. that you did. Thank you! I probably should have explained about the shift from "" to bold - I think the quotes can be interpreted in strange ways, they can come across as scare quotes or something like that (I've learned this from writing for other places). Hence, IMO we should use either bold or italics to denote a term that users should be aware of, like a textbook I suppose. Italics are generally used for emphasis, so terms get bolded the first time they're used.

I'll take a look at the rest of this tomorrow. Thanks again!

bryanwweber

One small change and responding to a comment. Thanks again @speth

pages/science/species.rst

pages/tutorials/yaml/phases.rst

speth force-pushed the yaml branch from edaa160 to 5197bb9 Compare October 9, 2019 21:08

speth commented Oct 10, 2019

View reviewed changes

pages/tutorials/yaml/phases.rst Outdated Show resolved Hide resolved

speth commented Oct 10, 2019

View reviewed changes

pages/tutorials/yaml/phases.rst Outdated Show resolved Hide resolved

speth force-pushed the yaml branch 4 times, most recently from f2c7560 to d69cb4a Compare October 15, 2019 02:26

speth changed the title ~~[WIP] YAML format documentation~~ YAML format documentation Oct 15, 2019

speth requested a review from bryanwweber October 15, 2019 17:27

speth mentioned this pull request Dec 4, 2019

[Doc] Make YAML section labels more distinctive Cantera/cantera#764

Merged

speth force-pushed the yaml branch from 741ea16 to cda963e Compare December 10, 2019 00:28

speth added 2 commits December 13, 2019 12:04

Add link to YAML reference documentation

197d584

Fix broken link to class ThermoPhase documentation

716da1a

Needed to be updated after setting Doxygen to use subdirectories

speth force-pushed the yaml branch 2 times, most recently from 2e5b8b1 to fff7e8e Compare December 13, 2019 19:50

bryanwweber requested changes Dec 20, 2019

View reviewed changes

ischoegl reviewed Dec 20, 2019

View reviewed changes

speth mentioned this pull request Dec 23, 2019

[WIP] Commit yaml files Cantera/cantera#768

Merged

3 tasks

speth mentioned this pull request Jan 3, 2020

Add vapor fraction as option for setting state in YAML files Cantera/cantera#784

Merged

3 tasks

speth force-pushed the yaml branch from fff7e8e to 45383f2 Compare January 3, 2020 17:36

speth requested a review from bryanwweber January 3, 2020 21:18

bryanwweber reviewed Jan 7, 2020

View reviewed changes

pages/compiling/installation-reqs.rst Show resolved Hide resolved

speth added 13 commits March 9, 2020 19:18

Change CSS for literal strings to make them stand out more

9835faf

Fix math formatting in Python / Matlab tutorials

d0b558b

Use one blank line before section headers

e0b39ab

Re-order composition and state paragraphs

620161a

Add ck2yaml tutorial

684026f

Add basic tutorial for cti2yaml and ctml2yaml

954df62

Add short descriptions for all models listed in the YAML tutorial

9ad3144

Document dependency on ruamel.yaml

8b82b1f

Clarify that main documentation page is for stable version

2ce56e8

Add Q / vapor-fraction to list of valid state variables

717af6f

Fix bad formatting caused by incorrect indentation

08647ed

Eliminate Latin abbreviations i.e. and e.g.

62ba99c

Avoid impression that charge can be inferred from species name

bb74653

speth force-pushed the yaml branch from 605595d to 611458d Compare March 10, 2020 00:07

speth requested a review from bryanwweber March 10, 2020 00:07

bryanwweber approved these changes Mar 10, 2020

View reviewed changes

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

pages/tutorials/yaml/phases.rst Outdated Show resolved Hide resolved

speth added 10 commits March 10, 2020 15:00

Minor formatting / typo / wording updates

f01ec3b

Extend description of Arrhenius expression

43aaa0f

Fix missing and incorrect use of \mathrm

7d2bdba

Replace dangling "chapter" reference from old CTI guide

d4fd08c

Put YAML format first

02f16b8

Revise description of Arrhenius expressions in YAML docs

2f7139b

Always use just "R" for the universal gas constant

1612421

Bold YAML file terminology

08a8291

Formatting changes for chemically-activated reactions

f355aad

Document --quiet and --extra options of ck2yaml

759bc09

speth force-pushed the yaml branch from 611458d to 759bc09 Compare March 10, 2020 19:10

speth merged commit 4fead69 into Cantera:master Mar 11, 2020

speth mentioned this pull request Jun 30, 2020

Some text is duplicated between C++ documentation and science #20

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

YAML format documentation #91

YAML format documentation #91

speth commented Oct 9, 2019 •

edited

speth commented Dec 10, 2019

bryanwweber commented Dec 10, 2019

speth commented Dec 10, 2019

speth commented Dec 10, 2019

speth commented Dec 13, 2019

bryanwweber left a comment

ischoegl left a comment

ischoegl Dec 20, 2019

ischoegl Dec 20, 2019

speth Jan 2, 2020

ischoegl Dec 20, 2019

speth Jan 2, 2020

ischoegl Dec 20, 2019

speth Jan 2, 2020

ischoegl Dec 20, 2019

speth Jan 2, 2020

ischoegl Dec 20, 2019

speth Jan 3, 2020

ischoegl Dec 20, 2019

speth Jan 3, 2020

speth commented Jan 3, 2020

ischoegl commented Jan 8, 2020 •

edited

speth commented Jan 8, 2020

bryanwweber commented Mar 10, 2020

bryanwweber left a comment

YAML format documentation #91

YAML format documentation #91

Conversation

speth commented Oct 9, 2019 • edited

speth commented Dec 10, 2019

bryanwweber commented Dec 10, 2019

speth commented Dec 10, 2019

speth commented Dec 10, 2019

speth commented Dec 13, 2019

bryanwweber left a comment

Choose a reason for hiding this comment

ischoegl left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

speth commented Jan 3, 2020

ischoegl commented Jan 8, 2020 • edited

speth commented Jan 8, 2020

bryanwweber commented Mar 10, 2020

bryanwweber left a comment

Choose a reason for hiding this comment

speth commented Oct 9, 2019 •

edited

ischoegl commented Jan 8, 2020 •

edited