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

Consolidate YAML API documentation in doxygen #1548

Closed
wants to merge 20 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions doc/doxygen/mainpage.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,17 @@
# %Cantera C++ Reference
@mainpage %Cantera Developer API

> **Note:** This is the **%Cantera Developer API** documentation; for general
> information on %Cantera, refer to [**cantera.org**](https://cantera.org).
> The %Cantera source code is hosted on [GitHub](https://github.com/Cantera/cantera).

Use sidebar or menu at the top to view detailed documentation of the code, or
use the following shortcuts:

* Overview of [**Cantera C++ Modules**](modules.html)
* Index of [**Cantera C++ Classes**](classes.html)
* @ref sec-yaml-documentation

A topical overview is provided as follows:
A topical overview of C++ modules is provided as follows:

* @ref solnGroup (interface to %Cantera core objects)
* @ref thermoprops (temperature, pressure, energy, ...)
Expand All @@ -22,5 +24,3 @@ A topical overview is provided as follows:
For fundamental scientific theory used for the implementation of %Cantera, refer to the
[Cantera Science Section](https://cantera.org/science/index.html) of the
[Cantera Website](https://cantera.org).

The %Cantera source code is hosted on [GitHub](https://github.com/Cantera/cantera).
26 changes: 26 additions & 0 deletions doc/doxygen/yaml.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
@page sec-yaml-documentation %Cantera YAML Documentation

> **Note:** %Cantera provides @ref sec-yaml-conversion to generate YAML files
> from Chemkin input data as well as legacy %Cantera formats.

This short guide describes %Cantera YAML input files that define phases and
interfaces for use in %Cantera simulations. Each link below represents an entry
point to the @subpage sec-yaml-api; while you certainly can read them in order,
you can also jump to whichever section addresses your current needs. If you need
tips on troubleshooting the YAML file syntax rules, please look at the
@subpage sec-yaml-format-tutorial.

- <b>@ref sec-yaml-general</b> -
Structure of a %Cantera YAML input file.
- <b>@ref sec-yaml-phases</b> -
For each phase or interface that appears in a problem, a corresponding
entry should be present in the input file(s). Phase entries specify lists
of elements, species and reactions, as well as other relevant parameters.
- <b>@ref sec-yaml-species</b> -
For each species declared as part of a phase description, thermodynamic
properties and other data need to be defined.
- <b>@ref sec-yaml-reactions</b> -
%Cantera supports a number of different types of reactions, including
several types of homogeneous reactions, surface reactions, and
electrochemical reactions. For each, there is a corresponding entry
type.
52 changes: 52 additions & 0 deletions doc/doxygen/yaml/elements.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
@page sec-yaml-elements Element Entries

[TOC]

# Overview

%Cantera provides built-in definitions for the chemical elements, including values for
their atomic weights taken from IUPAC / CIAAW. These elements can be used by specifying
the corresponding atomic symbols when specifying the composition of species. `element`
entries are needed only when defining custom elements that are not standard chemical
elements, or defining specific isotopes.

In order to give a name to a particular isotope or a virtual element
representing a surface site, a custom `element` entry can be used. The
default location for `element` entries is the `elements` section of the
input file. Elements defined in this section will automatically be
considered for addition to phases defined in the same file. Elements can
be defined in other sections of the input file if those sections are
named explicitly in the `elements` field of the phase definition.

**Example:**

```yaml
elements:
- symbol: C13
atomic-weight: 13.003354826
atomic-number: 12
- symbol: O-18
atomic-weight: 17.9991603
```

# Element API Reference

The fields of an `element` entry are:

<b>`symbol`</b>

The symbol used for the element, as used when specifying the
composition of species.

<b>`atomic-weight`</b>

The atomic weight of the element, in unified atomic mass units
(dalton).

<b>`atomic-number`</b>

The atomic number of the element. Optional.

<b>`entropy298`</b>

The standard molar entropy of the element at 298.15 K. Optional.
43 changes: 43 additions & 0 deletions doc/doxygen/yaml/general.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
@page sec-yaml-general General File Structure

The top level of a %Cantera YAML input file is a mapping that defines different input
file sections. Each section consists of a list of mappings that define objects of the
same type, such as reactions, species, phases, or elements. The `phases` section of
an input file contains all of the phase definitions. Multiple sections
containing reaction, species, or element definitions can be used. The
specific names `reactions`, `species`, and `elements` are used as defaults when looking
for @ref sec-yaml-reactions, @ref sec-yaml-species, and @ref sec-yaml-elements to add to
a phase. %Cantera uses SI input units by default, although input values can be
provided using a number of different units, as described in the
@ref sec-yaml-units-default section.

A simple input file has the following structure:

```yaml
description: |-
Optional description of the input file.

# units: optional unit settings used for input data

phases:
- name: spam
thermo: ideal-gas
# Additional fields come after this
- name: green-eggs
thermo: model-name
# Additional fields come after this

species:
- name: A
# Additional fields come after this
- name: B
# Additional fields come after this
- name: C
# Additional fields come after this

reactions:
- equation: A + B <=> C + D
# Additional fields come after this
- equation: A + C <=> 2 D
# Additional fields come after this
```
Loading
Loading