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

YAML format documentation #91

Merged
merged 45 commits into from
Mar 11, 2020
Merged

YAML format documentation #91

merged 45 commits into from
Mar 11, 2020

Conversation

speth
Copy link
Member

@speth speth commented Oct 9, 2019

  • 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)

@speth speth force-pushed the yaml branch 4 times, most recently from f2c7560 to d69cb4a Compare October 15, 2019 02:26
@speth speth changed the title [WIP] YAML format documentation YAML format documentation Oct 15, 2019
@speth
Copy link
Member Author

speth commented Dec 10, 2019

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
Copy link
Member

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
Copy link
Member Author

speth commented Dec 10, 2019

They've already been lowercased at that point.

@speth
Copy link
Member Author

speth commented Dec 10, 2019

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.

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

speth commented Dec 13, 2019

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.

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.

Looks mostly great, thanks @speth!

pages/tutorials/yaml/defining-phases.rst Outdated Show resolved Hide resolved
pages/tutorials/yaml/phases.rst Show resolved Hide resolved
pages/tutorials/yaml/phases.rst Show resolved Hide resolved
pages/tutorials/yaml/phases.rst Show resolved Hide resolved
pages/tutorials/yaml/phases.rst Outdated Show resolved Hide resolved
pages/tutorials/yaml/yaml-format.rst Show resolved Hide resolved
pages/tutorials/yaml/yaml-format.rst Outdated Show resolved Hide resolved
pages/tutorials/yaml/yaml-format.rst Outdated Show resolved Hide resolved
pages/tutorials/yaml/yaml-format.rst Outdated Show resolved Hide resolved
pages/tutorials/yaml/yaml-format.rst 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.

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 Outdated Show resolved Hide resolved

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
Copy link
Member

Choose a reason for hiding this comment

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

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

Copy link
Member

Choose a reason for hiding this comment

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

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

Copy link
Member Author

Choose a reason for hiding this comment

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

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.

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
Copy link
Member

Choose a reason for hiding this comment

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

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)

Copy link
Member Author

Choose a reason for hiding this comment

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

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.

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.
Copy link
Member

Choose a reason for hiding this comment

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

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

Copy link
Member Author

Choose a reason for hiding this comment

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

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

Comment on lines 19 to 24
- 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)*
Copy link
Member

Choose a reason for hiding this comment

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

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)

Copy link
Member Author

Choose a reason for hiding this comment

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

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

- :ref:`elementary <sec-yaml-elementary>`
- :ref:`three-body <sec-yaml-three-body>`
- :ref:`falloff <sec-yaml-falloff>`
- :ref:`chemically-activated <sec-yaml-chemically-activated>`
Copy link
Member

Choose a reason for hiding this comment

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

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

Copy link
Member Author

Choose a reason for hiding this comment

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

pages/tutorials/yaml/reactions.rst Outdated Show resolved Hide resolved
=======

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

Choose a reason for hiding this comment

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

Should Cantera/enhancements#14 be considered for 2.5.0?

Copy link
Member Author

Choose a reason for hiding this comment

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

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 Outdated Show resolved Hide resolved
pages/tutorials/yaml/yaml-format.rst Outdated Show resolved Hide resolved
@speth
Copy link
Member Author

speth commented Jan 3, 2020

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.

@ischoegl
Copy link
Member

ischoegl commented Jan 8, 2020

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
Copy link
Member Author

speth commented Jan 8, 2020

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
Copy link
Member

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

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.

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

pages/science/species.rst Outdated Show resolved Hide resolved
pages/tutorials/yaml/phases.rst Outdated Show resolved Hide resolved
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.

3 participants